⚠️ Add initial Maintainers Annotation parsing

README.md

@@ -423,6 +423,13 @@ RESULTS
 |---------|------------------------|--------------------------------|--------------------------------|---------------------------------------------------------------------------|
 ```
 
+##### Showing Maintainers Annotations (Experimental)
+
+To see the maintainers annotations for each check, use the `--show-annotations` option.
+
+For more information on how to configure annotations or what are the available annotations, see [the configuration doc](config/README.md).
+
+
 ##### Using a GitLab Repository
 
 To run Scorecard on a GitLab repository, you must create a [GitLab Access Token](https://gitlab.com/-/profile/personal_access_tokens) with the following permissions:

checker/check_result.go

@@ -19,7 +19,9 @@ import (
 	"errors"
 	"fmt"
 	"math"
+	"strings"
 
+	"github.com/ossf/scorecard/v5/config"
 	sce "github.com/ossf/scorecard/v5/errors"
 	"github.com/ossf/scorecard/v5/finding"
 )
@@ -254,3 +256,32 @@ func LogFinding(dl DetailLogger, f *finding.Finding, level DetailType) {
 		dl.Warn(&lm)
 	}
 }
+
+// IsExempted verifies if a given check in the results is exempted in annotations.
+func (check *CheckResult) IsExempted(c config.Config) (bool, []string) {
+	// If check has a maximum score, then there it doesn't make sense anymore to reason the check
+	// This may happen if the check score was once low but then the problem was fixed on Scorecard side
+	// or on the maintainers side
+	if check.Score == MaxResultScore {
+		return false, nil
+	}
+
+	// Collect all annotation reasons for this check
+	var reasons []string
+
+	// For all annotations
+	for _, annotation := range c.Annotations {
+		for _, checkName := range annotation.Checks {
+			// If check is in this annotation
+			if strings.EqualFold(checkName, check.Name) {
+				// Get all the reasons for this annotation
+				for _, reasonGroup := range annotation.Reasons {
+					reasons = append(reasons, reasonGroup.Reason.Doc())
+				}
+			}
+		}
+	}
+
+	// A check is considered exempted if it has annotation reasons
+	return (len(reasons) > 0), reasons
+}

checker/check_result_test.go

@@ -21,6 +21,7 @@ import (
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/go-cmp/cmp/cmpopts"
 
+	"github.com/ossf/scorecard/v5/config"
 	sce "github.com/ossf/scorecard/v5/errors"
 )
 
@@ -809,3 +810,195 @@ func TestCreateRuntimeErrorResult(t *testing.T) {
 		})
 	}
 }
+
+func TestIsExempted(t *testing.T) {
+	t.Parallel()
+	type args struct {
+		check  CheckResult
+		config config.Config
+	}
+	type want struct {
+		reasons    []config.Reason
+		isExempted bool
+	}
+	tests := []struct {
+		name string
+		args args
+		want want
+	}{
+		{
+			name: "Binary-Artifacts exempted for testing",
+			args: args{
+				check: CheckResult{
+					Name:  "Binary-Artifacts",
+					Score: 0,
+				},
+				config: config.Config{
+					Annotations: []config.Annotation{
+						{
+							Checks: []string{"binary-artifacts"},
+							Reasons: []config.ReasonGroup{
+								{Reason: "test-data"},
+							},
+						},
+					},
+				},
+			},
+			want: want{
+				isExempted: true,
+				reasons: []config.Reason{
+					config.TestData,
+				},
+			},
+		},
+		{
+			name: "Binary-Artifacts not exempted",
+			args: args{
+				check: CheckResult{
+					Name:  "Binary-Artifacts",
+					Score: 0,
+				},
+				config: config.Config{
+					Annotations: []config.Annotation{
+						{
+							Checks: []string{"pinned-dependencies"},
+							Reasons: []config.ReasonGroup{
+								{Reason: "test-data"},
+							},
+						},
+						{
+							Checks: []string{"branch-protection"},
+							Reasons: []config.ReasonGroup{
+								{Reason: "not-applicable"},
+							},
+						},
+					},
+				},
+			},
+			want: want{
+				isExempted: false,
+			},
+		},
+		{
+			name: "No checks exempted",
+			args: args{
+				check: CheckResult{
+					Name:  "Binary-Artifacts",
+					Score: 0,
+				},
+				config: config.Config{},
+			},
+			want: want{
+				isExempted: false,
+			},
+		},
+		{
+			name: "Exemption is outdated",
+			args: args{
+				check: CheckResult{
+					Name:  "Binary-Artifacts",
+					Score: 10,
+				},
+				config: config.Config{
+					Annotations: []config.Annotation{
+						{
+							Checks: []string{"binary-artifacts"},
+							Reasons: []config.ReasonGroup{
+								{Reason: "test-data"},
+							},
+						},
+					},
+				},
+			},
+			want: want{
+				isExempted: false,
+			},
+		},
+		{
+			name: "Multiple exemption reasons in a single annotation",
+			args: args{
+				check: CheckResult{
+					Name:  "Binary-Artifacts",
+					Score: 0,
+				},
+				config: config.Config{
+					Annotations: []config.Annotation{
+						{
+							Checks: []string{"binary-artifacts"},
+							Reasons: []config.ReasonGroup{
+								{Reason: "test-data"},
+								{Reason: "remediated"},
+							},
+						},
+					},
+				},
+			},
+			want: want{
+				isExempted: true,
+				reasons: []config.Reason{
+					config.TestData,
+					config.Remediated,
+				},
+			},
+		},
+		{
+			name: "Multiple exemption reasons across annotations",
+			args: args{
+				check: CheckResult{
+					Name:  "Binary-Artifacts",
+					Score: 0,
+				},
+				config: config.Config{
+					Annotations: []config.Annotation{
+						{
+							Checks: []string{
+								"binary-artifacts",
+								"pinned-dependencies",
+							},
+							Reasons: []config.ReasonGroup{
+								{Reason: "test-data"},
+							},
+						},
+						{
+							Checks: []string{
+								"binary-artifacts",
+								"dangerous-workflow",
+							},
+							Reasons: []config.ReasonGroup{
+								{Reason: "remediated"},
+							},
+						},
+					},
+				},
+			},
+			want: want{
+				isExempted: true,
+				reasons: []config.Reason{
+					config.TestData,
+					config.Remediated,
+				},
+			},
+		},
+	}
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			isExempted, reasons := tt.args.check.IsExempted(tt.args.config)
+			if isExempted != tt.want.isExempted {
+				t.Fatalf("IsExempted() = %v, want %v", isExempted, tt.want.isExempted)
+			}
+			wantReasons := []string{}
+			if tt.want.reasons != nil {
+				for _, r := range tt.want.reasons {
+					wantReasons = append(wantReasons, r.Doc())
+				}
+			} else {
+				wantReasons = nil
+			}
+			if cmp.Equal(reasons, wantReasons) == false {
+				t.Fatalf("Reasons for IsExempted() = %v, want %v", reasons, wantReasons)
+			}
+		})
+	}
+}

cmd/internal/scdiff/app/format/format.go

@@ -56,5 +56,9 @@ func JSON(r *pkg.ScorecardResult, w io.Writer) error {
 		return err
 	}
 	Normalize(r)
-	return r.AsJSON2(details, logLevel, docs, w)
+	o := pkg.AsJSON2ResultOption{
+		Details:  details,
+		LogLevel: logLevel,
+	}
+	return r.AsJSON2(w, docs, o)
 }

cmd/root.go

@@ -39,7 +39,7 @@ import (
 const (
 	scorecardLong = "A program that shows the OpenSSF scorecard for an open source software."
 	scorecardUse  = `./scorecard (--repo=<repo> | --local=<folder> | --{npm,pypi,rubygems,nuget}=<package_name>)
