Add Principles for Package Repository Security #37
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||
|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,106 @@ | ||||||||
| # Principles for Package Repository Security | ||||||||
|
|
||||||||
| Authors: [Jack Cable (CISA)](https://github.com/cablej), [Zach Steindler](https://github.com/steiza) | ||||||||
| Last updated: Jan 2024 | ||||||||
|
|
||||||||
| ## Background | ||||||||
|
|
||||||||
| The Securing Software Repositories Working Group (WG) of the OpenSSF has identified a taxonomy of package repositories and a set of principles for their security capabilities. This is intended to be an opinionated document, offering a set of best practices that package repositories should strive to adhere to. | ||||||||
|
|
||||||||
| By package repository (sometimes also called package registry) we're referring to the service that stores and index packages, that users and clients can download packages from. Often users and clients use a CLI tool to download packages, and some ecosystems have multiple popular CLI tools in use. Most of these security capabilities focus on the package repository, but there's also a section on security capabilities the CLI tooling can implement. | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
|
|
||||||||
| The taxonomy is because not all security advice applies to all package repositories. For example, https://proxy.golang.org/ does not manage user accounts, and so has no need of documented account recovery. | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
|
|
||||||||
| The roadmap of security capabilities can then be used by package repositories to assess gaps, put together fundable improvement lists ([like Python Packaging WG](https://github.com/psf/fundable-packaging-improvements/blob/master/FUNDABLES.md)) or write specific grant proposals that reference this guidance. | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
|
|
||||||||
| ## Taxonomy of Package Repositories | ||||||||
|
There was a problem hiding this comment. Another sort of package repository is one that doesn't have user accounts and doesn't allow uploads to it directly, but only mirrors another package repository. I think it would be good to have guidance around ensuring the mirror contains the same data as the source, and perhaps guidance around how the mirror removes content that the source has removed because it's malicious? There was a problem hiding this comment. I sometimes differentiate between "registry" and "repository". A "repository" actually stores the package contents. A "registry" registers a set of packages, but depends on something else to actually store the data. Would it be useful to make this distinction? There was a problem hiding this comment. We settled on "package repositories" in this doc, with the clarification above:
We last talked about this naming distinction back in November (!) where we looked at how different ecosystems referred to themselves, and the conclusion we came to is that there isn't consistent terminology. |
||||||||
|
|
||||||||
| Security capabilities will differ based on the services that the package repository offers. For instance, if the package repository has user accounts, the package repository will need to enforce authentication securely. In this section, we lay out the various relevant aspects of package repositories. | ||||||||
|
|
||||||||
| Does the package repository ... | ||||||||
|
|
||||||||
| ... have user accounts? | ||||||||
| - Yes: then you have to manage things like authentication and account recovery. For example: PyPI | ||||||||
| - No: For example: {index, proxy, sum}.golang.org | ||||||||
|
|
||||||||
| ... accept built packages, do builds on behalf of users, or only host source code? | ||||||||
| - Accept built packages: then you have to provide a way to link packages back to source code and build instructions. For example: npm | ||||||||
| - Builds on behalf of users: For example, Homebrew | ||||||||
| - Only host source code: For example: {index, proxy, sum}.golang.org | ||||||||
|
|
||||||||
| ## Security Capabilities of Package Repositories | ||||||||
|
|
||||||||
| We define 4 levels of security maturity: | ||||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||||
| - Level 0 is defined as having very little security maturity. | ||||||||
| - Level 1 is defined as having basic security maturity. Package repositories support basic security features like multi-factor authentication and allow security researchers to report vulnerabilities. All package management ecosystems should be working towards this level. | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
| - Level 2 is defined as having moderate security. | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
| - Level 3 is defined as having advanced security. These items are more aspirational, especially for smaller package management ecosystems. | ||||||||
|
There was a problem hiding this comment. What does "smaller" mean in this context, both in terms of what is being measured and what threshold of that measurement is considered to be smaller? That is, does this mean:
There was a problem hiding this comment. IMO, it's in terms of the amount of resources available to the registry to add/build these security capabilities.
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
|
|
||||||||
| ### Authentication | ||||||||
|
|
||||||||
| Applies to: package repositories that have user accounts. | ||||||||
|
There was a problem hiding this comment. Currently, crates.io only allows logging in via OAuth with GitHub-- does this count as having user accounts or not? Some of these items don't apply in this case-- crates.io doesn't have passwords, for example. |
||||||||
|
|
||||||||
| - Level 1 | ||||||||
| - The package repository requires users to verify their email address. This ensures that if a user loses access to their account, they are able to recover it. | ||||||||
|
There was a problem hiding this comment.
Suggested change
This decouples verification from the decision whether providing an email address should be a (non-)requirement. If an email is provided it certainly makes sense to verify it. And for many people it's desirable, so it can also make sense to recommend that users provide a valid email address, but in the end there are valid reasons why one might not want to use one. And a user could always opt to sign up with a throwaway email anyway, so enforcing it at signup is not going to really ensure things anyway. There was a problem hiding this comment. I would add: the repository restricts or otherwise disallows using temporary email addresses, the same email address for multiple accounts, etc. There was a problem hiding this comment. I'm opposed to that suggestion. Sometimes I intentionally use temporary email addresses to make a pseudonymous account. Major email providers want to tie your email account to your phone number and such. To avoid that association I use a throwaway to confirm the email validation and then only interact with username+password. Not being able to recover the account is a choice. There was a problem hiding this comment. In my experience, the added burden of spam/malware that comes from allowing temporary email addresses vastly outweighs the benefit of pseudonymous publishing and has a direct effect on the overall security of the repository. A repository team that is overwhelmed with dealing with spam/malware is one that is unable to handle the needs of the legitimate user base, remove spam/malware, or security features in a timely fashion. It's a tradeoff, and the one that improves the security of the repository (which is the goal of this document) is to prohibit temporary email addresses. There was a problem hiding this comment. What do you consider temporary? A newly created account with a randomized address on a freemail provider that doesn't do phone verification is a temporary address for my purposes. There was a problem hiding this comment. Specifically providers that a) generate email addresses on-demand b) don't require authentication (i.e. an "open inbox"). There is a long list that is maintained here based on that criteria: https://github.com/disposable-email-domains/disposable-email-domains There was a problem hiding this comment. I see. I have used domains in both the allow list and in the block list on that repo. |
||||||||
| - The package repository documents their account recovery policy. | ||||||||
|
There was a problem hiding this comment. I would add here "and their account recovery procedures that attempts to reduce the likelihood of the package registry support team being susceptible to social engineering attacks" or something along those lines. |
||||||||
| - The package repository supports strong multi-factor authentication (MFA) via (at minimum) TOTP. Solely offering weaker forms of MFA such as SMS, email, or phone call-based MFA would not meet this requirement. | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
| - The package repository notifies maintainers via email for critical account security changes, such as password changes or disabling multi-factor authentication. This helps users detect if their account has been compromised. | ||||||||
|
There was a problem hiding this comment. This item seems to be implying that there's also action a user can take if their account has been compromised, and I think it's worth making that explicit here-- that is, adding an item like "The package repository has a support team a user can notify if they suspect their account has been compromised. The support team has a SLA of X for locking and investigating the account". |
||||||||
| - The package repository implements account security measures like brute force prevention (even with 2FA attempts) | ||||||||
| - Level 2 | ||||||||
| - To prevent domain resurrection for account takeover via the recovery process, the package repository detects abandoned email domains. This may look like doing a WHOIS lookup on all registered email domains, and removing the ability to recover an account via an email domain that has been abandoned. | ||||||||
|
There was a problem hiding this comment. I would argue that the amount of work/effort to do with this probably moves this to Level 3, at least. It's not immediately obvious via a WHOIS whether a domain has been abandoned, or the rightful owner has just changed registrars or their registration information. I think the "right" way to do this is probably requiring something like ACME for all personal domains, but drawing the line here is challenging as well. There was a problem hiding this comment. Agreed -- WHOIS is unfortunately a pretty unreliable source of ground truth, and has diminishing value in the world of registrar privacy. For better or worse I think the current "state of the art" for email abandonment is bounce detection on delivery, which comes with its own problems. So Level 3 seems appropriate 🙂 There was a problem hiding this comment. +1 to level 3 for this... it's actually quite tricky to do this properly |
||||||||
| - The package repository supports MFA via phishing-resistant means such as WebAuthn | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
| - The package repository requires MFA for packages deemed critical (e.g. top 1% of packages by downloads). | ||||||||
| - The package repository integrates with public leaked credential databases such as Have I Been Pwned to detect when users are using known leaked credentials upon login. If a user has a leaked credential, detected upon login, the package repository prompts them to change it. The package manager checks passwords at registration and prevents users from registering with known leaked credentials. | ||||||||
| - Level 3 | ||||||||
| - The package repository supports passwordless authentication, such as passkeys. | ||||||||
| - The package repository requires MFA for all maintainers. | ||||||||
|
There was a problem hiding this comment. I think blanket requirements introduce friction and may be onerous for casual/new/poor developers that want to publish hobby projects and such. Instead individual packages should be labeled based on their level so that consumers who require higher levels can restrict them without burdening those who do not require this. Generally the commercial/big corporate/government users shouldn't shape registries solely to their needs. There was a problem hiding this comment. Authenticator apps are “proper” just like hardware keys, so i don’t think this is much of a consideration. There was a problem hiding this comment. Authenticator apps may sit on the same machine as the password manager or on devices that are generally more compromisable. So they provide a lower security level than dedicated hardware tokens. AIUI webauthn also supports attestation, which means an authentication provider may choose to lock MFA to a set of trusted (and usually more expensive) vendors. At $work we have to use physical tokens to comply with the security standards of some clients. I forsee such increasingly strict requirements will trickle down to what is deemed critical software infrastructure at some point. Making "compliance levels" a per-package/dependency-tree instead of per-registry thing is a rather simple change that prevents a security ratchet raising the barrier of entry for hobbyists and less affluent developers. There was a problem hiding this comment. Yes, the intent here is that MFA could either be hardware-based or TOTP. What we've seen first-hand at GitHub's MFA rollout is that this has substantially reduced account takeover while also providing global access. There was a problem hiding this comment. The intent is not stated here and I am concerned about this wording contributing to increasingly strict future developments. You're using the word requires here, in the context of an entire platform, not individual projects on that platform. Today it's perhaps only software TOTP. Tomorrow it'll be a select set of expensive, proprietary hardware tokens. In a decade you can only get those tokens by registering with your national ID, perhaps indirectly by them being tied to a TPM in your phone. With this recommendation and ongoing "critical software infrastructure" efforts in the EU I see this as a small step in that direction. A step that is easy to mitigate by not making MFA a platform-wide requirement and instead something that individual projects or organizations can opt into. If a project wants to cater to high-assurance clients then they can require MFA from all their maintainers (similar to signed git commits for example) and proudly display their security posture so that their clients can trust the project. Why would $GOV care that $HOST requires MFA for all users when $GOV only wants to use project $X from $HOST? This requirement just is overly broad. It impacts those who do not share the same values as $GOV. There was a problem hiding this comment. Which still does not substantiate your claim. There was a problem hiding this comment. That's only talking about "risk to attack", which is not the same as "attack vector". I asked you repeatedly to substantiate your claim that this constitutes an attack vector. Information usable to triaging promising targets does not constitute an attack vector. Anyway, I consider their risk-based argument lacking nuance/detailed consideration. There was a problem hiding this comment. I’m not interested in this argument devolving into pedantry; the fact remains that it is simply not viable to require package or org specific MFA, github and npm will be requiring it wholesale imminently, and this requirement is almost certain to remain as-is in this document. There was a problem hiding this comment.
The difference between an attack vector (which usually is something that needs to be fixed) and disclosure about security practices (which is a tradeoff, potentially a tiny one) is significant in my opinion, not pedantry. I had to ask 3 times for you to even reply to this aspect only to dismiss it as pedantry. I would expect more precise discourse when it comes to designing security documentation for global software infrastructure.
Do you mean the requirement or publishing that information? The requirement itself is clearly viable and has been for years because that's what NPM is doing right now without the world going up in fire. There might be reasons to change the policy, but they are likely subtle/marginal ones, that are not about fundamental viability of a policy but about tradeoffs between different viable policies.
Well there was a request for feedback, which is why I'm commenting. Anyway, I will again reiterate my suggestion that package registries should list the "compliance level" of individual packages (or even individual artifacts) instead of chosing "levels" as a baseline for the entire registry. So here's a rephrased proposal:
Suggested change
There was a problem hiding this comment. +1, but also "has a support team to handle account recovery based on a defined process within [some SLO]" There was a problem hiding this comment. I'd say that consistent internal process for account recovery that is robust to social engineering should be Level 2. Possibly also something about having enough forms of identity verification to enable proper recovery. If there isn't robust recovery the robust MFA is useless |
||||||||
| - The package repository requires phishing-resistant MFA for packages deemed critical (e.g. top 1% of packages by downloads). If possible, the package repository supplies security keys to these maintainers. | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
|
|
||||||||
| ### Authorization | ||||||||
|
|
||||||||
| Applies to: package repositories that have user accounts and accept built packages. | ||||||||
|
|
||||||||
| - Level 1 | ||||||||
| - The package repository allows maintainers to provision API keys scoped to specific packages. This allows maintainers to maintain packages via automated workflows without needing to provide their account password. | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
| - API tokens are prefixed with a repository-specific identifier | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
| - Level 2 | ||||||||
| - The package repository supports role-based access control (RBAC) for maintainers, allowing separate roles for managing users and publishing packages. | ||||||||
| - Level 3 | ||||||||
| - The package repository provisions short-lived API tokens via an OpenID Connect (OIDC) token exchange to prevent the need to provision long-lived API keys. Example: [trusted publishers](https://docs.pypi.org/trusted-publishers/) | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
| - The package repository API tokens are integrated into common third-party secret scanning programs. This typically requires using a known prefix or pattern to reduce false-positives. Furthermore, the package repository provides a secret-reporting endpoint for these secret scanning programs to report leaked credentials, which automatically revokes valid credentials. | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
| - The package repository supports providing [build provenance](https://repos.openssf.org/build-provenance-for-all-package-registries) for packages. | ||||||||
|
|
||||||||
| ### General Capabilities | ||||||||
|
There was a problem hiding this comment. Another idea that I think would go under "General Capabilities": a way to view the published artifact on the web without needing to download the package? And more advanced would be a way to view the differences between versions of the artifact? |
||||||||
|
|
||||||||
| Applies to: all package repositories | ||||||||
|
|
||||||||
| - Level 1 | ||||||||
|
There was a problem hiding this comment. IMO another good "Level 1" item here would be: (This is what PyPI does, and it's arguably a precursor step to the "event transparency log" noted under "Level 3".) |
||||||||
| - The package repository has published a vulnerability disclosure policy allowing security researchers to report vulnerabilities affecting the package repository, and receive legal safe harbor when doing so. The package repository should strive to remediate reported vulnerabilities within 90 days. | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
| - The package repository takes steps to prevent typosquatting attacks around package names. This may include namespacing, detecting similar names, or other actions. | ||||||||
| - Level 2 | ||||||||
| - The package repository has an unpublish policy to prevent specific versions of a package from being replaced, and, if a package is deleted, prevent others from reusing the same package name and version. | ||||||||
|
There was a problem hiding this comment. This seems like level 1 tbh. Immutability should be a core requirement for actively maintained packages. I think there is flexibility here for low used packages (as per the npm policy) Tombstoning for deletion isn't really neccessary for those packages with low usage imho, those with high usage should be able to be deleted |
||||||||
| - The package repository allows users to report a package as suspicious or malicious via the registry UI, tooling CLI, and via API. | ||||||||
|
There was a problem hiding this comment. I would add here "and documents the support team procedures and SLA for addressing reports of suspicious or malicious packages" |
||||||||
| - The package repository takes steps to detect malware, including scanning for known malware code snippets and hashes. | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
| - Level 3 | ||||||||
| - Undergo periodic cloud security review (and optionally publish remediations once they are complete) | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
| - The package repository publishes an event transparency log to enable detection of anomalous behaviors (e.g. [replicate.npmjs.com](https://replicate.npmjs.com/)). | ||||||||
|
There was a problem hiding this comment. Is there maybe a better link that describes what this is and how to use it? A JSON blob is not super helpful. There was a problem hiding this comment. The closest I could find is https://github.com/npm/registry/blob/master/docs/REPLICATE-API.md which appears to be older, not sure if there's anything more descriptive. |
||||||||
| - Advisories for malicious packages are published using the OSV schema and aggregated by the OSV service (e.g. [here](https://github.com/ossf/malicious-packages)) | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
|
|
||||||||
| ### CLI Tooling | ||||||||
|
There was a problem hiding this comment. Idea for another item under "CLI Tooling": guidance around how the CLI stores/uses/accesses API tokens? There was a problem hiding this comment. This seems overly broad, are we really just considering specific classes of CLI tooling, e.g. "installers", "builders", "publishers", etc? There was a problem hiding this comment. Agreed -- if the doc is meant to be taxonomical, it might make sense to clarify that tooling here is meant to be the "package installer" (based on context). |
||||||||
|
|
||||||||
| Applies to: all package management ecosystems, although here we are primarily focused on the CLI tooling instead of the registry itself. | ||||||||
|
There was a problem hiding this comment. What should tooling do when it encounters known malware? pypa/pip#5777 |
||||||||
|
|
||||||||
| - Level 1 | ||||||||
| - The CLI allows installing dependencies that are pinned based on hash, version, etc. | ||||||||
|
There was a problem hiding this comment. I would explicitly add "source registry" or "location" or similar here, to prevent repeats of issues such as https://nvd.nist.gov/vuln/detail/CVE-2020-36327 There was a problem hiding this comment. Agreed, something like "pinned based on build/source provenance", but that would probably be Level 2, if not Level 3. |
||||||||
| - Level 2 | ||||||||
| - The package repository warns of known security vulnerabilities in dependencies, in both the package repository UI and CLI tools when installing. | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
| - Level 3 | ||||||||
| - The CLI has functionality to produce SBOMs. | ||||||||
|
There was a problem hiding this comment.
Suggested change
I think this could be expanded: produce SBOMs for what? (applications? libraries?) based on what? (a lock file? a source tree?)
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
| - The package repository is able to reduce false positives of identified vulnerabilities using static analysis to understand whether a vulnerable code path is actually reachable. (e.g. [Golang's vulncheck feature](https://go.dev/security/vuln)) | ||||||||
|
There was a problem hiding this comment. Again, this seems like a mix of repository responsibilities (publish sufficiently detailed advisories that make it possible to determine usage) and CLI responsibilities (determine if a given source tree is actually using a vulnerable code path in a dependency with a known vulnerability).
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
|
|
||||||||
| ## Resources / Inspiration | ||||||||
|
|
||||||||
| - <https://github.com/psf/fundable-packaging-improvements/blob/master/FUNDABLES.md> | ||||||||
| - <https://github.com/ossf/wg-securing-software-repos/blob/main/survey/2022/results.csv> | ||||||||
| - <https://docs.npmjs.com/threats-and-mitigations> | ||||||||
| - <https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf> (as a framework for comparing options in a problem space) | ||||||||
steiza marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||
Uh oh!
There was an error while loading. Please reload this page.