Add remediation steps for various checks.

2024-11-04 03:52:31 +03:00 · 2021-01-26 23:42:57 -08:00 · 2021-01-26 23:42:57 -08:00 · 8493b0b9a0
commit 8493b0b9a0
parent 93373f7787
2 changed files with 115 additions and 21 deletions
--- a/README.md
+++ b/README.md
@ -149,7 +149,8 @@ The following checks are all run against the target project:
 | Branch-Protection  | Does the project use [Branch Protection](https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/about-protected-branches) ?                                                                                                                                             |
 | Packaging          | Does the project build and publish official packages from CI/CD, e.g. [GitHub Publishing](https://docs.github.com/en/free-pro-team@latest/actions/guides/about-packaging-with-github-actions#workflows-for-publishing-packages) ?                                                                  |

-To see detailed information on how each check works, see the [check-specific documentation page](checks.md).
+To see detailed information about each check and remediation steps,
+check out the [checks documentation page](checks.md).

 If you'd like to add a check, make sure it is something that meets the following criteria:

--- a/checks.md
+++ b/checks.md
@ -1,70 +1,163 @@
 # Check Documentation

-This page contains information on how each check works and calculates scores.
-All of these checks are basically "best-guesses" currently, and operate on a set of heuristics.
+This page contains information on how each check works and provide remediation
+steps to fix the failure. All of these checks are basically "best-guesses"
+currently, and operate on a set of heuristics.

-They are all subject to change, and have much room for improvement!
-If you have ideas for things to add, or new ways to detect things, please contribute!
+They are all subject to change, and have room for improvement!
+If you have ideas for things to add, or new ways to detect things,
+please contribute!

 ## Security-MD

-This check tries to determine if a project has published security policies.
-It works by looking for a file named `SECURITY.md` (case-insensitive) in a few well-known directories.
+This check tries to determine if a project has published a security policy.
+It works by looking for a file named `SECURITY.md` (case-insensitive) in a
+few well-known directories.
+
+**Remediation steps**:
+- Place a security policy file `SECURITY.md` in the root directory of your
+  repository. This makes it easily discoverable by a vulnerability reporter.
+- The file should contain information on what constitues a vulnerability and
+  a way to report it securely (e.g. issue tracker with private issue support,
+  encrypted email with a published public key).

 ## Contributors

-This check tries to determine if a project has a set of contributors from multiple companies.
-It works by looking at the authors of recent commits and checking the `Organization` field on the GitHub user profile.
+This check tries to determine if a project has a set of contributors from
+multiple companies. It works by looking at the authors of recent commits and
+checking the `Organization` field on the GitHub user profile.
+
+**Remediation steps**:
+- There is *NO* remediation work needed here. This is just to provide some
+  insights on which organization(s) have contributed to the project and
+  making trust decision based on that.

 ## Frozen-Deps

-This check tries to determine if a project has declared and pinned its dependencies.
-It works by looking for a set of well-known package management lock files.
+This check tries to determine if a project has declared and pinned its
+dependencies. It works by looking for a set of well-known package management
+lock files.
+
+**Remediation steps**:
+- Declare all your dependencies with specific versions in your package format
+  file (e.g. `package.json` for npm, `requirements.txt` for python). For C/C++,
+  check in the code from a trusted source and add a `README` on the specific
+  version used (and the archive SHA hashes).
+- If the package manager supports lock files (e.g. `package-lock.json` for npm),
+  make sure to check these in the source code as well. These files maintain
+  signatures for the entire dependency tree and saves from future exploitation
+  in case the package is compromised.

 ## Signed-Tags

 This check looks for cryptographically signed tags in the git history.

+**Remediation steps**:
+- Generate a new signing key.
+- Add your key to your source hosting provider.
+- Configure your key and email in git.
+- Publish the tag and then sign it with this key.
+- For GitHub, check out the steps
+  [here](https://docs.github.com/en/github/authenticating-to-github/signing-tags#further-reading). 
+
 ## Signed-Releases

-This check tries to determine if a project cryptographically signs release artifacts.
-It works by looking for well-known filenames within recently published GitHub releases.
+This check tries to determine if a project cryptographically signs release
+artifacts. It works by looking for well-known filenames within recently
+published GitHub releases.
+
+**Remediation steps**:
+- Publish the release.
+- Generate a signing key.
+- Download the release as an archive locally.
+- Sign the release archive with this key (should output a signature file).
+- Attach the signature file next to the release archive.
+- For GitHub, check out the steps
+  [here](https://wiki.debian.org/Creating%20signed%20GitHub%20releases).

 ## CI-Tests

-This check tries to determine if the project run tests before pull requests are merged.
-It works by looking for a set of well-known CI-system names in GitHub `CheckRuns` and `Statuses`.
+This check tries to determine if the project run tests before pull requests are
+merged. It works by looking for a set of well-known CI-system names in GitHub
+`CheckRuns` and `Statuses`.
+
+**Remediation steps**:
+- Check-in scripts that run all the tests in your repository.
+- Integrate those scripts with a CI/CD platform that runs it on every pull
+  request (e.g.
+  [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/introduction-to-github-actions),
+  [Prow](https://github.com/kubernetes/test-infra/tree/master/prow),
+  etc).

 ## Code-Review

-This check tries to determine if a project requires code review before pull requests are merged.
-It works by looking for a set of well-known code review system results in GitHub Pull Requests.
+This check tries to determine if a project requires code review before
+pull requests are merged. It works by looking for a set of well-known code
+review system results in GitHub Pull Requests.
+
+**Remediation steps**:
+- Follow security best practices by performing strict code reviews for every
+  new pull request.
+- Make "code reviews" mandatory in your repository configuration.
+  E.g. [GitHub](https://docs.github.com/en/github/administering-a-repository/about-protected-branches#require-pull-request-reviews-before-merging).
+- Enforce the rule for administrators / code owners as well.
+  E.g. [GitHub](https://docs.github.com/en/github/administering-a-repository/about-protected-branches#include-administrators)

 ## CII-Best-Practices

 This check tries to determine if the project has a [CII Best Practices Badge](https://bestpractices.coreinfrastructure.org/en).
 It uses the URL for the Git repo and the CII API.

+**Remediation steps**:
+- Sign up for the [CII Best Practices program](https://bestpractices.coreinfrastructure.org/en).
+
 ## Pull-Requests

-This check tries to determine if the project requires pull requests for all changes to the default branch.
-It works by looking at recent commits and using the GitHub API to search for associated pull requests.
+This check tries to determine if the project requires pull requests for all
+changes to the default branch. It works by looking at recent commits and using
+the GitHub API to search for associated pull requests.
+
+**Remediation steps**:
+- Always open a pull request for any change you intend to make, big or small.
+- Make "pull requests" mandatory in your repository configuration.
+  E.g. [GitHub](https://docs.github.com/en/github/administering-a-repository/about-protected-branches#require-pull-request-reviews-before-merging)
+- Enforce the rule for administrators / code owners as well.
+  E.g. [GitHub](https://docs.github.com/en/github/administering-a-repository/about-protected-branches#include-administrators)

 ## Fuzzing

 This check tries to determine if the project uses a fuzzing system.
-It currently works by checking if the repo name is in the [OSS-Fuzz](https://github.com/google/oss-fuzz) project list.
+It currently works by checking if the repo name is in the
+[OSS-Fuzz](https://github.com/google/oss-fuzz) project list.
+
+**Remediation steps**:
+- Integrate the project with OSS-Fuzz by following the instructions
+  [here](https://google.github.io/oss-fuzz/).

 ## SAST

 This check tries to determine if the project uses static code analysis systems.
 It currently works by looking for well-known results ([CodeQL](https://securitylab.github.com/tools/codeql), etc.) in GitHub pull requests.

+**Remediation steps**:
+- Run CodeQL checks in your CI/CD by following the instructions
+  [here](https://github.com/github/codeql-action#usage).
+
 ## Active

 This check tries to determine if the project is still "actively maintained".
-It currently works by looking for releases or commits within the last 90 days.
+It currently works by looking for commits within the last 90 days.
+
+**Remediation steps**:
+- There is *NO* remediation work needed here. This is just to indicate your
+  project activity and maintenance commitment.

 ## Branch-Protection

 This check tries to determine if the project has branch protection enabled.
+
+**Remediation steps**:
+- Enable branch protection settings in your source hosting provider to avoid
+  force pushes or deletion of your important branches.
+- For GitHub, check out the steps
+  [here](https://docs.github.com/en/github/administering-a-repository/managing-a-branch-protection-rule).