📖 Tweak Best Practices badge description to clarify things (ossf#2907)

* Tweak Best Practices badge description to clarify things

Signed-off-by: David A. Wheeler <[email protected]>

* Provided clearer message when there's no BP badge detected

Signed-off-by: David A. Wheeler <[email protected]>

* Remove extra line that shouldn't be there

Signed-off-by: David A. Wheeler <[email protected]>

---------

Signed-off-by: David A. Wheeler <[email protected]>
Signed-off-by: Avishay <[email protected]>

Author: david-a-wheeler

README.md

@@ -438,7 +438,7 @@ Name        | Description                               | Risk Level | Token Req
 [Binary-Artifacts](docs/checks.md#binary-artifacts)             | Is the project free of checked-in binaries?     | High               | PAT, GITHUB_TOKEN   | Fully Supported |
 [Branch-Protection](docs/checks.md#branch-protection)           | Does the project use [Branch Protection](https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/about-protected-branches) ?                                                                                                                                                                       | High | PAT (`repo` or `repo> public_repo`), GITHUB_TOKEN    | Fully Supported | certain settings are only supported with a maintainer PAT
 [CI-Tests](docs/checks.md#ci-tests)                             | Does the project run tests in CI, e.g. [GitHub Actions](https://docs.github.com/en/free-pro-team@latest/actions), [Prow](https://github.com/kubernetes/test-infra/tree/master/prow)?                                                                                                                                         | Low | PAT, GITHUB_TOKEN   | Unsupported
-[CII-Best-Practices](docs/checks.md#cii-best-practices)         | Does the project have an [OpenSSF (formerly CII) Best Practices Badge](https://bestpractices.coreinfrastructure.org/en)?                                                                                                                                                                                                                         | Low  | PAT, GITHUB_TOKEN   | Fully Supported |
+[CII-Best-Practices](docs/checks.md#cii-best-practices)         | Has the project earned an [OpenSSF (formerly CII) Best Practices Badge](https://bestpractices.coreinfrastructure.org) at the passing, silver, or gold level?                                                                                                                                                                 | Low  | PAT, GITHUB_TOKEN   | Fully Supported |
 [Code-Review](docs/checks.md#code-review)                       | Does the project practice code review before code is merged?                                                                                                                                                                                                                                                                 | High | PAT, GITHUB_TOKEN   | Fully Supported |
 [Contributors](docs/checks.md#contributors)                     | Does the project have contributors from at least two different organizations?                                                                                                                                                                                                                                                | Low | PAT, GITHUB_TOKEN   | Fully Supported |
 [Dangerous-Workflow](docs/checks.md#dangerous-workflow)         | Does the project avoid dangerous coding patterns in GitHub Action workflows?                                                                                                                                                                                                                                                 | Critical | PAT, GITHUB_TOKEN   | Unsupported |

checks/evaluation/cii_best_practices.go

@@ -41,7 +41,7 @@ func CIIBestPractices(name string, _ checker.DetailLogger, r *checker.CIIBestPra
 	var results checker.CheckResult
 	switch r.Badge {
 	case clients.NotFound:
-		results = checker.CreateMinScoreResult(name, "no badge detected")
+		results = checker.CreateMinScoreResult(name, "no effort to earn an OpenSSF best practices badge detected")
 	case clients.InProgress:
 		msg := fmt.Sprintf("badge detected: %v", r.Badge)
 		results = checker.CreateResultWithScore(name, msg, inProgressScore)

docs/checks.md

@@ -158,38 +158,21 @@ If a project's system was not detected and you think it should be, please
 
 Risk: `Low` (possibly not following security best practices)
 
-This check determines whether the project has earned an [OpenSSF (formerly CII) Best Practices Badge](https://bestpractices.coreinfrastructure.org/),
-which indicates that the project uses a set of security-focused best development practices for open
+This check determines whether the project has earned an [OpenSSF (formerly CII) Best Practices Badge](https://bestpractices.coreinfrastructure.org/) at the passing, silver, or gold level.
+The OpenSSF Best Practices badge indicates whether or not that the project uses a set of security-focused best development practices for open
 source software. The check uses the URL for the Git repo and the OpenSSF Best Practices badge API.
 
 The OpenSSF Best Practices badge has 3 tiers: passing, silver, and gold. We give
-full credit to projects that meet the [gold criteria](https://bestpractices.coreinfrastructure.org/criteria/2), which is a
-significant achievement for many projects. Lower scores represent a project that
-is at least working to achieve a badge, with increasingly more points awarded as
-more criteria are met.
-
-- [gold badge](https://bestpractices.coreinfrastructure.org/en/criteria/2): 10
-- [silver badge](https://bestpractices.coreinfrastructure.org/en/criteria/1): 7
-- [passing badge](https://bestpractices.coreinfrastructure.org/en/criteria/0): 5
-- in progress badge: 2
+full credit to projects that meet the [gold criteria](https://bestpractices.coreinfrastructure.org/criteria/2), which is a significant achievement for projects and requires multiple developers in the project.
+Lower scores represent a project that has met the silver criteria, met the passing criteria, or is working to achieve the passing badge, with increasingly more points awarded as more criteria are met. Note that even meeting the passing criteria is a significant achievement.
 
-To earn the passing badge, the project MUST:
-
-  - publish the process for reporting vulnerabilities on the project site
-  - provide a working build system that can automatically rebuild the software
-    from source code (where applicable)
-  - have a general policy that tests will be added to an automated test suite
-    when major new functionality is added
-  - meet various cryptography criteria where applicable
-  - have at least one primary developer who knows how to design secure software
-  - have at least one primary developer who knows of common kinds of errors
-    that lead to vulnerabilities in this kind of software (and at least one
-    method to counter or mitigate each of them)
-  - apply at least one static code analysis tool (beyond compiler warnings and
-    "safe" language modes) to any proposed major production release.
+- [gold badge](https://bestpractices.coreinfrastructure.org/criteria/2): 10
+- [silver badge](https://bestpractices.coreinfrastructure.org/criteria/1): 7
+- [passing badge](https://bestpractices.coreinfrastructure.org/criteria/0): 5
+- in progress badge: 2
 
 Some of these criteria overlap with other Scorecard checks.
- 
+However, note that in those overlapping cases, Scorecard can only report what it can automatically detect, while the OpenSSF Best Practices badge can report on claims and claim justifications from people (this counters false negatives and positives but has the challenge of requiring additional work from people).
 
 **Remediation steps**
 - Sign up for the [OpenSSF Best Practices program](https://bestpractices.coreinfrastructure.org/).

docs/checks/internal/checks.yaml

@@ -255,37 +255,21 @@ checks:
     description: |
       Risk: `Low` (possibly not following security best practices)
 
-      This check determines whether the project has earned an [OpenSSF (formerly CII) Best Practices Badge](https://bestpractices.coreinfrastructure.org/),
-      which indicates that the project uses a set of security-focused best development practices for open
+      This check determines whether the project has earned an [OpenSSF (formerly CII) Best Practices Badge](https://bestpractices.coreinfrastructure.org/) at the passing, silver, or gold level.
+      The OpenSSF Best Practices badge indicates whether or not that the project uses a set of security-focused best development practices for open
       source software. The check uses the URL for the Git repo and the OpenSSF Best Practices badge API.
 
       The OpenSSF Best Practices badge has 3 tiers: passing, silver, and gold. We give
-      full credit to projects that meet the [gold criteria](https://bestpractices.coreinfrastructure.org/criteria/2), which is a
-      significant achievement for many projects. Lower scores represent a project that
-      is at least working to achieve a badge, with increasingly more points awarded as
-      more criteria are met.
-
-      - [gold badge](https://bestpractices.coreinfrastructure.org/en/criteria/2): 10
-      - [silver badge](https://bestpractices.coreinfrastructure.org/en/criteria/1): 7
-      - [passing badge](https://bestpractices.coreinfrastructure.org/en/criteria/0): 5
-      - in progress badge: 2
+      full credit to projects that meet the [gold criteria](https://bestpractices.coreinfrastructure.org/criteria/2), which is a significant achievement for projects and requires multiple developers in the project.
+      Lower scores represent a project that has met the silver criteria, met the passing criteria, or is working to achieve the passing badge, with increasingly more points awarded as more criteria are met. Note that even meeting the passing criteria is a significant achievement.
 
-      To earn the passing badge, the project MUST:
-
-        - publish the process for reporting vulnerabilities on the project site
-        - provide a working build system that can automatically rebuild the software
-          from source code (where applicable)
-        - have a general policy that tests will be added to an automated test suite
-          when major new functionality is added
-        - meet various cryptography criteria where applicable
-        - have at least one primary developer who knows how to design secure software
-        - have at least one primary developer who knows of common kinds of errors
-          that lead to vulnerabilities in this kind of software (and at least one
-          method to counter or mitigate each of them)
-        - apply at least one static code analysis tool (beyond compiler warnings and
-          "safe" language modes) to any proposed major production release.
+      - [gold badge](https://bestpractices.coreinfrastructure.org/criteria/2): 10
+      - [silver badge](https://bestpractices.coreinfrastructure.org/criteria/1): 7
+      - [passing badge](https://bestpractices.coreinfrastructure.org/criteria/0): 5
+      - in progress badge: 2
 
       Some of these criteria overlap with other Scorecard checks.
+      However, note that in those overlapping cases, Scorecard can only report what it can automatically detect, while the OpenSSF Best Practices badge can report on claims and claim justifications from people (this counters false negatives and positives but has the challenge of requiring additional work from people).
     remediation:
       - >-
         Sign up for the [OpenSSF Best Practices program](https://bestpractices.coreinfrastructure.org/).