🌱 Add lifecycle field to probes (#4147)

* add lifecycle field to probe yaml definitions Signed-off-by: Spencer Schrock <sschrock@google.com> * classify existing probes Some are listed as stable if they're not expected to change, others are listed as experimental if there are still expected changes. Signed-off-by: Spencer Schrock <sschrock@google.com> * add lifecycle to probe readme Signed-off-by: Spencer Schrock <sschrock@google.com> * fix linter Signed-off-by: Spencer Schrock <sschrock@google.com> * add lifecycle for new probe Signed-off-by: Spencer Schrock <sschrock@google.com> * add probe lifecycle to documentation Signed-off-by: Spencer Schrock <sschrock@google.com> --------- Signed-off-by: Spencer Schrock <sschrock@google.com>
ossf · Jul 2, 2024 · 6629b09 · 6629b09
1 parent 28337f1
commit 6629b09
Show file tree

Hide file tree

Showing 63 changed files with 240 additions and 0 deletions.
diff --git a/docs/probes.md b/docs/probes.md
diff --git a/docs/probes/internal/generate/main.go b/docs/probes/internal/generate/main.go
@@ -39,6 +39,7 @@ func printField(w io.Writer, name string, value any) {
 func printProbe(w io.Writer, p *pyaml.Probe) {
 	// short, motivation, implementation, outcome, remediation, ecosystem
 	fmt.Fprint(w, "\n"+"## "+p.ID+"\n\n")
+	printField(w, "Lifecycle", p.Lifecycle)
 	printField(w, "Description", p.Short)
 	printField(w, "Motivation", p.Motivation)
 	printField(w, "Implementation", p.Implementation)

diff --git a/finding/probe.go b/finding/probe.go
@@ -28,6 +28,9 @@ import (
 // RemediationEffort indicates the estimated effort necessary to remediate a finding.
 type RemediationEffort int
 
+// lifecycle indicates the probe's stability.
+type lifecycle string
+
 const (
 	// RemediationEffortNone indicates a no remediation effort.
 	RemediationEffortNone RemediationEffort = iota
@@ -37,6 +40,10 @@ const (
 	RemediationEffortMedium
 	// RemediationEffortHigh indicates a high remediation effort.
 	RemediationEffortHigh
+
+	lifecycleExperimental lifecycle = "experimental"
+	lifecycleStable       lifecycle = "stable"
+	lifecycleDeprecated   lifecycle = "deprecated"
 )
 
 // Remediation represents the remediation for a finding.
@@ -109,6 +116,9 @@ func validate(r *pyaml.Probe, probeID string) error {
 	if err := validateEcosystem(r.Ecosystem); err != nil {
 		return err
 	}
+	if err := validateLifecycle(lifecycle(r.Lifecycle)); err != nil {
+		return err
+	}
 	return nil
 }
 
@@ -178,6 +188,15 @@ func validateSupportedClients(r pyaml.Ecosystem) error {
 	return nil
 }
 
+func validateLifecycle(l lifecycle) error {
+	switch l {
+	case lifecycleExperimental, lifecycleStable, lifecycleDeprecated:
+		return nil
+	default:
+		return fmt.Errorf("%w: %v", errInvalid, fmt.Sprintf("lifecycle '%v'", l))
+	}
+}
+
 func parseFromYAML(content []byte) (*pyaml.Probe, error) {
 	r := pyaml.Probe{}
 

diff --git a/finding/probe_test.go b/finding/probe_test.go
@@ -90,6 +90,18 @@ func Test_probeFromBytes(t *testing.T) {
 			path: "testdata/invalid-client.yml",
 			err:  errInvalid,
 		},
+		{
+			name: "invalid lifecycle is an error",
+			id:   "invalid-lifecycle",
+			path: "testdata/invalid-lifecycle.yml",
+			err:  errInvalid,
+		},
+		{
+			name: "missing lifecycle is an error",
+			id:   "missing-lifecycle",
+			path: "testdata/missing-lifecycle.yml",
+			err:  errInvalid,
+		},
 	}
 	for _, tt := range tests {
 		tt := tt // Re-initializing variable so it is not changed while executing the closure below

diff --git a/finding/testdata/all-fields.yml b/finding/testdata/all-fields.yml
@@ -1,4 +1,5 @@
 id: all-fields
+lifecycle: stable
 short: short description
 motivation: >
   mot1

diff --git a/finding/testdata/effort-high.yml b/finding/testdata/effort-high.yml
@@ -1,4 +1,5 @@
 id: effort-high
+lifecycle: stable
 short: short description
 motivation: >
   line1

diff --git a/finding/testdata/effort-low.yml b/finding/testdata/effort-low.yml
@@ -1,4 +1,5 @@
 id: effort-low
+lifecycle: stable
 short: short description
 motivation: >
   line1

diff --git a/finding/testdata/invalid-client.yml b/finding/testdata/invalid-client.yml
@@ -1,4 +1,5 @@
 id: invalid-client
+lifecycle: stable
 short: short description
 motivation: >
   mot1

diff --git a/finding/testdata/invalid-effort.yml b/finding/testdata/invalid-effort.yml
@@ -1,4 +1,5 @@
 id: invalid-effort
+lifecycle: stable
 short: short description
 motivation: >
   line1

diff --git a/finding/testdata/invalid-language.yml b/finding/testdata/invalid-language.yml
@@ -1,4 +1,5 @@
 id: invalid-language
+lifecycle: stable
 short: short description
 motivation: >
   mot1

diff --git a/finding/testdata/invalid-lifecycle.yml b/finding/testdata/invalid-lifecycle.yml
@@ -0,0 +1,26 @@
+id: all-fields
+lifecycle: foo
+short: short description
+motivation: >
+  mot1
+  mot2
+implementation: >
+  impl1
+  impl2
+remediation:
+  onOutcome: False
+  effort: Low
+  text:
+    - step1
+    - step2 https://www.google.com/something
+  markdown:
+    - step1
+    - step2 [google.com](https://www.google.com/something)
+ecosystem:
+  languages:
+    - c
+    - c++
+  clients:
+    - github
+    - gitlab
+    - localdir
diff --git a/finding/testdata/metadata-variables.yml b/finding/testdata/metadata-variables.yml
@@ -1,4 +1,5 @@
 id: metadata-variables
+lifecycle: stable
 short: short description
 motivation: >
   line1

diff --git a/finding/testdata/missing-id.yml b/finding/testdata/missing-id.yml
@@ -1,3 +1,4 @@
+lifecycle: stable
 short: short description
 motivation: >
   line1

diff --git a/finding/testdata/missing-lifecycle.yml b/finding/testdata/missing-lifecycle.yml
@@ -0,0 +1,25 @@
+id: all-fields
+short: short description
+motivation: >
+  mot1
+  mot2
+implementation: >
+  impl1
+  impl2
+remediation:
+  onOutcome: False
+  effort: Low
+  text:
+    - step1
+    - step2 https://www.google.com/something
+  markdown:
+    - step1
+    - step2 [google.com](https://www.google.com/something)
+ecosystem:
+  languages:
+    - c
+    - c++
+  clients:
+    - github
+    - gitlab
+    - localdir
diff --git a/internal/probes/yaml/yaml.go b/internal/probes/yaml/yaml.go
@@ -31,6 +31,7 @@ type Probe struct {
 	ID             string      `yaml:"id"`
 	Short          string      `yaml:"short"`
 	Motivation     string      `yaml:"motivation"`
+	Lifecycle      string      `yaml:"lifecycle"`
 	Implementation string      `yaml:"implementation"`
 	Ecosystem      Ecosystem   `yaml:"ecosystem"`
 	Outcomes       []string    `yaml:"outcome"`

diff --git a/probes/README.md b/probes/README.md
@@ -16,6 +16,13 @@ A probe consists of three files:
 - `impl.go`: The actual implementation of the probe.
 - `impl_test.go`: The probe's test.
 
+## Lifecycle
+
+Probes can exist in several different lifecycle states:
+* `Experimental`: The semantics of the probe may change, and there are no stability guarantees.
+* `Stable`: The probe behavior and semantics will not change. There may be bug fixes as needed.
+* `Deprecated`: The probe is no longer supported and callers should not expect it to be maintained.
+
 ## Reusing code in probes
 
 When multiple probes use the same code, the reused code can be placed in a package under `probes/internal/`

diff --git a/probes/archived/def.yml b/probes/archived/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: archived
+lifecycle: stable
 short: Check that the project is archived
 motivation: >
   An archived project will not received security patches, and is not actively tested or used.

diff --git a/probes/blocksDeleteOnBranches/def.yml b/probes/blocksDeleteOnBranches/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: blocksDeleteOnBranches
+lifecycle: stable
 short: Check that the project blocks non-admins from deleting branches.
 motivation: >
   Allowing non-admins to delete project branches has a similar effect to performing force pushes.

diff --git a/probes/blocksForcePushOnBranches/def.yml b/probes/blocksForcePushOnBranches/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: blocksForcePushOnBranches
+lifecycle: stable
 short: Check that the project blocks force push on its branches.
 motivation: >
   Allowing force pushes to branches could allow those with write access to make insecure changes to the behavior of the project.

diff --git a/probes/branchProtectionAppliesToAdmins/def.yml b/probes/branchProtectionAppliesToAdmins/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: branchProtectionAppliesToAdmins
+lifecycle: stable
 short: Check that the project's branch protection rules apply to project admins.
 motivation: >
   Admins may be able to bypass branch protection settings which could defeat the purpose of having them.

diff --git a/probes/branchesAreProtected/def.yml b/probes/branchesAreProtected/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: branchesAreProtected
+lifecycle: stable
 short: Check that the project uses protected branches.
 motivation: >
   Unprotected branches may allow actions that could compromise the project's security. 

diff --git a/probes/codeApproved/def.yml b/probes/codeApproved/def.yml
@@ -14,6 +14,7 @@
 
 
 id: codeApproved
+lifecycle: stable
 short: Check that all recent changesets have been approved by someone who is not the author of the changeset.
 motivation: >
   To ensure that the review process works, the proposed changes

diff --git a/probes/codeReviewOneReviewers/def.yml b/probes/codeReviewOneReviewers/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: codeReviewOneReviewers
+lifecycle: experimental
 short: Check that at least one reviewers review a change before merging.
 motivation: >
   To ensure that the review process works, the proposed changes

diff --git a/probes/contributorsFromOrgOrCompany/def.yml b/probes/contributorsFromOrgOrCompany/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: contributorsFromOrgOrCompany
+lifecycle: experimental
 short: Checks whether a project has a contributions from users associated with a company or organization.
 motivation: >
   This probe tries to determine if the project has recent contributors from multiple organizations.

diff --git a/probes/createdRecently/def.yml b/probes/createdRecently/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: createdRecently
+lifecycle: stable
 short: Checks if the project was created in the last 90 days.
 motivation: >
   Recently created repositories have been used for malicious forks / typosquatting attacks in the past.

diff --git a/probes/dependencyUpdateToolConfigured/def.yml b/probes/dependencyUpdateToolConfigured/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: dependencyUpdateToolConfigured
+lifecycle: stable
 short: Check that a dependency update tool config is present.
 motivation: >
   Out-of-date dependencies make a project vulnerable to known flaws and prone to attacks.

diff --git a/probes/dismissesStaleReviews/def.yml b/probes/dismissesStaleReviews/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: dismissesStaleReviews
+lifecycle: stable
 short: Check that the project dismisses stale reviews when new commits are pushed.
 motivation: >
   When a project does not dismiss stale reviews, contributors can bring their pull requests to an approved state and then make unreviewed commits.

diff --git a/probes/fuzzed/def.yml b/probes/fuzzed/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: fuzzed
+lifecycle: stable
 short: Check that the project is fuzzed
 motivation: >
   Fuzzing, or fuzz testing, is the practice of feeding unexpected or random data into a program to expose bugs.

diff --git a/probes/hasBinaryArtifacts/def.yml b/probes/hasBinaryArtifacts/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: hasBinaryArtifacts
+lifecycle: stable
 short: Checks if the project has any binary files in its source tree.
 motivation: >
   Binary files are not human readable so users and reviewers can't easily see what they do.

diff --git a/probes/hasDangerousWorkflowScriptInjection/def.yml b/probes/hasDangerousWorkflowScriptInjection/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: hasDangerousWorkflowScriptInjection
+lifecycle: stable
 short: Check whether the project has GitHub Actions workflows that enable script injection.
 motivation: >
   Script injections allow attackers to use untrusted input to access privileged resources (code execution, secret exfiltration, etc.)

diff --git a/probes/hasDangerousWorkflowUntrustedCheckout/def.yml b/probes/hasDangerousWorkflowUntrustedCheckout/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: hasDangerousWorkflowUntrustedCheckout
+lifecycle: stable
 short: Check whether the project has GitHub Actions workflows that does untrusted checkouts.
 motivation: >
   GitHub workflows triggered with pull_request_target or workflow_run have write permission to the target repository and access to target repository secrets.

diff --git a/probes/hasFSFOrOSIApprovedLicense/def.yml b/probes/hasFSFOrOSIApprovedLicense/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: hasFSFOrOSIApprovedLicense
+lifecycle: stable
 short: Check that the project has an FSF or OSI approved license.
 motivation: >
   A license can give users information about how the source code may or may not be used.

diff --git a/probes/hasLicenseFile/def.yml b/probes/hasLicenseFile/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: hasLicenseFile
+lifecycle: stable
 short: Check that the project has a license file
 motivation: >
   A license can give users information about how the source code may or may not be used.

diff --git a/probes/hasNoGitHubWorkflowPermissionUnknown/def.yml b/probes/hasNoGitHubWorkflowPermissionUnknown/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: hasNoGitHubWorkflowPermissionUnknown
+lifecycle: experimental
 short: Checks that GitHub workflows have workflows with unknown permissions
 motivation: >
   Unknown permissions may be a result of a bug or another error from fetching the permission levels.

diff --git a/probes/hasOSVVulnerabilities/def.yml b/probes/hasOSVVulnerabilities/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: hasOSVVulnerabilities
+lifecycle: stable
 short: Check whether the project has known vulnerabilities
 motivation: >
   This check determines whether the project has open, unfixed vulnerabilities in its own codebase or its dependencies using the OSV (Open Source Vulnerabilities) service.

diff --git a/probes/hasOpenSSFBadge/def.yml b/probes/hasOpenSSFBadge/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: hasOpenSSFBadge
+lifecycle: stable
 short: This check determines whether the project has an OpenSSF (formerly CII) Best Practices Badge.
 motivation: >
   The OpenSSF Best Practices badge indicates whether or not the project uses a set of security-focused best development practices for open source software.

diff --git a/probes/hasPermissiveLicense/def.yml b/probes/hasPermissiveLicense/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: hasPermissiveLicense
+lifecycle: stable
 short: Check that the project has an permissive license.
 motivation: >
   A permissive license allows users to use the analyzed component to be used in derivative works. Non-permissive licenses (as copyleft licenses) might be a legal risk for potential users.

diff --git a/probes/hasRecentCommits/def.yml b/probes/hasRecentCommits/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: hasRecentCommits
+lifecycle: stable
 short: Check whether the project has at least one commit per week over the last 90 days.
 motivation: >
   A project which is not active might not be patched, have its dependencies patched, or be actively tested and used.

diff --git a/probes/hasReleaseSBOM/def.yml b/probes/hasReleaseSBOM/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: hasReleaseSBOM
+lifecycle: experimental
 short: Check that the project publishes an SBOM as part of its release artifacts.
 motivation: >
   An SBOM can give users information about how the source code components and dependencies. They help facilitate sotware supplychain security and aid in identifying upstream vulnerabilities in a codebase.

diff --git a/probes/hasSBOM/def.yml b/probes/hasSBOM/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: hasSBOM
+lifecycle: experimental
 short: Check that the project has an SBOM file
 motivation: >
   An SBOM can give users information about how the source code components and dependencies. They help facilitate sotware supplychain security and aid in identifying upstream vulnerabilities in a codebase.

diff --git a/probes/hasUnverifiedBinaryArtifacts/def.yml b/probes/hasUnverifiedBinaryArtifacts/def.yml
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 id: hasUnverifiedBinaryArtifacts
+lifecycle: stable
 short: Checks if the project has binary files in its source tree. The probe skips verified binary files which currently are gradle-wrappers.
 motivation: >
   Binary files are not human readable so users and reviewers can't easily see what they do.