OpenSSF Scorecard can turn a repository into a list of security signals, but the badge or aggregate score is not the decision. A project may lose points because it has a workflow pattern that matters greatly to your threat model, or because a check cannot observe a control that exists elsewhere. The useful review starts with a pinned repository revision, keeps the individual findings, and asks what each result means for the way your team will consume the software. This guide produces a small evidence bundle that another engineer can rerun instead of a screenshot of a number.
The dependency comes before the score
Write one sentence describing how the project would enter your system. A build-time development tool, a container deployed with credentials, a library linked into a public service, and a copied code sample create different exposure. Record whether you will execute upstream releases, build from source, allow network access, or permit the tool to write files. The same Scorecard finding changes significance across those cases.
Pin the repository URL and the commit or release under review. Do not write “latest” in the record. Save the date, evaluator, operating system, Scorecard version, and command. That header prevents a later rerun from being compared with an unidentified moving target.
A local run and its structured output
Follow the official repository instructions for the current release. Prefer the documented binary, package, or container path over an unofficial wrapper. Authenticate only when required to avoid rate limits, and give the token the smallest documented access. Never paste a production secret into a command that will remain in shell history.
Run the repository check against the pinned target and request a machine-readable format such as JSON. Save standard output, standard error, the process exit code, and the tool version. A compact evidence directory can contain:
| Artifact | Purpose | Review rule |
|---|---|---|
| target.txt | Repository and pinned revision | Must not say only “main” |
| command.txt | Exact invocation with secrets removed | Must be rerunnable |
| scorecard.json | Individual checks and evidence | Keep even when the score is high |
| notes.md | Human interpretation and owners | Separate fact from decision |
The aggregate score is a navigation aid. Sort the checks by risk to your adoption path, not merely by points lost.
What does a failed check actually mean?
A branch-protection result asks how unreviewed changes could reach the code you consume. A dependency-update result asks how known problems are discovered and handled. A token-permissions result asks what a compromised workflow could access. A signed-release or provenance result asks whether you can establish where an artifact came from. Investigate the linked evidence and the repository configuration before labelling a project safe or unsafe.
Scorecard observes public evidence and automated patterns. It does not prove that maintainers are trustworthy, that a release is free of malicious code, or that the software fits your environment. Conversely, a failed check can reflect an observation limit or a deliberate project choice. Record the finding, the upstream evidence, your exposure, and the resulting control as four separate fields.
From finding to adoption control
For every material finding, choose one action: accept with a written reason, mitigate locally, ask upstream, or stop the evaluation. Examples of local mitigation include pinning a full commit digest, building in an isolated environment, verifying provenance when available, removing unnecessary network access, scanning the produced artifact, or vendoring a small reviewed component. A mitigation that no one owns is not a control.
Set a refresh trigger. Rerun when the pinned version changes, a critical workflow changes, a repository changes ownership, or your integration gains new privileges. Avoid an automatic daily score alert unless someone can act on it; high-frequency noise trains teams to ignore the result.
One manual trace calibrates the scanner
Select the most consequential failed or uncertain check and follow its evidence into the repository. For a workflow-related finding, identify the exact file, trigger, permissions block, and third-party action reference. For a release-related finding, trace one downloadable artifact back to its source revision and documented build path. Save the relevant URLs and a short note describing what the scanner observed and what the manual trace added. This spot check calibrates how much confidence to place in the other results and can reveal stale, incomplete, or context-free evidence without pretending that a single manual review replaces the scanner.
A decision record that survives handoff
End with a one-page record: intended use, pinned revision, three most relevant findings, evidence links, compensating controls, unresolved questions, decision owner, and review date. Include the raw JSON beside it. If the decision is “adopt,” state the conditions that would reverse it. If it is “wait,” name the evidence that would unblock it.
That record is more valuable than a green badge because it connects an automated observation to your actual deployment. Scorecard supplies useful evidence. Your team still owns the threat model, the interpretation, and the decision.