From 6933bc8789a3077c7d6bb0c0337adf2d5c884851 Mon Sep 17 00:00:00 2001 From: ariathaker Date: Fri, 27 Oct 2023 20:01:46 +0530 Subject: [PATCH 01/13] -Added beginner's guide to scorecard checks doc -Edited README to link to the beginner's guide Signed-off-by: ariathaker --- README.md | 17 +++++---- docs/beginner-checks.md | 77 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+), 6 deletions(-) create mode 100644 docs/beginner-checks.md diff --git a/README.md b/README.md index bda6efed521..b876a764dae 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ - [Default Scorecard Checks](#scorecard-checks) - [Detailed Check Documentation](docs/checks.md) (Scoring Criteria, Risks, and Remediation) +- [Beginner's Guide to Scorecard Checks](#beginners-guide-to-scorecard-checks) ## Other Important Recommendations - [Two-factor Authentication (2FA)](#two-factor-authentication-2fa) @@ -94,14 +95,14 @@ metrics. Prominent projects that use Scorecard include: ### View a Project's Score -To see scores for projects regularly scanned by Scorecard, navigate to the webviewer, replacing the placeholder text with the platform, user/org, and repository name: +To see scores for projects regularly scanned by Scorecard, navigate to the webviewer, replacing the placeholder text with the platform, user/org, and repository name: https://securityscorecards.dev/viewer/?uri=.com//. -For example: +For example: - [https://securityscorecards.dev/viewer/?uri=github.com/ossf/scorecard](https://securityscorecards.dev/viewer/?uri=github.com/ossf/scorecard) - [https://securityscorecards.dev/viewer/?uri=gitlab.com/fdroid/fdroidclient](https://securityscorecards.dev/viewer/?uri=gitlab.com/fdroid/fdroidclient) -To view scores for projects not included in the webviewer, use the [Scorecard CLI](#scorecard-command-line-interface). +To view scores for projects not included in the webviewer, use the [Scorecard CLI](#scorecard-command-line-interface). ### Public Data @@ -506,6 +507,10 @@ Name | Description | Risk Level | Token Req To see detailed information about each check, its scoring criteria, and remediation steps, check out the [checks documentation page](docs/checks.md). +### Beginner's Guide to Scorecard Checks + +For a guide to the checks you should use when getting started, see the [beginner's guide to scorecard checks](docs/beginner-checks.md). + ## Other Important Recommendations ### Two-factor Authentication (2FA) @@ -593,13 +598,13 @@ To report a security issue, please follow instructions [here](SECURITY.md). ### Join the Scorecards Project Meeting -#### Zoom +#### Zoom -We meet every other Thursday - 4p ET on this [zoom link](https://zoom.us/j/98835923979?pwd=RG5JZ3czZEtmRDlGdms0ZktmMFQvUT09). +We meet every other Thursday - 4p ET on this [zoom link](https://zoom.us/j/98835923979?pwd=RG5JZ3czZEtmRDlGdms0ZktmMFQvUT09). #### Agenda -You can see the [agenda and meeting notes here](https://docs.google.com/document/d/1b6d3CVJLsl7YnTE7ZaZQHdkdYIvuOQ8rzAmvVdypOWM/edit?usp=sharing). +You can see the [agenda and meeting notes here](https://docs.google.com/document/d/1b6d3CVJLsl7YnTE7ZaZQHdkdYIvuOQ8rzAmvVdypOWM/edit?usp=sharing). ## Stargazers over time diff --git a/docs/beginner-checks.md b/docs/beginner-checks.md new file mode 100644 index 00000000000..5597a077af1 --- /dev/null +++ b/docs/beginner-checks.md @@ -0,0 +1,77 @@ +# Getting Started with Scorecard Checks for Supply Chain Security + +If you are an open-source developer, you know that maintaining the security posture of a project can feel like a full-time job, but it can be easier with a little guidance. [Scorecard](https://github.com/ossf/scorecard#openssf-scorecard), an automated tool created [by the Open Source Security Foundation](https://securityscorecards.dev/) (OpenSSF), checks projects for security best practices and scores projects on a scale between 1 and 10. Maintainers can use the Scorecard checks as guidelines to improve their project's security practices. + +Choosing which Scorecard checks to get started with can be overwhelming, though. On this page, we’ll walk you through getting started with some of the most important checks, focusing on the ones that give you the biggest payoff versus effort. We’ve broken them down into three categories based on stages of the development process: setting up your project, accepting contributions from others, and packaging the project to release to the world. + +## 1. Setting up your project + +The setup phase of an open-source project can be hectic, which can make it difficult to prioritize security concerns. Start your project off strong by focusing on Scorecard checks that help you secure your project dependencies and workflows. + +- Secure your dependencies with the Vulnerabilities check and the Dependency-Update-Tool check +- Secure your workflows with the Token-Permissions check + +### The Vulnerabilities and Dependency-Update-Tool checks secure your dependencies + +Vulnerabilities are probably the most familiar security risk. By running Scorecard’s [Vulnerabilities check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#vulnerabilities), you’ll get information about known vulnerabilities in your project, either through your codebase or through your direct and (for most languages) indirect dependencies. Tracking these can be tricky, but it’s important: [95% of vulnerable dependencies are transitive](https://www.endorlabs.com/state-of-dependency-management). + +If vulnerabilities are found in your dependencies, there are a few options: + +- Update the dependency to a non-vulnerable version (if available) +- Submit a patch to the vulnerable project +- Replace the dependency with a non-vulnerable dependency +- Remove the dependency and write code to take its place +- If you are sure a vulnerability does not impact your project, you may ignore the dependency by creating an [osv-scanner.toml](https://google.github.io/osv-scanner/configuration/#ignore-vulnerabilities-by-id) file in the same directory as your dependency manifest + +If you have handled the vulnerabilities in your dependencies and are still not satisfied with your score for this check, make sure there are no open, unfixed vulnerabilities in your project’s own codebase. Once you have dealt with those, your score should improve. + +Next, Scorecard’s [Dependency-Update-Tool check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dependency-update-tool) encourages developers to keep their dependencies up to date, which is a great way to stay on top of security updates. This check awards a high score to a project if it uses a dependency update tool such as [Dependabot](https://docs.github.com/en/code-security/dependabot), [Renovate bot](https://docs.renovatebot.com/), or [PyUp](https://github.com/pyupio/pyup#readme). Using one of these tools helps streamline security processes by notifying you when vulnerabilities have surfaced in your dependencies or when new versions of your dependencies become available. + +Automated processes like these save you time and are highly configurable; for example, you can set your bot to update dependencies every day or every week at the same time. + +If you want to increase your score in this category, sign up for automatic updates with a dependency update tool. Do note, however, that this check can only assess whether the dependency update tool is enabled, not that it is running. To maximize your benefit from this check, be sure that you consistently run your dependency update tool. + +### Token-Permissions check helps you secure your workflows + +We suggest addressing the [Token-Permissions check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions) next because it takes just a few minutes to “set it and forget it” and secure your workflows. The check warns you when your project’s tokens have `write` access instead of `read` access. Projects that use tokens with `write` access for their automated workflows may be vulnerable to malicious code execution. By simply switching `write` to `read` you’ll be able to close off a powerful attack vector (exploiting compromised tokens that have write permissions and using them to inject malicious code into the project). + +To change the default setting for token permissions, add the following to the top of your workflow: + +``` +permissions: +contents: read +``` + +When you add a GitHub Action, be sure to read the Action’s docs to see if it needs any additional permissions; this information is usually prominent in the Action’s README. + +## 2. Manage contributions to your project + +As projects grow, they generally start including contributions from others. Contributors can expand your project’s scope and maturity, but they can also introduce security risk. To protect your project at this stage, we recommend improving the Branch Protection check, which allows you, the maintainer, to define rules that require certain workflows for certain branches. + +### Branch Protection reduces the risks of errors and hacks + +The [Branch Protection check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection) can help protect your code from unvetted changes. You can choose any or all of the following options: + +- Require code review. Select this if your project has more than one maintainer. Requiring review before changes are merged is one of the strongest protections you can give your code. This will also improve your [Code Review check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#code-review) score. +- Require [status checks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks). All projects would benefit from selecting this option. It ensures that all Continuous Integration (CI) tests have passed before a change is accepted, helping you catch mistakes early on in the development process. This will also improve your [CI Test check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#ci-tests) score. +- [Require signed commits](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-signed-commits). All projects would benefit from selecting this option. By requiring that you sign your own commits, you help leave an auditable trail showing that you were the one who made the changes, not a malicious actor who gained access to your project. Requiring signed commits can be especially helpful for single maintainers who don’t have fellow contributors to review their code. + +## 3. Package and release your project + +Deciding how to securely share your code can be difficult. Building locally on your laptop may seem simpler at first, but using an automated build process to create your package on your CI/CD system provides you with security benefits that pay off in the long run. Scorecard’s Packaging check helps guide you through this process. + +### Packaging check verifies if a project is published as a package + +The [Packaging check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#packaging) assesses whether a project has been published as a package. The check is currently limited to repositories hosted on GitHub. It looks for [GitHub packaging workflows](https://docs.github.com/en/packages/learn-github-packages/publishing-a-package) and language-specific GitHub Actions that upload the package to a corresponding hub, like npm or PyPI. + +Packaging your projects makes it easier for users to receive security patches as updates. It also provides information about the release details to your users, which opens the door to more collaboration from your open-source peers. + +Another benefit to releasing projects as packages is reproducibility—the version that new users can download and execute is identical to the one that you and other contributors have already reviewed. Packages also have clear versioning documentation; this makes it easier to track whether any newly discovered security issues are applicable to your project. + +## Customize your checks to your project’s needs + +Based on the specifics of your project, not all the checks offered by Scorecard, or even not all of the checks discussed on this page, may apply to you. For example, if you are the sole maintainer of an open-source project, the “Code Review” check would not be usable for your project. + +The languages you use also influence which checks will be useful to you. For example, if your project is built in C or C++, the Packaging and Dependency-Update-Tool checks will not be applicable because the C/C++ ecosystem does not have a centralized package manager. + +To learn more about all the checks Scorecard offers, see the [checks documentation](https://github.com/ossf/scorecard/blob/main/docs/checks.md#check-documentation). From 0d938d27796a76610fef9c9c68cf9f3af443fd37 Mon Sep 17 00:00:00 2001 From: ariathaker <51683211+ariathaker@users.noreply.github.com> Date: Sun, 29 Oct 2023 23:58:11 -0700 Subject: [PATCH 02/13] Update beginner-checks.md Incorporating Spencer's edits. Signed-off-by: ariathaker <51683211+ariathaker@users.noreply.github.com> Signed-off-by: ariathaker --- docs/beginner-checks.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/beginner-checks.md b/docs/beginner-checks.md index 5597a077af1..c315e5a77a5 100644 --- a/docs/beginner-checks.md +++ b/docs/beginner-checks.md @@ -1,6 +1,6 @@ # Getting Started with Scorecard Checks for Supply Chain Security -If you are an open-source developer, you know that maintaining the security posture of a project can feel like a full-time job, but it can be easier with a little guidance. [Scorecard](https://github.com/ossf/scorecard#openssf-scorecard), an automated tool created [by the Open Source Security Foundation](https://securityscorecards.dev/) (OpenSSF), checks projects for security best practices and scores projects on a scale between 1 and 10. Maintainers can use the Scorecard checks as guidelines to improve their project's security practices. +If you are an open-source developer, you know that maintaining the security posture of a project can feel like a full-time job, but it can be easier with a little guidance. [Scorecard](https://github.com/ossf/scorecard#openssf-scorecard), an automated tool created [by the Open Source Security Foundation](https://openssf.org/) (OpenSSF), checks projects for security best practices and scores projects on a scale between 1 and 10. Maintainers can use the Scorecard checks as guidelines to improve their project's security practices. Choosing which Scorecard checks to get started with can be overwhelming, though. On this page, we’ll walk you through getting started with some of the most important checks, focusing on the ones that give you the biggest payoff versus effort. We’ve broken them down into three categories based on stages of the development process: setting up your project, accepting contributions from others, and packaging the project to release to the world. @@ -21,11 +21,11 @@ If vulnerabilities are found in your dependencies, there are a few options: - Submit a patch to the vulnerable project - Replace the dependency with a non-vulnerable dependency - Remove the dependency and write code to take its place -- If you are sure a vulnerability does not impact your project, you may ignore the dependency by creating an [osv-scanner.toml](https://google.github.io/osv-scanner/configuration/#ignore-vulnerabilities-by-id) file in the same directory as your dependency manifest +- If you are sure a vulnerability does not impact your project, you may ignore the dependency by creating an [osv-scanner.toml](https://google.github.io/osv-scanner/configuration/#ignore-vulnerabilities-by-id) file in your project's root directory. If you have handled the vulnerabilities in your dependencies and are still not satisfied with your score for this check, make sure there are no open, unfixed vulnerabilities in your project’s own codebase. Once you have dealt with those, your score should improve. -Next, Scorecard’s [Dependency-Update-Tool check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dependency-update-tool) encourages developers to keep their dependencies up to date, which is a great way to stay on top of security updates. This check awards a high score to a project if it uses a dependency update tool such as [Dependabot](https://docs.github.com/en/code-security/dependabot), [Renovate bot](https://docs.renovatebot.com/), or [PyUp](https://github.com/pyupio/pyup#readme). Using one of these tools helps streamline security processes by notifying you when vulnerabilities have surfaced in your dependencies or when new versions of your dependencies become available. +Next, Scorecard’s [Dependency-Update-Tool check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dependency-update-tool) encourages developers to keep their dependencies up to date, which is a great way to stay on top of security updates. This check awards a high score to a project if it uses a dependency update tool such as [Dependabot](https://docs.github.com/code-security/dependabot), [Renovate bot](https://docs.renovatebot.com/), or [PyUp](https://github.com/pyupio/pyup#readme). Using one of these tools helps streamline security processes by notifying you when vulnerabilities have surfaced in your dependencies or when new versions of your dependencies become available. Automated processes like these save you time and are highly configurable; for example, you can set your bot to update dependencies every day or every week at the same time. @@ -33,13 +33,13 @@ If you want to increase your score in this category, sign up for automatic updat ### Token-Permissions check helps you secure your workflows -We suggest addressing the [Token-Permissions check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions) next because it takes just a few minutes to “set it and forget it” and secure your workflows. The check warns you when your project’s tokens have `write` access instead of `read` access. Projects that use tokens with `write` access for their automated workflows may be vulnerable to malicious code execution. By simply switching `write` to `read` you’ll be able to close off a powerful attack vector (exploiting compromised tokens that have write permissions and using them to inject malicious code into the project). +We suggest addressing the [Token-Permissions check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions) next because it takes just a few minutes to “set it and forget it” and secure your workflows. The check warns you when your project’s top-level tokens have `write` access instead of the more restrictive `read` access. Not all `write` access permissions need to be eliminated; some workflows may genuinely require them. However, ensuring your top-level permissions have `read` access helps your project adhere to the principle of least privilege, which means that permissions are granted based on the minimal necessary access to perform a function. Projects that have top-level tokens set to `write` access for their automated workflows may be vulnerable to malicious code execution. By simply switching `write` to `read` you’ll be able to close off a powerful attack vector (exploiting compromised tokens that have write permissions and using them to inject malicious code into the project). To change the default setting for token permissions, add the following to the top of your workflow: ``` permissions: -contents: read + contents: read ``` When you add a GitHub Action, be sure to read the Action’s docs to see if it needs any additional permissions; this information is usually prominent in the Action’s README. @@ -50,11 +50,10 @@ As projects grow, they generally start including contributions from others. Cont ### Branch Protection reduces the risks of errors and hacks -The [Branch Protection check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection) can help protect your code from unvetted changes. You can choose any or all of the following options: +The [Branch Protection check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection) can help protect your code from unvetted changes. You can choose either or both of the following options: - Require code review. Select this if your project has more than one maintainer. Requiring review before changes are merged is one of the strongest protections you can give your code. This will also improve your [Code Review check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#code-review) score. -- Require [status checks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks). All projects would benefit from selecting this option. It ensures that all Continuous Integration (CI) tests have passed before a change is accepted, helping you catch mistakes early on in the development process. This will also improve your [CI Test check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#ci-tests) score. -- [Require signed commits](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-signed-commits). All projects would benefit from selecting this option. By requiring that you sign your own commits, you help leave an auditable trail showing that you were the one who made the changes, not a malicious actor who gained access to your project. Requiring signed commits can be especially helpful for single maintainers who don’t have fellow contributors to review their code. +- Require [status checks](https://docs.github.com/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks). All projects would benefit from selecting this option. It ensures that all Continuous Integration (CI) tests chosen by the maintainer have passed before a change is accepted, helping you catch mistakes early on in the development process. This will also improve your [CI Test check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#ci-tests) score. ## 3. Package and release your project @@ -62,7 +61,7 @@ Deciding how to securely share your code can be difficult. Building locally on y ### Packaging check verifies if a project is published as a package -The [Packaging check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#packaging) assesses whether a project has been published as a package. The check is currently limited to repositories hosted on GitHub. It looks for [GitHub packaging workflows](https://docs.github.com/en/packages/learn-github-packages/publishing-a-package) and language-specific GitHub Actions that upload the package to a corresponding hub, like npm or PyPI. +The [Packaging check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#packaging) assesses whether a project has been published as a package. The check is currently limited to repositories hosted on GitHub. It looks for [GitHub packaging workflows](https://docs.github.com/packages/learn-github-packages/publishing-a-package) and language-specific GitHub Actions that upload the package to a corresponding hub, like npm or PyPI. Packaging your projects makes it easier for users to receive security patches as updates. It also provides information about the release details to your users, which opens the door to more collaboration from your open-source peers. From c05e6111371e25c86f3b2e2e28142fa55baf8794 Mon Sep 17 00:00:00 2001 From: ariathaker <51683211+ariathaker@users.noreply.github.com> Date: Wed, 1 Nov 2023 05:50:04 -0700 Subject: [PATCH 03/13] Update docs/beginner-checks.md Co-authored-by: olivekl <83081275+olivekl@users.noreply.github.com> Signed-off-by: ariathaker <51683211+ariathaker@users.noreply.github.com> Signed-off-by: ariathaker --- docs/beginner-checks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/beginner-checks.md b/docs/beginner-checks.md index c315e5a77a5..99bd5b4867f 100644 --- a/docs/beginner-checks.md +++ b/docs/beginner-checks.md @@ -2,7 +2,7 @@ If you are an open-source developer, you know that maintaining the security posture of a project can feel like a full-time job, but it can be easier with a little guidance. [Scorecard](https://github.com/ossf/scorecard#openssf-scorecard), an automated tool created [by the Open Source Security Foundation](https://openssf.org/) (OpenSSF), checks projects for security best practices and scores projects on a scale between 1 and 10. Maintainers can use the Scorecard checks as guidelines to improve their project's security practices. -Choosing which Scorecard checks to get started with can be overwhelming, though. On this page, we’ll walk you through getting started with some of the most important checks, focusing on the ones that give you the biggest payoff versus effort. We’ve broken them down into three categories based on stages of the development process: setting up your project, accepting contributions from others, and packaging the project to release to the world. +Choosing which Scorecard checks to get started with as a project maintainer can be overwhelming. This page walks through some of the most important checks to start with for project improvement, focusing on the ones that give you the biggest payoff versus effort. They're broken down into three categories based on stages of the development process: setting up your project, accepting contributions from others, and packaging the project to release to the world. ## 1. Setting up your project From aca042b2b8c9c05a3e03c215540eb924ed0b2872 Mon Sep 17 00:00:00 2001 From: ariathaker <51683211+ariathaker@users.noreply.github.com> Date: Wed, 1 Nov 2023 05:50:27 -0700 Subject: [PATCH 04/13] Update docs/beginner-checks.md Co-authored-by: olivekl <83081275+olivekl@users.noreply.github.com> Signed-off-by: ariathaker <51683211+ariathaker@users.noreply.github.com> Signed-off-by: ariathaker --- docs/beginner-checks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/beginner-checks.md b/docs/beginner-checks.md index 99bd5b4867f..84fbaf538ac 100644 --- a/docs/beginner-checks.md +++ b/docs/beginner-checks.md @@ -6,7 +6,7 @@ Choosing which Scorecard checks to get started with as a project maintainer can ## 1. Setting up your project -The setup phase of an open-source project can be hectic, which can make it difficult to prioritize security concerns. Start your project off strong by focusing on Scorecard checks that help you secure your project dependencies and workflows. +Start your project off strong by focusing on Scorecard checks that help you secure your project dependencies and workflows. - Secure your dependencies with the Vulnerabilities check and the Dependency-Update-Tool check - Secure your workflows with the Token-Permissions check From e88999478023c24f47dd30172cc295a433135efd Mon Sep 17 00:00:00 2001 From: ariathaker <51683211+ariathaker@users.noreply.github.com> Date: Wed, 1 Nov 2023 05:50:52 -0700 Subject: [PATCH 05/13] Update docs/beginner-checks.md Co-authored-by: olivekl <83081275+olivekl@users.noreply.github.com> Signed-off-by: ariathaker <51683211+ariathaker@users.noreply.github.com> Signed-off-by: ariathaker --- docs/beginner-checks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/beginner-checks.md b/docs/beginner-checks.md index 84fbaf538ac..01d851e9fc1 100644 --- a/docs/beginner-checks.md +++ b/docs/beginner-checks.md @@ -13,7 +13,7 @@ Start your project off strong by focusing on Scorecard checks that help you secu ### The Vulnerabilities and Dependency-Update-Tool checks secure your dependencies -Vulnerabilities are probably the most familiar security risk. By running Scorecard’s [Vulnerabilities check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#vulnerabilities), you’ll get information about known vulnerabilities in your project, either through your codebase or through your direct and (for most languages) indirect dependencies. Tracking these can be tricky, but it’s important: [95% of vulnerable dependencies are transitive](https://www.endorlabs.com/state-of-dependency-management). +Vulnerabilities are probably the most familiar security risk. By running Scorecard’s [Vulnerabilities check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#vulnerabilities), you’ll get information about known vulnerabilities in your project, either through your codebase or through your direct and (for most languages) indirect dependencies. Tracking vulnerabilities in an indirect (sometimes called transitive) dependency can be tricky, but it’s important: [95% of vulnerable dependencies are transitive](https://www.endorlabs.com/state-of-dependency-management). If vulnerabilities are found in your dependencies, there are a few options: From be510e7c4f8ca48b32e66cf90b2cfe38ecff5ffd Mon Sep 17 00:00:00 2001 From: ariathaker <51683211+ariathaker@users.noreply.github.com> Date: Wed, 1 Nov 2023 05:51:31 -0700 Subject: [PATCH 06/13] Update docs/beginner-checks.md Co-authored-by: olivekl <83081275+olivekl@users.noreply.github.com> Signed-off-by: ariathaker <51683211+ariathaker@users.noreply.github.com> Signed-off-by: ariathaker --- docs/beginner-checks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/beginner-checks.md b/docs/beginner-checks.md index 01d851e9fc1..dab7f8bbcfa 100644 --- a/docs/beginner-checks.md +++ b/docs/beginner-checks.md @@ -65,7 +65,7 @@ The [Packaging check](https://github.com/ossf/scorecard/blob/main/docs/checks.md Packaging your projects makes it easier for users to receive security patches as updates. It also provides information about the release details to your users, which opens the door to more collaboration from your open-source peers. -Another benefit to releasing projects as packages is reproducibility—the version that new users can download and execute is identical to the one that you and other contributors have already reviewed. Packages also have clear versioning documentation; this makes it easier to track whether any newly discovered security issues are applicable to your project. +Another benefit to releasing projects as packages is reproducibility—the version that new users can download and execute is identical to the one that you and other contributors have already reviewed. Packages also have clear versioning documentation that makes it easier to track whether any newly discovered security issues are applicable to your project. ## Customize your checks to your project’s needs From 52b8a3647faa7934e8ef8adc396c7eb33acabd41 Mon Sep 17 00:00:00 2001 From: ariathaker <51683211+ariathaker@users.noreply.github.com> Date: Wed, 1 Nov 2023 05:51:50 -0700 Subject: [PATCH 07/13] Update docs/beginner-checks.md Co-authored-by: olivekl <83081275+olivekl@users.noreply.github.com> Signed-off-by: ariathaker <51683211+ariathaker@users.noreply.github.com> Signed-off-by: ariathaker --- docs/beginner-checks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/beginner-checks.md b/docs/beginner-checks.md index dab7f8bbcfa..37a7fd49da3 100644 --- a/docs/beginner-checks.md +++ b/docs/beginner-checks.md @@ -69,7 +69,7 @@ Another benefit to releasing projects as packages is reproducibility—the versi ## Customize your checks to your project’s needs -Based on the specifics of your project, not all the checks offered by Scorecard, or even not all of the checks discussed on this page, may apply to you. For example, if you are the sole maintainer of an open-source project, the “Code Review” check would not be usable for your project. +Based on the specifics of your project, not all the checks offered by Scorecard or discussed on this page may apply to you. For example, if you are the sole maintainer of an open-source project, the “Code Review” check would not be usable for your project. The languages you use also influence which checks will be useful to you. For example, if your project is built in C or C++, the Packaging and Dependency-Update-Tool checks will not be applicable because the C/C++ ecosystem does not have a centralized package manager. From e2bbd88ed2a90a4c6c91ad04963d4affadea8f01 Mon Sep 17 00:00:00 2001 From: ariathaker <51683211+ariathaker@users.noreply.github.com> Date: Wed, 1 Nov 2023 05:53:08 -0700 Subject: [PATCH 08/13] Update docs/beginner-checks.md Co-authored-by: olivekl <83081275+olivekl@users.noreply.github.com> Signed-off-by: ariathaker <51683211+ariathaker@users.noreply.github.com> Signed-off-by: ariathaker --- docs/beginner-checks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/beginner-checks.md b/docs/beginner-checks.md index 37a7fd49da3..9599986b0ee 100644 --- a/docs/beginner-checks.md +++ b/docs/beginner-checks.md @@ -29,7 +29,7 @@ Next, Scorecard’s [Dependency-Update-Tool check](https://github.com/ossf/score Automated processes like these save you time and are highly configurable; for example, you can set your bot to update dependencies every day or every week at the same time. -If you want to increase your score in this category, sign up for automatic updates with a dependency update tool. Do note, however, that this check can only assess whether the dependency update tool is enabled, not that it is running. To maximize your benefit from this check, be sure that you consistently run your dependency update tool. +If you want to increase your score in this category, sign up for automatic updates with a dependency update tool. Do note, however, that this check can only assess whether the dependency update tool is enabled, not that it is running. To maximize your benefit from this check, be sure that you consistently run and act on the information from your dependency update tool. ### Token-Permissions check helps you secure your workflows From b4d30eb7d459981fd763e5f7d308bf8780965b69 Mon Sep 17 00:00:00 2001 From: ariathaker <51683211+ariathaker@users.noreply.github.com> Date: Wed, 1 Nov 2023 06:04:41 -0700 Subject: [PATCH 09/13] Update beginner-checks.md Signed-off-by: ariathaker <51683211+ariathaker@users.noreply.github.com> Signed-off-by: ariathaker --- docs/beginner-checks.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/beginner-checks.md b/docs/beginner-checks.md index 9599986b0ee..6d60e1c4a1f 100644 --- a/docs/beginner-checks.md +++ b/docs/beginner-checks.md @@ -1,7 +1,5 @@ # Getting Started with Scorecard Checks for Supply Chain Security -If you are an open-source developer, you know that maintaining the security posture of a project can feel like a full-time job, but it can be easier with a little guidance. [Scorecard](https://github.com/ossf/scorecard#openssf-scorecard), an automated tool created [by the Open Source Security Foundation](https://openssf.org/) (OpenSSF), checks projects for security best practices and scores projects on a scale between 1 and 10. Maintainers can use the Scorecard checks as guidelines to improve their project's security practices. - Choosing which Scorecard checks to get started with as a project maintainer can be overwhelming. This page walks through some of the most important checks to start with for project improvement, focusing on the ones that give you the biggest payoff versus effort. They're broken down into three categories based on stages of the development process: setting up your project, accepting contributions from others, and packaging the project to release to the world. ## 1. Setting up your project @@ -29,11 +27,11 @@ Next, Scorecard’s [Dependency-Update-Tool check](https://github.com/ossf/score Automated processes like these save you time and are highly configurable; for example, you can set your bot to update dependencies every day or every week at the same time. -If you want to increase your score in this category, sign up for automatic updates with a dependency update tool. Do note, however, that this check can only assess whether the dependency update tool is enabled, not that it is running. To maximize your benefit from this check, be sure that you consistently run and act on the information from your dependency update tool. +If you want to increase your score in this category, sign up for automatic updates with a dependency update tool. Keep in mind, though, that this check can only show that the dependency update tool is enabled, not that it is running. To benefit as much as possible from this check, be sure that you consistently run and act on the information from your dependency update tool. ### Token-Permissions check helps you secure your workflows -We suggest addressing the [Token-Permissions check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions) next because it takes just a few minutes to “set it and forget it” and secure your workflows. The check warns you when your project’s top-level tokens have `write` access instead of the more restrictive `read` access. Not all `write` access permissions need to be eliminated; some workflows may genuinely require them. However, ensuring your top-level permissions have `read` access helps your project adhere to the principle of least privilege, which means that permissions are granted based on the minimal necessary access to perform a function. Projects that have top-level tokens set to `write` access for their automated workflows may be vulnerable to malicious code execution. By simply switching `write` to `read` you’ll be able to close off a powerful attack vector (exploiting compromised tokens that have write permissions and using them to inject malicious code into the project). +We suggest addressing the [Token-Permissions check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions) next because it takes just a few minutes to “set it and forget it” and secure your workflows. The check warns you when your project’s top-level tokens have `write` access instead of the more restrictive `read` access. Not all `write` access permissions need to be eliminated; some workflows may genuinely require them. But ensuring your top-level permissions have `read` access helps your project follow the principle of least privilege, which means that permissions are granted based on the minimal necessary access to perform a function. Projects that have top-level tokens set to `write` access for their automated workflows may be vulnerable to malicious code execution. By simply switching `write` to `read` you’ll be able to close off a powerful attack vector (exploiting compromised tokens that have write permissions and using them to inject malicious code into the project). To change the default setting for token permissions, add the following to the top of your workflow: From 766a2bf09eea108c1d204d410d3ea773f6ecdeb6 Mon Sep 17 00:00:00 2001 From: ariathaker <51683211+ariathaker@users.noreply.github.com> Date: Wed, 15 Nov 2023 20:44:35 -0800 Subject: [PATCH 10/13] Update beginner-checks.md Signed-off-by: ariathaker <51683211+ariathaker@users.noreply.github.com> --- docs/beginner-checks.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/beginner-checks.md b/docs/beginner-checks.md index 6d60e1c4a1f..ef72b1b48fa 100644 --- a/docs/beginner-checks.md +++ b/docs/beginner-checks.md @@ -1,6 +1,6 @@ # Getting Started with Scorecard Checks for Supply Chain Security -Choosing which Scorecard checks to get started with as a project maintainer can be overwhelming. This page walks through some of the most important checks to start with for project improvement, focusing on the ones that give you the biggest payoff versus effort. They're broken down into three categories based on stages of the development process: setting up your project, accepting contributions from others, and packaging the project to release to the world. +Choosing which Scorecard checks to get started with as a project maintainer can be overwhelming. This page walks through some of the most important checks to start with for project improvement, focusing on the ones that give you the biggest payoff versus effort. They're broken down into three categories based on stages of the development process: [setting up your project](#setting-up-your-project), [accepting contributions from others](#manage-contributions-to-your-project), and [packaging the project to release to the world](#package-and-release-your-project). ## 1. Setting up your project @@ -31,7 +31,7 @@ If you want to increase your score in this category, sign up for automatic updat ### Token-Permissions check helps you secure your workflows -We suggest addressing the [Token-Permissions check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions) next because it takes just a few minutes to “set it and forget it” and secure your workflows. The check warns you when your project’s top-level tokens have `write` access instead of the more restrictive `read` access. Not all `write` access permissions need to be eliminated; some workflows may genuinely require them. But ensuring your top-level permissions have `read` access helps your project follow the principle of least privilege, which means that permissions are granted based on the minimal necessary access to perform a function. Projects that have top-level tokens set to `write` access for their automated workflows may be vulnerable to malicious code execution. By simply switching `write` to `read` you’ll be able to close off a powerful attack vector (exploiting compromised tokens that have write permissions and using them to inject malicious code into the project). +We suggest addressing the [Token-Permissions check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions) next because it takes just a few minutes to “set it and forget it” and secure your workflows. The check warns you when your project’s top-level tokens have `write` access instead of the more restrictive `read` access. Not all `write` access permissions need to be eliminated; some workflows may genuinely require them. But ensuring your top-level permissions have `read` access helps your project follow the principle of least privilege, which means that permissions are granted based on the minimal necessary access to perform a function. Projects that don't follow least privilege, particularly around `write` permissions, expose themselves to undue risks of attack if their workflow dependencies become compromised. By simply switching `write` to `read` you’ll be able to close off a powerful attack vector (exploiting compromised tokens that have write permissions and using them to inject malicious code into the project). To change the default setting for token permissions, add the following to the top of your workflow: @@ -59,12 +59,10 @@ Deciding how to securely share your code can be difficult. Building locally on y ### Packaging check verifies if a project is published as a package -The [Packaging check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#packaging) assesses whether a project has been published as a package. The check is currently limited to repositories hosted on GitHub. It looks for [GitHub packaging workflows](https://docs.github.com/packages/learn-github-packages/publishing-a-package) and language-specific GitHub Actions that upload the package to a corresponding hub, like npm or PyPI. +The [Packaging check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#packaging) assesses whether a project has been published as a package. The check is currently limited to repositories hosted on GitHub. It looks for [GitHub packaging workflows](https://docs.github.com/packages/learn-github-packages/publishing-a-package) and language-specific GitHub Actions that upload the package to a corresponding hub, like npm or PyPI. Another benefit to releasing projects as packages is reproducibility—the version that new users can download and execute is identical to the one that you and other contributors have already reviewed. Packages also have clear versioning documentation that makes it easier to track whether any newly discovered security issues are applicable to your project. Packaging your projects makes it easier for users to receive security patches as updates. It also provides information about the release details to your users, which opens the door to more collaboration from your open-source peers. -Another benefit to releasing projects as packages is reproducibility—the version that new users can download and execute is identical to the one that you and other contributors have already reviewed. Packages also have clear versioning documentation that makes it easier to track whether any newly discovered security issues are applicable to your project. - ## Customize your checks to your project’s needs Based on the specifics of your project, not all the checks offered by Scorecard or discussed on this page may apply to you. For example, if you are the sole maintainer of an open-source project, the “Code Review” check would not be usable for your project. From 73277c69f9cd7a083a6b116be2cbbe80a6915791 Mon Sep 17 00:00:00 2001 From: ariathaker <51683211+ariathaker@users.noreply.github.com> Date: Mon, 20 Nov 2023 22:51:41 -0800 Subject: [PATCH 11/13] Update beginner-checks.md Signed-off-by: ariathaker <51683211+ariathaker@users.noreply.github.com> --- docs/beginner-checks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/beginner-checks.md b/docs/beginner-checks.md index ef72b1b48fa..1c5f9be7c02 100644 --- a/docs/beginner-checks.md +++ b/docs/beginner-checks.md @@ -1,6 +1,6 @@ # Getting Started with Scorecard Checks for Supply Chain Security -Choosing which Scorecard checks to get started with as a project maintainer can be overwhelming. This page walks through some of the most important checks to start with for project improvement, focusing on the ones that give you the biggest payoff versus effort. They're broken down into three categories based on stages of the development process: [setting up your project](#setting-up-your-project), [accepting contributions from others](#manage-contributions-to-your-project), and [packaging the project to release to the world](#package-and-release-your-project). +Choosing which Scorecard checks to get started with as a project maintainer can be overwhelming. This page walks through some of the most important checks to start with for project improvement, focusing on the ones that give you the biggest payoff versus effort. They're broken down into three categories based on stages of the development process: [setting up your project](#1-setting-up-your-project), [accepting contributions from others](#2-manage-contributions-to-your-project), and [packaging the project to release to the world](#3-package-and-release-your-project). ## 1. Setting up your project From b47d3b9e12e484792e82678b021cf518e6c68c5f Mon Sep 17 00:00:00 2001 From: ariathaker <51683211+ariathaker@users.noreply.github.com> Date: Wed, 22 Nov 2023 13:59:29 -0800 Subject: [PATCH 12/13] Update beginner-checks.md Signed-off-by: ariathaker <51683211+ariathaker@users.noreply.github.com> --- docs/beginner-checks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/beginner-checks.md b/docs/beginner-checks.md index 1c5f9be7c02..f46e99a8181 100644 --- a/docs/beginner-checks.md +++ b/docs/beginner-checks.md @@ -31,7 +31,7 @@ If you want to increase your score in this category, sign up for automatic updat ### Token-Permissions check helps you secure your workflows -We suggest addressing the [Token-Permissions check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions) next because it takes just a few minutes to “set it and forget it” and secure your workflows. The check warns you when your project’s top-level tokens have `write` access instead of the more restrictive `read` access. Not all `write` access permissions need to be eliminated; some workflows may genuinely require them. But ensuring your top-level permissions have `read` access helps your project follow the principle of least privilege, which means that permissions are granted based on the minimal necessary access to perform a function. Projects that don't follow least privilege, particularly around `write` permissions, expose themselves to undue risks of attack if their workflow dependencies become compromised. By simply switching `write` to `read` you’ll be able to close off a powerful attack vector (exploiting compromised tokens that have write permissions and using them to inject malicious code into the project). +We suggest addressing the [Token-Permissions check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions) next because it takes just a few minutes to “set it and forget it” and secure your workflows. The check warns you when your project’s top-level tokens have `write` access instead of the more restrictive `read` access. Not all `write` access permissions need to be eliminated; some workflows may genuinely require them. But ensuring your top-level permissions have `read` access helps your project follow the principle of least privilege, which means that permissions are granted based on the minimal necessary access to perform a function. Projects that have top-level tokens set to `write` are granting more access than necessary to their automated workflow dependencies. If those dependencies were ever compromised, they could become an attack vector, and could be vulnerable to malicious code execution. To change the default setting for token permissions, add the following to the top of your workflow: From cfa1a9a4cf6664e82c9d3374c15c1dc7d8a9145d Mon Sep 17 00:00:00 2001 From: ariathaker <51683211+ariathaker@users.noreply.github.com> Date: Wed, 29 Nov 2023 12:19:26 -0800 Subject: [PATCH 13/13] Update beginner-checks.md Signed-off-by: ariathaker <51683211+ariathaker@users.noreply.github.com> --- docs/beginner-checks.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/beginner-checks.md b/docs/beginner-checks.md index f46e99a8181..dfca3765a53 100644 --- a/docs/beginner-checks.md +++ b/docs/beginner-checks.md @@ -2,6 +2,8 @@ Choosing which Scorecard checks to get started with as a project maintainer can be overwhelming. This page walks through some of the most important checks to start with for project improvement, focusing on the ones that give you the biggest payoff versus effort. They're broken down into three categories based on stages of the development process: [setting up your project](#1-setting-up-your-project), [accepting contributions from others](#2-manage-contributions-to-your-project), and [packaging the project to release to the world](#3-package-and-release-your-project). +Note: not every Scorecard check or topic mentioned on this page might be relevant to your project. See below for more on [customizing your checks to your needs](#customize-your-checks-to-your-projects-needs). + ## 1. Setting up your project Start your project off strong by focusing on Scorecard checks that help you secure your project dependencies and workflows. @@ -59,7 +61,9 @@ Deciding how to securely share your code can be difficult. Building locally on y ### Packaging check verifies if a project is published as a package -The [Packaging check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#packaging) assesses whether a project has been published as a package. The check is currently limited to repositories hosted on GitHub. It looks for [GitHub packaging workflows](https://docs.github.com/packages/learn-github-packages/publishing-a-package) and language-specific GitHub Actions that upload the package to a corresponding hub, like npm or PyPI. Another benefit to releasing projects as packages is reproducibility—the version that new users can download and execute is identical to the one that you and other contributors have already reviewed. Packages also have clear versioning documentation that makes it easier to track whether any newly discovered security issues are applicable to your project. +The [Packaging check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#packaging) assesses whether a project has been published as a package. The check is currently limited to repositories hosted on GitHub. It looks for [GitHub packaging workflows](https://docs.github.com/packages/learn-github-packages/publishing-a-package) and language-specific GitHub Actions that upload the package to a corresponding hub, like npm or PyPI. + +Another benefit to releasing projects as packages is reproducibility—the version that new users can download and execute is identical to the one that you and other contributors have already reviewed. Packages also have clear versioning documentation that makes it easier to track whether any newly discovered security issues are applicable to your project. Packaging your projects makes it easier for users to receive security patches as updates. It also provides information about the release details to your users, which opens the door to more collaboration from your open-source peers.