✨ SARIF 2: add short description to checks.yml (#848)

* short desc

* validate new field

* typos

* comments

* fixed

checks/automatic_dependency_update.go

@@ -20,29 +20,29 @@ import (
 	"github.com/ossf/scorecard/v2/checker"
 )
 
-// CheckAutomaticDependencyUpdate is the exported name for Automatic-Depdendency-Update.
-const CheckAutomaticDependencyUpdate = "Automatic-Dependency-Update"
+// CheckDependencyUpdateTool is the exported name for Automatic-Depdendency-Update.
+const CheckDependencyUpdateTool = "Dependency-Update-Tool"
 
 //nolint
 func init() {
-	registerCheck(CheckAutomaticDependencyUpdate, AutomaticDependencyUpdate)
+	registerCheck(CheckDependencyUpdateTool, AutomaticDependencyUpdate)
 }
 
 // AutomaticDependencyUpdate will check the repository if it contains Automatic dependency update.
 func AutomaticDependencyUpdate(c *checker.CheckRequest) checker.CheckResult {
 	var r bool
-	err := CheckIfFileExists(CheckAutomaticDependencyUpdate, c, fileExists, &r)
+	err := CheckIfFileExists(CheckDependencyUpdateTool, c, fileExists, &r)
 	if err != nil {
-		return checker.CreateRuntimeErrorResult(CheckAutomaticDependencyUpdate, err)
+		return checker.CreateRuntimeErrorResult(CheckDependencyUpdateTool, err)
 	}
 	if !r {
 		c.Dlogger.Warn("dependabot not detected")
 		c.Dlogger.Warn("renovatebot not detected")
-		return checker.CreateMinScoreResult(CheckAutomaticDependencyUpdate, "no update tool detected")
+		return checker.CreateMinScoreResult(CheckDependencyUpdateTool, "no update tool detected")
 	}
 
 	// High score result.
-	return checker.CreateMaxScoreResult(CheckAutomaticDependencyUpdate, "update tool detected")
+	return checker.CreateMaxScoreResult(CheckDependencyUpdateTool, "update tool detected")
 }
 
 // fileExists will validate the if frozen dependencies file name exists.

docs/checks.md

@@ -18,18 +18,9 @@ The check currently works by looking for commits within the last 90 days, and ou
 **Remediation steps**
 - There is *NO* remediation work needed here. This is just to indicate your project activity and maintenance commitment.
 
-## Automatic-Dependency-Update 
-
-This check tries to determine if a project has dependencies automatically updated.
-Not updating dependencies makes a project vulnerable to known flaws and prone to attacks. A low score is therefore considered `High` risk.
-The checks looks for [dependabot](https://dependabot.com/docs/config-file/) or [renovatebot](https://docs.renovatebot.com/configuration-options/). This check only looks if it is enabled and does not ensure that it is run and pull requests are merged. 
-
-**Remediation steps**
-- Signup for automatic dependency updates with dependabot or renovatebot and place the config file in the locations that are recommended by these tools.
-
 ## Binary-Artifacts 
 
-This check tries to determine if a project has binary artifacts in the source repository.
+This check tries to determine if the project has binary artifacts in the source repository.
 Binaries are a threat to auditability and vulnerability management. In addition, a binary could be compromised or malicious. A low score is therefore considered `High` risk. 
 
 **Remediation steps**
@@ -67,7 +58,7 @@ The check uses the URL for the Git repo and the CII API.
 
 ## Code-Review 
 
-This check tries to determine if a project requires code review before pull requests are merged.
+This check tries to determine if the project requires code review before pull requests are merged.
 Reviewing code improves the quality of code in general. In addition, it ensures compromised contributors cannot intentionally inject malicious code. A low score is therefore considered `High` risk.
 The check first tries to detect if Branch-Protection is enabled on the default branch ,and the number of reviewers is at least 1. If this fails, it checks if the recent (~30) commits have a Github-approved review or if the merger is different from the committer (implicit review). It also performs similar check for reviews using [Prow](https://github.com/kubernetes/test-infra/tree/master/prow#readme) (labels "lgtm" or "approved") and Gerrit ("Reviewed-on" and "Reviewed-by"). 
 
@@ -78,16 +69,25 @@ The check first tries to detect if Branch-Protection is enabled on the default b
 
 ## Contributors 
 
-This check tries to determine if a project has a set of contributors from multiple companies.
+This check tries to determine if the project has a set of contributors from multiple companies.
 Low score has 'Low' risk.
 The check works by looking at the authors of recent commits and checking the `Company` field on the GitHub user profile. A contributor must have at least 5 commits in the last 30 commits. The check succeeds if all contributors span at least 2 different companies. 
 
 **Remediation steps**
 - There is *NO* remediation work needed here. This is to provide some insights on which organization(s) have contributed to the project and making trust decisions based on that. But you can ask your contributors to join their respective organizations.
 
+## Dependency-Update-Tool 
+
+This check tries to determine if the project uses a dependency update tool.
+Not updating dependencies makes a project vulnerable to known flaws and prone to attacks. A low score is therefore considered `High` risk.
+The checks looks for [dependabot](https://dependabot.com/docs/config-file/) or [renovatebot](https://docs.renovatebot.com/configuration-options/). This check only looks if it is enabled and does not ensure that it is run and pull requests are merged. 
+
+**Remediation steps**
+- Signup for automatic dependency updates with dependabot or renovatebot and place the config file in the locations that are recommended by these tools.
+
 ## Fuzzing 
 
-This check tries to determine if the project uses a fuzzing system.
+This check tries to determine if the project uses fuzzing.
 Fuzzing is important to reduce the number of vulnerabilities in code. A low score is considered 'Medium' risk.
 The check currently works by checking if the repo name is in the [OSS-Fuzz](https://github.com/google/oss-fuzz) project list. 
 
@@ -106,7 +106,7 @@ The check currently looks for [GitHub packaging workflows]( https://docs.github.
 
 ## Pinned-Dependencies 
 
-This check tries to determine if a project has declared and pinned its dependencies.
+This check tries to determine if the project has declared and pinned its dependencies.
 Pinning dependencies is important to mitigate compromised dependencies from undermining the security of the project. Low score is therefore considered `Medium` risk.
 The checks works by (1) looking for the following files in the root directory: go.mod, go.sum (Golang), package-lock.json, npm-shrinkwrap.json (Javascript), requirements.txt, pipfile.lock (Python), gemfile.lock (Ruby), cargo.lock (Rust), yarn.lock (package manager), composer.lock (PHP), vendor/, third_party/, third-party/; (2) looks for unpinned dependencies in Dockerfiles, shell scripts and GitHub workflows. 
 
@@ -118,7 +118,7 @@ The checks works by (1) looking for the following files in the root directory: g
 
 ## SAST 
 
-This check tries to determine if the project uses static code analysis systems.
+This check tries to determine if the project uses static code analysis.
 SAST tool may prevent known classes of bugs to be inadvertently introduced in the codebase. A low score is considered `Medium` risk.
 The checks currently looks for known Github apps such as [github-code-scanning](https://securitylab.github.com/tools/codeql) (codeql) and sonarcloud in the recent (~30) merged PRs. The check also looks for the use of "github/codeql-action" in a GitHub workflow. 
 
@@ -127,15 +127,15 @@ The checks currently looks for known Github apps such as [github-code-scanning](
 
 ## Security-Policy 
 
-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. 
+This check tries to determine if the 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 constitutes a vulnerability and a way to report it securely (e.g. issue tracker with private issue support, encrypted email with a published public key).
 
 ## Signed-Releases 
 
-This check tries to determine if a project cryptographically signs release artifacts.
+This check tries to determine if the project cryptographically signs release artifacts.
 Signed releases attest to the provenance of the artifact. A low score is considered 'High' risk.
 It works by looking for filenames: *.minisig (https://github.com/jedisct1/minisign), *.asc (pgp), *.sign. for the last 5 GitHub releases. The check does not verify the signatures. 
 
@@ -149,7 +149,7 @@ It works by looking for filenames: *.minisig (https://github.com/jedisct1/minisi
 
 ## Token-Permissions 
 
-This check tries to determine if a project's GitHub workflows follow the principle of least privilege, i.e. if the GitHub tokens are set read-only by default.
+This check tries to determine if the project's GitHub workflows follow the principle of least privilege, i.e. if the GitHub tokens are set read-only by default.
 Attackers may use a compromised token with write access to push malicious code into the project. A low score is therefore considered `High` risk.
 For each workflow yaml file, the check looks for the permission definitions. To obtain the highest score, the permissions should be set as read-only at the [top level](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#permissions) and the required write permissions should be declared at the [run-level](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idpermissions). The check cannot detect if the "read-only" GitHub permission settings is enabled, as there is no API available. 
 

docs/checks/checks.yaml

@@ -17,6 +17,7 @@
 checks:
   Active:
     risk: High
+    short: Determines if the project is "actively maintained".
     description: >-
       This check tries to determine if the project is "actively maintained".
 
@@ -30,10 +31,11 @@ checks:
       - >-
         There is *NO* remediation work needed here. This is just to indicate
         your project activity and maintenance commitment.
-  Automatic-Dependency-Update:
+  Dependency-Update-Tool:
     risk: High
+    short: Determines if the project uses a dependency update tool.
     description: >-
-      This check tries to determine if a project has dependencies automatically updated.
+      This check tries to determine if the project uses a dependency update tool.
 
       Not updating dependencies makes a project vulnerable to known flaws and prone to attacks.
       A low score is therefore considered `High` risk.
@@ -48,8 +50,9 @@ checks:
         file in the locations that are recommended by these tools.
   Binary-Artifacts:
     risk: High
+    short: Determines if the project has binary artifacts in the source repository.
     description: >-
-      This check tries to determine if a project has binary artifacts in the source repository.
+      This check tries to determine if the project has binary artifacts in the source repository.
 
       Binaries are a threat to auditability and vulnerability management.
       In addition, a binary could be compromised or malicious.
@@ -61,6 +64,7 @@ checks:
         Build from source.
   Branch-Protection:
     risk: High
+    short: Determines if the default and release branches are protected with GitHub's branch protection settings.
     description: >-
       [Branch protection](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)
       allows defining rules to enforce certain workflows for
@@ -84,6 +88,7 @@ checks:
         [here](https://docs.github.com/en/github/administering-a-repository/managing-a-branch-protection-rule).
   CI-Tests:
     risk: Low
+    short: Determines if the project runs tests before pull requests are merged.
     description: >-
       This check tries to determine if the project runs tests before pull
       requests are merged.
@@ -107,6 +112,7 @@ checks:
         [Prow](https://github.com/kubernetes/test-infra/tree/master/prow), etc).
   CII-Best-Practices:
     risk: Low
+    short: Determines if the project has a CII Best Practices Badge.
     description: >-
       This check tries to determine if the project has a [CII Best Practices
       Badge](https://bestpractices.coreinfrastructure.org/en).
@@ -121,8 +127,9 @@ checks:
         program](https://bestpractices.coreinfrastructure.org/en).
   Code-Review:
     risk: High
+    short: Determines if the project requires code review before pull requests are merged.
     description: >-
-      This check tries to determine if a project requires code review before
+      This check tries to determine if the project requires code review before
       pull requests are merged.
 
       Reviewing code improves the quality of code in general. In addition, it ensures
@@ -148,8 +155,9 @@ checks:
         [GitHub](https://docs.github.com/en/github/administering-a-repository/about-protected-branches#include-administrators)
   Contributors:
     risk: Low
+    short: Determines if the project has a set of contributors from multiple companies.
     description: >-
-      This check tries to determine if a project has a set of contributors from
+      This check tries to determine if the project has a set of contributors from
       multiple companies.
 
       Low score has 'Low' risk.
@@ -166,8 +174,9 @@ checks:
         to join their respective organizations.
   Fuzzing:
     risk: Medium
+    short: Determines if the project uses fuzzing.
     description: >-
-      This check tries to determine if the project uses a fuzzing system.
+      This check tries to determine if the project uses fuzzing.
 
       Fuzzing is important to reduce the number of vulnerabilities in code.
       A low score is considered 'Medium' risk.
@@ -180,6 +189,7 @@ checks:
         [here](https://google.github.io/oss-fuzz/).
   Packaging:
     risk: Medium
+    short: Determines if the project is published as a package that other developers can install/download.
     description:
       This check tries to determine if the project is published as a package that other developers can install/download.
 
@@ -194,8 +204,9 @@ checks:
       - Use a GitHub action to release your package to language-specific hubs.
   Pinned-Dependencies:
     risk: Medium
+    short: Determines if the project has declared and pinned its dependencies.
     description: >-
-      This check tries to determine if a project has declared and pinned its
+      This check tries to determine if the project has declared and pinned its
       dependencies.
 
       Pinning dependencies is important to mitigate compromised dependencies
@@ -229,9 +240,9 @@ checks:
         or [renovate bot](https://github.com/renovatebot/renovate).
   SAST:
     risk: Medium
+    short: Determines if the project uses static code analysis.
     description: >-
-      This check tries to determine if the project uses static code analysis
-      systems.
+      This check tries to determine if the project uses static code analysis.
 
       SAST tool may prevent known classes of bugs to be inadvertently
       introduced in the codebase. A low score is considered `Medium` risk.
@@ -245,8 +256,9 @@ checks:
         Run CodeQL checks in your CI/CD by following the instructions
         [here](https://github.com/github/codeql-action#usage).
   Security-Policy:
+    short: Determines if the project has published a security policy.
     description: >-
-      This check tries to determine if a project has published a security
+      This check tries to determine if the 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:
@@ -259,8 +271,9 @@ checks:
         support, encrypted email with a published public key).
   Signed-Releases:
     risk: High
+    short: Determines if the project cryptographically signs release artifacts.
     description: >-
-      This check tries to determine if a project cryptographically signs release
+      This check tries to determine if the project cryptographically signs release
       artifacts.
 
       Signed releases attest to the provenance of the artifact.
@@ -280,8 +293,9 @@ checks:
         [here](https://wiki.debian.org/Creating%20signed%20GitHub%20releases).
   Token-Permissions:
     risk: High
+    short: Determines if the project's GitHub workflows follow the principle of least privilege.
     description: >-
-      This check tries to determine if a project's GitHub workflows
+      This check tries to determine if the project's GitHub workflows
       follow the principle of least privilege, i.e. if the GitHub tokens
       are set read-only by default.
 
@@ -299,6 +313,7 @@ checks:
         GitHub's [documentation](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#permissions).
   Vulnerabilities:
     risk: High
+    short: Determines if the project has open, known unfixed vulnerabilities.
     description: >-
       This check determines if the project has open, unfixed 
       vulnerabilities using the [OSV](https://osv.dev) service.
@@ -308,4 +323,4 @@ checks:
     remediation:
       - >-
         Fix the vulnerabilities. The details of each vulnerability can be found
-        on <https://osv.dev>.
+        on <https://osv.dev>.

docs/checks/reader.go

@@ -30,6 +30,7 @@ var checksYAML []byte
 // Check defines expected check definition in checks.yaml.
 type Check struct {
 	Risk        string   `yaml:"-"`
+	Short       string   `yaml:"short"`
 	Description string   `yaml:"description"`
 	Remediation []string `yaml:"remediation"`
 }