mirror of
https://github.com/ossf/scorecard.git
synced 2024-09-19 21:18:09 +03:00
ed272eab2c
* update docs Signed-off-by: Raghav Kaul <raghavkaul+github@google.com> * reword Signed-off-by: Raghav Kaul <raghavkaul+github@google.com> * update Signed-off-by: Raghav Kaul <raghavkaul+github@google.com> --------- Signed-off-by: Raghav Kaul <raghavkaul+github@google.com>
66 lines
2.8 KiB
Markdown
66 lines
2.8 KiB
Markdown
# Maintainer Annotations
|
|
|
|
**Maintainer Annotations** are an experimental feature that let maintainers add context to Scorecard check results. Annotations can inform users when Scorecard is incorrectly assessing 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.yml` or `.github/scorecard.yml`.
|
|
|
|
The file structure is as follows:
|
|
|
|
```yml
|
|
exemptions:
|
|
- checks:
|
|
- binary-artifacts
|
|
annotations:
|
|
- annotation: test-data # the binary files are only used for testing
|
|
- checks:
|
|
- dangerous-workflow
|
|
annotations:
|
|
- annotation: remediated # the workflow is dangerous but only run under maintainers verification and approval
|
|
-
|
|
```
|
|
|
|
You can annotate multiple checks at a time:
|
|
|
|
```yml
|
|
exemptions:
|
|
- checks:
|
|
- binary-artifacts
|
|
- pinned-dependencies
|
|
annotations:
|
|
- annotation: test-data # the binary files and files with unpinned dependencies are only used for testing
|
|
|
|
```
|
|
|
|
And also provide multiple annotations for checks:
|
|
|
|
```yml
|
|
exemptions:
|
|
- checks:
|
|
- binary-artifacts
|
|
annotations:
|
|
- annotation: test-data # test.exe is only used for testing
|
|
- annotation: 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.
|