From 18931083ea90f15e7c71cf8a2cdf151031918890 Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Wed, 13 Dec 2023 16:30:17 -0500 Subject: [PATCH 01/17] Add Principles for Package Repository Security Signed-off-by: Zach Steindler --- ...nciples-for-package-repository-security.md | 105 ++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 docs/principles-for-package-repository-security.md diff --git a/docs/principles-for-package-repository-security.md b/docs/principles-for-package-repository-security.md new file mode 100644 index 0000000..5285ec0 --- /dev/null +++ b/docs/principles-for-package-repository-security.md @@ -0,0 +1,105 @@ +# Principles for Package Repository Security + +Authors: [Jack Cable](https://github.com/cablej), [Zach Steindler](https://github.com/steiza) +Last updated: Dec 2023 + +## Background + +The Securing Software Repositories Working Group (WG) of the OpenSSF is putting together a taxonomy of package repositories and a set of principles for 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. + +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. + +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. + +## Taxonomy of Package Repositories + +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: +- 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, allow security researchers to report vulnerabilities. All package management ecosystems should be working towards this level. +- Level 2 is defined as having moderate security. +- Level 3 is defined as having advanced security. These items are more aspirational, especially for smaller package management ecosystems. + +### Authentication + +Applies to: package repositories that have user accounts. + +- 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. + - The package repository documents their account recovery policy. + - The package repository supports multi-factor authentication (MFA) via (at minimum) TOTP. + - 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. + - 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 locking accounts for which the domain is abandoned. + - The package repository supports MFA via phishing-resistant means such as WebAuthn + - 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 leaked credentials. If a user has a leaked credential, the package repository prompts them to change it upon login. +- Level 3 + - The package repository supports passwordless authentication, such as passkeys. + - The package repository requires MFA for all maintainers. + - 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. + +### 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. +- 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 identity tokens via OpenID Connect (OIDC) to prevent needing to provision long-lived API keys. Example: [trusted publishers](https://docs.pypi.org/trusted-publishers/) + - The package repository API tokens are integrated into common third-party secret scanning programs like GitGuardian, GitHub, etc. This typically requires using a known prefix or pattern to reduce false-positives. + - The package repository supports providing [build provenance](https://repos.openssf.org/build-provenance-for-all-package-registries) for packages. + +### General Capabilities + +Applies to: all package repositories + +- Level 1 + - The package repository has published a vulnerability disclosure policy allowing security researchers to report vulnerabilities to the package repository, and receive legal safe harbor when doing so. The package repository should strive to remediate reported vulnerabilities within 90 days. + - 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. + - The package repository allows users to report a package as suspicious or malicious via the registry UI, tooling CLI, and via API. + - The package repository takes steps to detect malware, including scanning for known malware code snippets and hashes. +- Level 3 + - Undergo periodic cloud security review (and optionally publish remediations once they are complete) + - The package repository publishes an event transparency log to enable detection of anomalous behaviors (e.g. [replicate.npmjs.com](https://replicate.npmjs.com/)). + - Malicious packages are published using OSV (e.g. [here](https://github.com/ossf/malicious-packages)) + +### CLI Tooling + +Applies to: all package management ecosystems, although here we are primarily focused on the CLI tooling instead of the registry itself. + +- Level 1 + - The CLI allows installing dependencies that are pinned based on hash, version, etc. +- Level 2 + - The package repository warns of known security vulnerabilities in dependencies, in both the package repository UI and CLI tools when installing. +- Level 3 + - The CLI has functionality to produce SBOMs. + - 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)) + +## Resources / Inspiration + +- +- +- +- (as a framework for comparing options in a problem space) From 7d517f7d3653a63d2b4249c98d106d908ad5dcac Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Wed, 13 Dec 2023 16:34:01 -0500 Subject: [PATCH 02/17] add links Signed-off-by: Zach Steindler --- README.md | 1 + docs/index.md | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2f0a58f..4fc8e46 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ The working group may create: See also https://repos.openssf.org/ +* **[Principles for Package Repository Security](https://repos.openssf.org/principles-for-package-repository-security)** - December 2023 * **[Build Provenance and Code-signing for Homebrew](https://repos.openssf.org/proposals/build-provenance-and-code-signing-for-homebrew)** - July 2023 > A proposal for introducing build provenance and cryptographic signatures to the Homebrew package manager. * **[Build Provenance for All Package Registries](https://repos.openssf.org/build-provenance-for-all-package-registries)** - July 2023 diff --git a/docs/index.md b/docs/index.md index 1c5f558..eb80657 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,10 +9,12 @@ This is a list of materials (surveys, documents, proposals, and so on) released ## Documents +* [Principles for Package Repository Security](https://repos.openssf.org/principles-for-package-repository-security) - December 2023 + > A security maturity model for package repositories, for assessing current capabilities and roadmapping future improvements. + * [Build Provenance for All Package Registries](https://repos.openssf.org/build-provenance-for-all-package-registries) - July 2023 > Guidance for package registries in adopting build provenance to verifiably link a package back to its source code and build instructions. - ## Proposals * [Build Provenance and Code-signing for Homebrew](https://repos.openssf.org/proposals/build-provenance-and-code-signing-for-homebrew) - July 2023 From ab4ceb7f36622b939c31b0db9bb013e2e3f816b0 Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Wed, 13 Dec 2023 16:36:51 -0500 Subject: [PATCH 03/17] add description to README Signed-off-by: Zach Steindler --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 4fc8e46..5d889dd 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,7 @@ The working group may create: See also https://repos.openssf.org/ * **[Principles for Package Repository Security](https://repos.openssf.org/principles-for-package-repository-security)** - December 2023 + > A security maturity model for package repositories, for assessing current capabilities and roadmapping future improvements. * **[Build Provenance and Code-signing for Homebrew](https://repos.openssf.org/proposals/build-provenance-and-code-signing-for-homebrew)** - July 2023 > A proposal for introducing build provenance and cryptographic signatures to the Homebrew package manager. * **[Build Provenance for All Package Registries](https://repos.openssf.org/build-provenance-for-all-package-registries)** - July 2023 From b2e695b6e13f4a46586d31361a34d490b280394e Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Fri, 15 Dec 2023 10:54:46 -0500 Subject: [PATCH 04/17] Update abandoned email domain wording Signed-off-by: Zach Steindler --- docs/principles-for-package-repository-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/principles-for-package-repository-security.md b/docs/principles-for-package-repository-security.md index 5285ec0..7a2d9c1 100644 --- a/docs/principles-for-package-repository-security.md +++ b/docs/principles-for-package-repository-security.md @@ -47,7 +47,7 @@ Applies to: package repositories that have user accounts. - 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. - 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 locking accounts for which the domain is abandoned. + - 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. - The package repository supports MFA via phishing-resistant means such as WebAuthn - 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 leaked credentials. If a user has a leaked credential, the package repository prompts them to change it upon login. From 04ac7ab873cb868f40e370e14b6fcac5f9bafe03 Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Mon, 8 Jan 2024 15:01:49 -0500 Subject: [PATCH 05/17] Update docs/principles-for-package-repository-security.md Co-authored-by: Jack Cable Signed-off-by: Zach Steindler --- docs/principles-for-package-repository-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/principles-for-package-repository-security.md b/docs/principles-for-package-repository-security.md index 7a2d9c1..d15f447 100644 --- a/docs/principles-for-package-repository-security.md +++ b/docs/principles-for-package-repository-security.md @@ -50,7 +50,7 @@ Applies to: package repositories that have user accounts. - 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. - The package repository supports MFA via phishing-resistant means such as WebAuthn - 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 leaked credentials. If a user has a leaked credential, the package repository prompts them to change it upon login. + - 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. From cfec1b732b64bcbeacf23bcdf300a388533658a9 Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Mon, 8 Jan 2024 15:02:59 -0500 Subject: [PATCH 06/17] Update docs/principles-for-package-repository-security.md Co-authored-by: Dustin Ingram Signed-off-by: Zach Steindler --- docs/principles-for-package-repository-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/principles-for-package-repository-security.md b/docs/principles-for-package-repository-security.md index d15f447..553a3dc 100644 --- a/docs/principles-for-package-repository-security.md +++ b/docs/principles-for-package-repository-security.md @@ -65,7 +65,7 @@ Applies to: package repositories that have user accounts and accept built packag - 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 identity tokens via OpenID Connect (OIDC) to prevent needing to provision long-lived API keys. Example: [trusted publishers](https://docs.pypi.org/trusted-publishers/) + - 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/) - The package repository API tokens are integrated into common third-party secret scanning programs like GitGuardian, GitHub, etc. This typically requires using a known prefix or pattern to reduce false-positives. - The package repository supports providing [build provenance](https://repos.openssf.org/build-provenance-for-all-package-registries) for packages. From c5065bece53bd9ef9f2c0290c56daa06312ad568 Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Mon, 8 Jan 2024 15:04:10 -0500 Subject: [PATCH 07/17] Update docs/principles-for-package-repository-security.md Co-authored-by: Dustin Ingram Signed-off-by: Zach Steindler --- docs/principles-for-package-repository-security.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/principles-for-package-repository-security.md b/docs/principles-for-package-repository-security.md index 553a3dc..c3aeba4 100644 --- a/docs/principles-for-package-repository-security.md +++ b/docs/principles-for-package-repository-security.md @@ -62,6 +62,7 @@ Applies to: package repositories that have user accounts and accept built packag - 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. + - API tokens are prefixed with a repository-specific identifier - Level 2 - The package repository supports role-based access control (RBAC) for maintainers, allowing separate roles for managing users and publishing packages. - Level 3 From 1ce0137a80d9092fd3f35b16f03c744b4e7c4c10 Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Mon, 8 Jan 2024 15:05:35 -0500 Subject: [PATCH 08/17] Update docs/principles-for-package-repository-security.md Co-authored-by: Jack Cable Signed-off-by: Zach Steindler --- docs/principles-for-package-repository-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/principles-for-package-repository-security.md b/docs/principles-for-package-repository-security.md index c3aeba4..a6b0756 100644 --- a/docs/principles-for-package-repository-security.md +++ b/docs/principles-for-package-repository-security.md @@ -67,7 +67,7 @@ Applies to: package repositories that have user accounts and accept built packag - 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/) - - The package repository API tokens are integrated into common third-party secret scanning programs like GitGuardian, GitHub, etc. This typically requires using a known prefix or pattern to reduce false-positives. + - 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. - The package repository supports providing [build provenance](https://repos.openssf.org/build-provenance-for-all-package-registries) for packages. ### General Capabilities From b42e807231507dee294d2ab4fb3ce213a474b39c Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Mon, 8 Jan 2024 15:06:10 -0500 Subject: [PATCH 09/17] Update docs/principles-for-package-repository-security.md Co-authored-by: Jack Cable Signed-off-by: Zach Steindler --- docs/principles-for-package-repository-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/principles-for-package-repository-security.md b/docs/principles-for-package-repository-security.md index a6b0756..158c7bf 100644 --- a/docs/principles-for-package-repository-security.md +++ b/docs/principles-for-package-repository-security.md @@ -75,7 +75,7 @@ Applies to: package repositories that have user accounts and accept built packag Applies to: all package repositories - Level 1 - - The package repository has published a vulnerability disclosure policy allowing security researchers to report vulnerabilities to the package repository, and receive legal safe harbor when doing so. The package repository should strive to remediate reported vulnerabilities within 90 days. + - 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. - 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. From c65f480d93e9bbdb1545fe875af8128824442f08 Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Mon, 8 Jan 2024 15:06:47 -0500 Subject: [PATCH 10/17] Update docs/principles-for-package-repository-security.md Co-authored-by: Dustin Ingram Signed-off-by: Zach Steindler --- docs/principles-for-package-repository-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/principles-for-package-repository-security.md b/docs/principles-for-package-repository-security.md index 158c7bf..ab92ec5 100644 --- a/docs/principles-for-package-repository-security.md +++ b/docs/principles-for-package-repository-security.md @@ -84,7 +84,7 @@ Applies to: all package repositories - Level 3 - Undergo periodic cloud security review (and optionally publish remediations once they are complete) - The package repository publishes an event transparency log to enable detection of anomalous behaviors (e.g. [replicate.npmjs.com](https://replicate.npmjs.com/)). - - Malicious packages are published using OSV (e.g. [here](https://github.com/ossf/malicious-packages)) + - 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)) ### CLI Tooling From 1146a6c2843bbe12ed7dd49a5a0f3236dcd5ef19 Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Mon, 8 Jan 2024 15:07:44 -0500 Subject: [PATCH 11/17] Update docs/principles-for-package-repository-security.md Co-authored-by: Dustin Ingram Signed-off-by: Zach Steindler --- docs/principles-for-package-repository-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/principles-for-package-repository-security.md b/docs/principles-for-package-repository-security.md index ab92ec5..3d08439 100644 --- a/docs/principles-for-package-repository-security.md +++ b/docs/principles-for-package-repository-security.md @@ -5,7 +5,7 @@ Last updated: Dec 2023 ## Background -The Securing Software Repositories Working Group (WG) of the OpenSSF is putting together a taxonomy of package repositories and a set of principles for security capabilities. This is intended to be an opinionated document, offering a set of best practices that package repositories should strive to adhere to. +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. From a77177ae7495f789a8048dc059c69e379380cdbd Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Mon, 8 Jan 2024 15:08:09 -0500 Subject: [PATCH 12/17] Update docs/principles-for-package-repository-security.md Co-authored-by: Jack Cable Signed-off-by: Zach Steindler --- docs/principles-for-package-repository-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/principles-for-package-repository-security.md b/docs/principles-for-package-repository-security.md index 3d08439..cb043ed 100644 --- a/docs/principles-for-package-repository-security.md +++ b/docs/principles-for-package-repository-security.md @@ -32,7 +32,7 @@ Does the package repository ... We define 4 levels of security maturity: - 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, allow security researchers to report vulnerabilities. All package management ecosystems should be working towards this level. +- 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. - Level 2 is defined as having moderate security. - Level 3 is defined as having advanced security. These items are more aspirational, especially for smaller package management ecosystems. From 05eb852a4c45279cc5a4ad943c3429cd7b23da78 Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Mon, 8 Jan 2024 15:09:35 -0500 Subject: [PATCH 13/17] Update docs/principles-for-package-repository-security.md Co-authored-by: Jack Cable Signed-off-by: Zach Steindler --- docs/principles-for-package-repository-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/principles-for-package-repository-security.md b/docs/principles-for-package-repository-security.md index cb043ed..f0ac90b 100644 --- a/docs/principles-for-package-repository-security.md +++ b/docs/principles-for-package-repository-security.md @@ -43,7 +43,7 @@ Applies to: package repositories that have user accounts. - 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. - The package repository documents their account recovery policy. - - The package repository supports multi-factor authentication (MFA) via (at minimum) TOTP. + - 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. - 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. - The package repository implements account security measures like brute force prevention (even with 2FA attempts) - Level 2 From 86b0642e5fb25f7944f3e0c70501a015b7ee1f53 Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Tue, 30 Jan 2024 09:34:58 -0500 Subject: [PATCH 14/17] Update authors and date Signed-off-by: Zach Steindler --- docs/principles-for-package-repository-security.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/principles-for-package-repository-security.md b/docs/principles-for-package-repository-security.md index f0ac90b..d027044 100644 --- a/docs/principles-for-package-repository-security.md +++ b/docs/principles-for-package-repository-security.md @@ -1,7 +1,7 @@ # Principles for Package Repository Security -Authors: [Jack Cable](https://github.com/cablej), [Zach Steindler](https://github.com/steiza) -Last updated: Dec 2023 +Authors: [Jack Cable (CISA)](https://github.com/cablej), [Zach Steindler](https://github.com/steiza) +Last updated: Jan 2024 ## Background From f8bbc2315db9d47599cab60de47c5e8bcb3b4cbb Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Tue, 6 Feb 2024 09:31:36 -0500 Subject: [PATCH 15/17] Update docs/principles-for-package-repository-security.md Co-authored-by: Jack Cable Signed-off-by: Zach Steindler --- docs/principles-for-package-repository-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/principles-for-package-repository-security.md b/docs/principles-for-package-repository-security.md index d027044..ffd17a5 100644 --- a/docs/principles-for-package-repository-security.md +++ b/docs/principles-for-package-repository-security.md @@ -82,7 +82,7 @@ Applies to: all package repositories - The package repository allows users to report a package as suspicious or malicious via the registry UI, tooling CLI, and via API. - The package repository takes steps to detect malware, including scanning for known malware code snippets and hashes. - Level 3 - - Undergo periodic cloud security review (and optionally publish remediations once they are complete) + - Undergo periodic security reviews of package repository infrastructure (and optionally publish remediations once they are complete) - The package repository publishes an event transparency log to enable detection of anomalous behaviors (e.g. [replicate.npmjs.com](https://replicate.npmjs.com/)). - 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)) From c53f265d14c2ec85f2f68a5ae80d616e125ef34a Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Tue, 6 Feb 2024 09:37:01 -0500 Subject: [PATCH 16/17] Apply suggestions from code review Co-authored-by: Jack Cable Signed-off-by: Zach Steindler --- ...nciples-for-package-repository-security.md | 38 ++++++++++--------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/docs/principles-for-package-repository-security.md b/docs/principles-for-package-repository-security.md index ffd17a5..6603502 100644 --- a/docs/principles-for-package-repository-security.md +++ b/docs/principles-for-package-repository-security.md @@ -5,13 +5,13 @@ 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. +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 offer 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. +By package repository (sometimes also called package registry) we're referring to the service that stores and indexes packages, enabling users and clients to download packages. 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. -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. +We include the below taxonomy 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. -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. +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. ## Taxonomy of Package Repositories @@ -32,9 +32,9 @@ Does the package repository ... We define 4 levels of security maturity: - 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. -- Level 2 is defined as having moderate security. -- Level 3 is defined as having advanced security. These items are more aspirational, especially for smaller package management ecosystems. +- Level 1 is defined as having basic security maturity, which includes supporting basic security features like multi-factor authentication (MFA) and allowing security researchers to report vulnerabilities. All package management ecosystems should be working towards at least this level. +- Level 2 is defined as having moderate security, which includes actions like requiring MFA for critical packages and warning users of known security vulnerabilities. +- Level 3 is defined as having advanced security, which includes actions like requiring MFA for all maintainers and supporting build provenance for packages. This level is more aspirational, especially for smaller package management ecosystems. ### Authentication @@ -43,18 +43,18 @@ Applies to: package repositories that have user accounts. - 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. - The package repository documents their account recovery policy. - - 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. + - 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. - 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. - 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. - - The package repository supports MFA via phishing-resistant means such as WebAuthn + - The package repository supports MFA via phishing-resistant means such as WebAuthn. - 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. - - 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. + - The package repository requires phishing-resistant MFA for packages deemed critical (e.g., the top 1% of packages by downloads). If possible, the package repository supplies security keys to these maintainers. ### Authorization @@ -62,12 +62,12 @@ Applies to: package repositories that have user accounts and accept built packag - 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. - - API tokens are prefixed with a repository-specific identifier + - API tokens are prefixed with a repository-specific identifier. - 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/) - - 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. + - 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/). + - 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. - The package repository supports providing [build provenance](https://repos.openssf.org/build-provenance-for-all-package-registries) for packages. ### General Capabilities @@ -75,16 +75,17 @@ Applies to: package repositories that have user accounts and accept built packag Applies to: all package repositories - Level 1 - - 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. + - The package repository has published a vulnerability disclosure policy allowing security researchers to identify and report vulnerabilities affecting the package repository, and receive legal safe harbor when doing so within the requirements of the policy. The package repository should strive to remediate reported vulnerabilities within 90 days. - 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. - The package repository allows users to report a package as suspicious or malicious via the registry UI, tooling CLI, and via API. - The package repository takes steps to detect malware, including scanning for known malware code snippets and hashes. + - The package repository warns of known security vulnerabilities in dependencies in the package repository UI. - Level 3 - Undergo periodic security reviews of package repository infrastructure (and optionally publish remediations once they are complete) - The package repository publishes an event transparency log to enable detection of anomalous behaviors (e.g. [replicate.npmjs.com](https://replicate.npmjs.com/)). - - 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)) + - Advisories for malicious packages are published using a standardized machine readable format, such as using the OSV schema and aggregation provided by the OSV service (e.g. [here](https://github.com/ossf/malicious-packages)). ### CLI Tooling @@ -93,10 +94,11 @@ Applies to: all package management ecosystems, although here we are primarily fo - Level 1 - The CLI allows installing dependencies that are pinned based on hash, version, etc. - Level 2 - - The package repository warns of known security vulnerabilities in dependencies, in both the package repository UI and CLI tools when installing. + - The CLI warns of known security vulnerabilities in dependencies when installing packages. - Level 3 - The CLI has functionality to produce SBOMs. - - 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)) + - The CLI has functionality to, where possible, automatically remediate known vulnerabilities in dependencies by upgrading them. + - 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)). ## Resources / Inspiration @@ -104,3 +106,5 @@ Applies to: all package management ecosystems, although here we are primarily fo - - - (as a framework for comparing options in a problem space) + +Note: CISA does not endorse any commercial entity, product, company, or service, including any entities, products, or services linked within this document. Any reference to specific commercial entities, products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply endorsement, recommendation, or favoring by CISA. From 771106f75765787983c261f131246c237bd8d884 Mon Sep 17 00:00:00 2001 From: Zach Steindler Date: Thu, 8 Feb 2024 08:30:32 -0500 Subject: [PATCH 17/17] Clarify levels, update date, minor formatting edits Signed-off-by: Zach Steindler --- README.md | 2 +- docs/index.md | 2 +- ...nciples-for-package-repository-security.md | 19 +++++++++++-------- 3 files changed, 13 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 5d889dd..96d95d6 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ The working group may create: See also https://repos.openssf.org/ -* **[Principles for Package Repository Security](https://repos.openssf.org/principles-for-package-repository-security)** - December 2023 +* **[Principles for Package Repository Security](https://repos.openssf.org/principles-for-package-repository-security)** - February 2024 > A security maturity model for package repositories, for assessing current capabilities and roadmapping future improvements. * **[Build Provenance and Code-signing for Homebrew](https://repos.openssf.org/proposals/build-provenance-and-code-signing-for-homebrew)** - July 2023 > A proposal for introducing build provenance and cryptographic signatures to the Homebrew package manager. diff --git a/docs/index.md b/docs/index.md index eb80657..cbf92e6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,7 +9,7 @@ This is a list of materials (surveys, documents, proposals, and so on) released ## Documents -* [Principles for Package Repository Security](https://repos.openssf.org/principles-for-package-repository-security) - December 2023 +* [Principles for Package Repository Security](https://repos.openssf.org/principles-for-package-repository-security) - February 2024 > A security maturity model for package repositories, for assessing current capabilities and roadmapping future improvements. * [Build Provenance for All Package Registries](https://repos.openssf.org/build-provenance-for-all-package-registries) - July 2023 diff --git a/docs/principles-for-package-repository-security.md b/docs/principles-for-package-repository-security.md index 6603502..5f1f650 100644 --- a/docs/principles-for-package-repository-security.md +++ b/docs/principles-for-package-repository-security.md @@ -1,7 +1,7 @@ # Principles for Package Repository Security Authors: [Jack Cable (CISA)](https://github.com/cablej), [Zach Steindler](https://github.com/steiza) -Last updated: Jan 2024 +Last updated: Feb 2024 ## Background @@ -15,27 +15,30 @@ The roadmap of security capabilities can then be used by package repositories to ## Taxonomy of Package Repositories -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. +Security capabilities will differ based on the services that the package repository offers. For instance, if the package repository has user accounts, it 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 +- 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 +- Accept built packages: 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: + - Level 0 is defined as having very little security maturity. - Level 1 is defined as having basic security maturity, which includes supporting basic security features like multi-factor authentication (MFA) and allowing security researchers to report vulnerabilities. All package management ecosystems should be working towards at least this level. - Level 2 is defined as having moderate security, which includes actions like requiring MFA for critical packages and warning users of known security vulnerabilities. - Level 3 is defined as having advanced security, which includes actions like requiring MFA for all maintainers and supporting build provenance for packages. This level is more aspirational, especially for smaller package management ecosystems. +These levels are split into four tracks enumerated in the below sections: Authentication, Authorization, General Capabilities, and CLI Tooling. All tracks may not apply to all package repositories, as detailed above. Having these tracks allows package repositories to assess their security across various dimensions. + ### Authentication Applies to: package repositories that have user accounts. @@ -62,7 +65,7 @@ Applies to: package repositories that have user accounts and accept built packag - 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. - - API tokens are prefixed with a repository-specific identifier. + - API tokens are prefixed with a package repository-specific identifier. - Level 2 - The package repository supports role-based access control (RBAC) for maintainers, allowing separate roles for managing users and publishing packages. - Level 3