OpenSSF Scorecard Guide: Checks, Scores and Using Results in Dependency Decisions

Teams add open source dependencies every day with almost no information about how those projects protect their code, their build pipelines and their release credentials. OpenSSF Scorecard is an automated tool from the Open Source Security Foundation that inspects a repository and scores a set of security practices, from branch protection to the permissions of CI workflow tokens. It is used by maintainers to harden their own projects and by consumers to inform dependency decisions. This guide explains the checks, how the scores are calculated, how to run Scorecard as a GitHub Action, CLI or API, and how to turn results into a dependency policy without over-trusting a single number. It is for application security engineers, platform teams, open source programme offices and anyone setting rules for third-party code.

Key takeaways

• Scorecard measures practices, not code quality. It checks whether a project follows supply chain hygiene such as code review, pinned dependencies and signed releases; it does not prove the code is free of vulnerabilities or malice.
• The aggregate score is risk weighted. Each check scores 0 to 10, and the overall score weights Critical checks at 10, High at 7.5, Medium at 5 and Low at 2.5.
• The two Critical checks are about pipeline identity. Dangerous-Workflow and Webhooks, together with the High-risk Token-Permissions check, look at how CI credentials and automation can be abused.
• Use individual checks for decisions. A policy such as "no Critical findings and Code-Review above 7" is more defensible than "overall score above 6".
• Running it yourself needs a token. The CLI and Action authenticate to GitHub with a token or GitHub App, which is itself a non-human credential to scope and protect.

What it is and who it applies to

Scorecard is an open source project under the OpenSSF. Its site says it was built to improve the health of critical projects the community depends on, and it targets risks from malicious maintainers, compromised build systems and source code, and malicious packages. According to the project repository, it scans more than 1.3 million repositories every week and publishes the results through a REST API.

• Maintainers: a pre-launch security check, a list of improvements to plan, and a badge to show progress.
• Organisations: run on internal and public repositories through CI so regressions are caught on each change.
• Consumers: look up the published results for a candidate dependency before adopting it, or monitor existing dependencies over time.
• Platforms: GitHub is fully supported, GitLab is supported with a GITLAB_AUTH_TOKEN (including self-hosted instances), and GitHub Enterprise Server is supported through the GH_HOST variable. The project documents macOS and Linux as supported operating systems.

Scorecard is not a regulation or certification. It is a measurement tool that supports obligations elsewhere, such as SSDF task PW.4.4 (verify third-party components keep meeting requirements). See the NIST Secure Software Development Framework (SSDF, SP 800-218) Guide and the Open Source Security Guide.

Structure and key requirements

The checks and their risk levels

The weekly public scan omits CI-Tests, Contributors and Dependency-Update-Tool because of API cost, so those checks only appear when you run Scorecard yourself.

How individual checks are scored

• Branch-Protection: tiered. Tier 1 (3/10) blocks force-push and deletion; tier 2 (6/10) requires at least one reviewer and, for admin-visible settings, pull requests, up-to-date branches and approval of the latest push; tier 3 (8/10) adds a required status check; tier 4 (9/10) requires two reviewers and code owner review; tier 5 (10/10) dismisses stale reviews and includes administrators. Without an admin token, admin-only settings are ignored.
• Code-Review: looks at roughly the last 30 commits for an approval or an implicit review (merger different from committer). Unreviewed human changes cost the most points; bot reviews do not count.
• Signed-Releases: 8 if each checked release has a signature file (such as .asc, .sig, .minisig or .sigstore), 10 if it also has SLSA provenance (.intoto.jsonl). Signatures are detected, not verified.
• Pinned-Dependencies: unpinned dependencies in Dockerfiles, shell scripts and GitHub workflows lower the score; hash pinning is recommended.
• Vulnerabilities: uses OSV; maintainers can ignore specific entries with a reason in an osv-scanner.toml file, which consumers should review.
• Maintained: best score needs at least one commit a week across the previous 90 days; projects younger than 90 days are not evaluated.

Probes and structured results

Since version 5, Scorecard exposes structured results built from probes: single detection rules such as hasDangerousWorkflowScriptInjection, hasDangerousWorkflowUntrustedCheckout, topLevelPermissions and jobLevelPermissions. Each probe returns OutcomeTrue, OutcomeFalse, OutcomeNotApplicable or OutcomeNotAvailable. Probes let a policy test one behaviour directly instead of inferring it from a 0 to 10 score.

Identity and NHI requirements

Three checks are really about how a project's machine identities can be abused, which is why they matter more to NHI teams than the overall score.

Both patterns have been exploited. In the Ultralytics PyPI compromise, a pull_request_target workflow inserted a branch name into a shell script, which let an attacker get code into releases. In the tj-actions/changed-files compromise (CVE-2025-30066), a stolen bot token was used to repoint release tags at a malicious commit, so every workflow using a tag rather than a SHA printed its secrets to build logs.

Running Scorecard creates its own NHI. The CLI needs a GitHub token (GITHUB_AUTH_TOKEN, GITHUB_TOKEN, GH_AUTH_TOKEN or GH_TOKEN) or a GitHub App installation; the site notes a PAT with the public_repo scope for public repositories. The Action can use the default GITHUB_TOKEN for repository rules, but reading classic branch protection needs a fine-grained PAT passed as repo_token. Store that PAT as a secret, scope it to read access, give it an expiry and an owner. See the GitHub and GitHub Actions Security Guide and the CI/CD Pipeline Identity Security Guide.