-	 [--checks=check1,...] [--show-details]`
+	 [--checks=check1,...] [--show-details] [--show-annotations]`
 	scorecardShort = "OpenSSF Scorecard"
 )
 

config/README.md

@@ -0,0 +1,63 @@
+# Maintainers Annotations
+
+Maintainers Annotations is an experimental feature to let maintainers add annotations to Scorecard checks.
+
+## Showing Maintainers Annotations
+
+To see the maintainers annotations for each check on Scorecard results, use the `--show-annotations` option.
+
+## Adding Annotations
+
+To add annotations to your repository, create a `scorecard.yml` file in the root of your repository.
+
+The file structure is as follows:
+```yml
+exemptions:
+  - checks:
+      - binary-artifacts
+    annotations:
+      # the binary files are only used for testing
+      - annotation: test-data
+  - checks:
+      - dangerous-workflow
+    annotations:
+      # the workflow is dangerous but only run under maintainers verification and approval
+      - annotation: remediated
+```
+
+You can annotate multiple checks at a time:
+```yml
+exemptions:
+  - checks:
+      - binary-artifacts
+      - pinned-dependencies
+    annotations:
+      # the binary files and files with unpinned dependencies are only used for testing
+      - annotation: test-data
+```
+
+And also provide multiple annotations for checks:
+```yml
+exemptions:
+  - checks:
+      - binary-artifacts
+    annotations:
+      # test.exe is only used for testing
+      - annotation: test-data
+      # dependency.exe is needed and it's used but the binary signature is verified
+      - annotation: remediated
+```
+
+The available checks are the Scorecard checks in lower case e.g. Binary-Artifacts is `binary-artifacts`.
+
+The annotations are predefined as shown in the table below:
+
+| Annotation | Description | Example |
+|------------|-------------|---------|
+| test-data | To annotate when a check or probe is targeting a danger in files or code snippets only used for test or example purposes. | The binary files are only used for testing. |
+| remediated | To annotate when a check or probe correctly identified a danger and, even though the danger is necessary, a remediation was already applied. | A workflow is dangerous but only run under maintainers verification and approval, or a binary is needed but it is signed or has provenance. |
+| not-applicable | To annotate when a check or probe is not applicable for the case. | The dependencies should not be pinned because the project is a library. |
+| not-supported | To annotate when the maintainer fulfills a check or probe in a way that is not supported by Scorecard. | Clang-Tidy is used as SAST tool but not identified because its not supported. |
+| not-detected | To annotate when the maintainer fulfills a check or probe in a way that is supported by Scorecard but not identified. | Dependabot is configured in the repository settings and not in a file. |
+
+These annotations, when displayed in Scorecard results are parsed to a human-readable format that is similar to the annotation description described in the table above.