README
¶
Maintainer Annotations
Maintainer Annotations let maintainers add context to display alongside Scorecard check results. Annotations can provide users additional information when Scorecard has an incomplete assessment of a project's security practices.
Annotating Your Project
To annotate your repository, create a scorecard.yml file in the root of your repository.
You can also place your annotations in
.scorecard.ymlor.github/scorecard.yml.
The file structure is as follows:
annotations:
- checks:
- binary-artifacts
reasons:
- reason: test-data # the binary files are only used for testing
- checks:
- dangerous-workflow
reasons:
- reason: remediated # the workflow is dangerous but only run under maintainers verification and approval
You can annotate multiple checks at a time:
annotations:
- checks:
- binary-artifacts
- pinned-dependencies
reasons:
- reason: test-data # the binary files and files with unpinned dependencies are only used for testing
And also provide multiple annotations for checks:
annotations:
- checks:
- binary-artifacts
reasons:
- reason: test-data # test.exe is only used for testing
- reason: remediated # dependency.exe is needed and it's used but the binary signature is verified
The available checks are the Scorecard checks in lower case e.g. Binary-Artifacts is binary-artifacts.
Types of Annotations
The annotations are predefined as shown in the table below:
| Annotation | Description | Example |
|---|---|---|
| test-data | A check or probe has found a security issue 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 has found a security issue to which 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. |
Viewing Maintainer Annotations
To see the maintainers annotations for each check on Scorecard results, use the --show-annotations option.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Annotation ¶
type Annotation struct {
Checks []string `yaml:"checks"`
Reasons []ReasonGroup `yaml:"reasons"`
}
Annotation defines a group of checks that are being annotated for various reasons.
type Config ¶
type Config struct {
Annotations []Annotation `yaml:"annotations"`
}
Config contains configurations defined by maintainers.
type Reason ¶
type Reason string
Reason is the reason behind an annotation.
const ( // TestData is to annotate when a check or probe is targeting a danger // in files or code snippets only used for test or example purposes. TestData Reason = "test-data" // Remediated is to annotate when a check or probe correctly identified a // danger and, even though the danger is necessary, a remediation was already applied. // E.g. a workflow is dangerous but only run under maintainers verification and approval, // or a binary is needed but it is signed or has provenance. Remediated Reason = "remediated" // NotApplicable is to annotate when a check or probe is not applicable for the case. // E.g. the dependencies should not be pinned because the project is a library. NotApplicable Reason = "not-applicable" // NotSupported is to annotate when the maintainer fulfills a check or probe in a way // that is not supported by Scorecard. E.g. Clang-Tidy is used as SAST tool but not identified // because its not supported. NotSupported Reason = "not-supported" // NotDetected is to annotate when the maintainer fulfills a check or probe in a way // that is supported by Scorecard but not identified. E.g. Dependabot is configured in the // repository settings and not in a file. NotDetected Reason = "not-detected" )
type ReasonGroup ¶
type ReasonGroup struct {
Reason Reason `yaml:"reason"`
}
ReasonGroup groups the annotation reason and, in the future, the related probe. If there is a probe, the reason applies to the probe. If there is not a probe, the reason applies to the check or checks in the group.
Source Files