📖 Clarifications about the pinned dependencies check (#2319)

* Clarifications about the pinned dependencies check

The pinned dependencies check is confusing to authors of libraries,
who shouldn't be pinning the dependencies of the library. But it is
still valuable for flagging things which are used as part of
the build and release process for a library.

Signed-off-by: Jeremy Katz <jeremy@tidelift.com>

* Regenerate docs/checks.md

Signed-off-by: Jeremy Katz <jeremy@tidelift.com>

Signed-off-by: Jeremy Katz <jeremy@tidelift.com>

Author: katzj

docs/checks.md

@@ -438,13 +438,14 @@ issue](https://github.com/ossf/scorecard/issues/new/choose).
 
 Risk: `Medium` (possible compromised dependencies)
 
-This check tries to determine if the project pins its dependencies.
+This check tries to determine if the project pins dependencies used during its build and release process.
 A "pinned dependency" is a dependency that is explicitly set to a specific hash instead of
 allowing a mutable version or range of versions. It
 is currently limited to repositories hosted on GitHub, and does not support
 other source hosting repositories (i.e., Forges).
 
-The check works by looking for unpinned dependencies in Dockerfiles, shell scripts and GitHub workflows.
+The check works by looking for unpinned dependencies in Dockerfiles, shell scripts, and GitHub workflows
+which are used during the build and release process of a project.
 
 Pinned dependencies reduce several security risks:
 
@@ -464,7 +465,6 @@ However, pinning dependencies can inhibit software updates, either because of a
 security vulnerability or because the pinned version is compromised. Mitigate
 this risk by:
 
-  - [having applications and _not_ libraries pin to specific hashes](https://jbeckwith.com/2019/12/18/package-lock/);
   - using automated tools to notify applications when their dependencies are
     outdated;
   - quickly updating applications that do pin dependencies.
@@ -474,11 +474,10 @@ dependencies using the [GitHub dependency graph](https://docs.github.com/en/code
 
 
 **Remediation steps**
-- First determine if your project is producing a library or application. If it is a library, you generally don't want to pin dependencies of library users, and should not follow any remediation steps.
 - If your project is producing an application, 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.
-- For Dockerfiles, pin dependencies by hash. See [Dockerfile](https://github.com/ossf/scorecard/blob/main/cron/internal/worker/Dockerfile) for example. If you are using a manifest list to support builds across multiple architectures, you can pin to the manifest list hash instead of a single image hash. You can use a tool like [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md) to obtain the hash of the manifest list like in this [example](https://github.com/ossf/scorecard/issues/1773#issuecomment-1076699039).
-- For GitHub workflows, pin dependencies by hash. See [main.yaml](https://github.com/ossf/scorecard/blob/f55b86d6627cc3717e3a0395e03305e81b9a09be/.github/workflows/main.yml#L27) for example. To determine the permissions needed for your workflows, you may use [StepSecurity's online tool](https://app.stepsecurity.io/) by ticking the "Pin actions to a full length commit SHA". You may also tick the "Restrict permissions for GITHUB_TOKEN" to fix issues found by the Token-Permissions check.
+- If your project is producing an application and 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.
+- For Dockerfiles used in building and releasing your project, pin dependencies by hash. See [Dockerfile](https://github.com/ossf/scorecard/blob/main/cron/internal/worker/Dockerfile) for example. If you are using a manifest list to support builds across multiple architectures, you can pin to the manifest list hash instead of a single image hash. You can use a tool like [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md) to obtain the hash of the manifest list like in this [example](https://github.com/ossf/scorecard/issues/1773#issuecomment-1076699039).
+- For GitHub workflows used in building and releasing your project, pin dependencies by hash. See [main.yaml](https://github.com/ossf/scorecard/blob/f55b86d6627cc3717e3a0395e03305e81b9a09be/.github/workflows/main.yml#L27) for example. To determine the permissions needed for your workflows, you may use [StepSecurity's online tool](https://app.stepsecurity.io/) by ticking the "Pin actions to a full length commit SHA". You may also tick the "Restrict permissions for GITHUB_TOKEN" to fix issues found by the Token-Permissions check.
 - To help update your dependencies after pinning them, use tools such as
  Github's [dependabot](https://github.blog/2020-06-01-keep-all-your-packages-up-to-date-with-dependabot/)
 or [renovate bot](https://github.com/renovatebot/renovate).

docs/checks/internal/checks.yaml

@@ -447,17 +447,18 @@ checks:
     risk: Medium
     tags: supply-chain, security, dependencies
     repos: GitHub, local
-    short: Determines if the project has declared and pinned its dependencies.
+    short: Determines if the project has declared and pinned the dependencies of its build process.
     description: |
       Risk: `Medium` (possible compromised dependencies)
 
-      This check tries to determine if the project pins its dependencies.
+      This check tries to determine if the project pins dependencies used during its build and release process.
       A "pinned dependency" is a dependency that is explicitly set to a specific hash instead of
       allowing a mutable version or range of versions. It
       is currently limited to repositories hosted on GitHub, and does not support
       other source hosting repositories (i.e., Forges).
 
-      The check works by looking for unpinned dependencies in Dockerfiles, shell scripts and GitHub workflows.
+      The check works by looking for unpinned dependencies in Dockerfiles, shell scripts, and GitHub workflows
+      which are used during the build and release process of a project.
 
       Pinned dependencies reduce several security risks:
 
@@ -477,35 +478,30 @@ checks:
       security vulnerability or because the pinned version is compromised. Mitigate
       this risk by:
 
-        - [having applications and _not_ libraries pin to specific hashes](https://jbeckwith.com/2019/12/18/package-lock/);
         - using automated tools to notify applications when their dependencies are
           outdated;
         - quickly updating applications that do pin dependencies.
 
       For projects hosted on GitHub, you can learn more about
       dependencies using the [GitHub dependency graph](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph).
     remediation:
-      - >-
-        First determine if your project is producing a library or
-        application. If it is a library, you generally don't want to pin dependencies of
-        library users, and should not follow any remediation steps.
       - >-
         If your project is producing an application, 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
+        If your project is producing an application and 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.
       - >-
-        For Dockerfiles, pin dependencies by hash. See [Dockerfile](https://github.com/ossf/scorecard/blob/main/cron/internal/worker/Dockerfile) for example. If you are using a manifest list to support builds
+        For Dockerfiles used in building and releasing your project, pin dependencies by hash. See [Dockerfile](https://github.com/ossf/scorecard/blob/main/cron/internal/worker/Dockerfile) for example. If you are using a manifest list to support builds
         across multiple architectures, you can pin to the manifest list hash instead
         of a single image hash. You can use a tool like [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md)
         to obtain the hash of the manifest list like in this [example](https://github.com/ossf/scorecard/issues/1773#issuecomment-1076699039).
       - >-
-        For GitHub workflows, pin dependencies by hash. See [main.yaml](https://github.com/ossf/scorecard/blob/f55b86d6627cc3717e3a0395e03305e81b9a09be/.github/workflows/main.yml#L27) for example.
+        For GitHub workflows used in building and releasing your project, pin dependencies by hash. See [main.yaml](https://github.com/ossf/scorecard/blob/f55b86d6627cc3717e3a0395e03305e81b9a09be/.github/workflows/main.yml#L27) for example.
         To determine the permissions needed for your workflows, you may use [StepSecurity's online tool](https://app.stepsecurity.io/) by ticking
         the "Pin actions to a full length commit SHA". You may also tick the "Restrict permissions for GITHUB_TOKEN" to fix issues found
         by the Token-Permissions check.