Implementation steps

1. Look up your dependencies first: query the public results for your top direct dependencies through the REST API at api.scorecard.dev (path /projects/github.com/{owner}/{repo}). The response gives the date, Scorecard version, overall score and each check's score, reason and details. The former BigQuery public dataset is no longer available.
2. Scan your own repositories with the Action: add ossf/scorecard-action on push to the default branch and on a weekly schedule, with workflow-level permissions: read-all and job-level security-events: write (to upload SARIF to code scanning) and id-token: write (only if publishing results).
3. Respect the publishing restrictions: with publish_results: true the job may not define env or defaults, use containers or services, or hold workflow-level write permissions, and its steps must come from an approved list (actions/checkout, actions/upload-artifact, github/codeql-action/upload-sarif, ossf/scorecard-action and step-security/harden-runner).
4. Triage in report-only mode: for the first month, review alerts in the Security tab without blocking anything. Fix Critical findings (Dangerous-Workflow, Webhooks) and Token-Permissions first: they are usually small YAML changes.
5. Write a dependency policy: define thresholds per check for new dependencies, for example no Dangerous-Workflow finding, Maintained above 0, Code-Review at least 7, and a documented exception route. Apply stricter rules to dependencies that run in build or release pipelines.
6. Enforce gradually: add the policy to the pull request review for dependency manifest changes, warning first, blocking later. If a block stalls delivery, move the rule back to warning through configuration and record the exception with an expiry.
7. Monitor over time: re-query dependency scores on a schedule and alert on drops in Critical or High checks, on a project becoming archived, or on Signed-Releases disappearing from a release.

Decision guidance

Evidence and assessment

• Evidence for auditors: retained SARIF or JSON output per scan, the dependency policy, the exceptions register and records of blocked dependency changes. These support SSDF PW.4 and supplier risk records.
• Reading a result honestly: a score of -1 or OutcomeNotAvailable means the data could not be retrieved, not that the practice is absent. A low Signed-Releases score on a project that ships only through a package registry may reflect where Scorecard looks rather than a real gap.
• What to log: score changes per dependency, new Critical findings in your own repositories, workflow file changes that add pull_request_target or write permissions, and expiry of the Scorecard PAT.

Metrics

• Critical findings: count of Dangerous-Workflow and Webhooks findings across owned repositories (target zero).
• Least privilege coverage: percentage of owned repositories scoring 10 on Token-Permissions.
• Pinning coverage: percentage of workflows with all actions pinned to SHAs.
• Dependency health: percentage of direct dependencies meeting the policy, and number with an open exception.
• Time to fix: median days from a Critical or High finding to resolution.

Mapping to other frameworks

The CII-Best-Practices check rewards the separate OpenSSF Best Practices badge, a self-certified questionnaire; the two complement each other. See the SLSA and Build Provenance Guide and the SBOM Guide.

Common pitfalls

• Using the aggregate as a pass mark: a project can score well overall and still have a Dangerous-Workflow finding that exposes its release secrets. Gate on specific checks.
• Treating a high score as proof of safety: Scorecard detects practices. A maintainer with legitimate access, as in the XZ Utils backdoor, can pass review-based checks.
• Ignoring the scanner's own token: a broad classic PAT used for bulk scans across an organisation becomes a high-value credential. Prefer a GitHub App or fine-grained read-only token with expiry.
• Penalising small but healthy projects: Contributors, Fuzzing and Packaging can be low for sound reasons. Weigh them against the dependency's role.
• Not rechecking: scores change when maintainers leave or workflows change. A one-off check at adoption misses later regressions.
• Accepting vulnerability ignores blindly: entries in osv-scanner.toml raise the Vulnerabilities score; read the stated reasons.

Practitioner checklist

• Add the Scorecard Action to owned repositories with read-all workflow permissions and SARIF upload.
• Fix every Dangerous-Workflow and Webhooks finding, then bring Token-Permissions to 10.
• Pin all third-party actions to full commit SHAs.
• Scope, vault and set an expiry on any PAT or GitHub App used to run Scorecard.
• Write a dependency policy based on individual checks and probes, with an exception register.
• Query public results for top direct dependencies and record the baseline.
• Schedule re-queries and alert on drops in Critical or High checks or archived projects.
• Retain scan outputs as evidence for SSDF PW.4 and supplier risk reviews.

Standards and references

• OpenSSF: Scorecard checks documentation
• OpenSSF: Scorecard repository and README
• OpenSSF: Scorecard GitHub Action
• OpenSSF: Scorecard probes documentation
• OpenSSF: Scorecard project site
• OpenSSF: Scorecard REST API
• GitHub Docs: Security hardening for GitHub Actions
• MITRE ATT&CK: Compromise Software Supply Chain

Related NHI Mgmt Group resources: Software Supply Chain Security Guide · Open Source Security Guide · Malicious Package and Dependency Confusion Guide · CI/CD Security Guide