OpenSSF Scorecard Guide: Checks, Scores and Policy

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

Check	Risk	What it looks for
Dangerous-Workflow	Critical	Risky GitHub Actions patterns: untrusted code checkouts in privileged triggers and script injection from untrusted context
Webhooks	Critical	Whether webhooks have a token configured to authenticate request origins (experimental)
Binary-Artifacts	High	Generated executables committed to the repository
Branch-Protection	High	Rules on default and release branches: reviews, status checks, no force-push
Code-Review	High	Whether recent changes were reviewed by a human before merge
Dependency-Update-Tool	High	Dependabot or Renovate enabled
Maintained	High	Commit and issue activity in the last 90 days; archived projects score lowest
Signed-Releases	High	Signature or provenance files on release assets
Token-Permissions	High	Whether workflow token permissions follow least privilege
Vulnerabilities	High	Open, unfixed vulnerabilities in the OSV database
Fuzzing	Medium	OSS-Fuzz, ClusterFuzzLite or language fuzzing tools
Packaging	Medium	Whether the project publishes packages
Pinned-Dependencies	Medium	Build and release dependencies pinned to hashes or exact versions
SAST	Medium	Static analysis tools such as CodeQL or SonarCloud
SBOM	Medium	An SBOM in the source or release artefacts
Security-Policy	Medium	A SECURITY.md with reporting contacts and disclosure guidance
CI-Tests	Low	Tests run in CI before pull requests merge
CII-Best-Practices	Low	An OpenSSF Best Practices badge (passing, silver or gold)
Contributors	Low	Recent contributors from multiple organisations
License	Low	A published licence file

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.

Check	NHI exposure it detects	What good looks like
Token-Permissions	The GITHUB_TOKEN issued to every workflow run has write scopes it does not need, so any compromised step can push code, publish packages or alter releases	Top-level `permissions` read-only (for example `contents: read`), write scopes declared only on the job that needs them. Scorecard warns on sensitive writes such as contents, packages and actions
Dangerous-Workflow	`pull_request_target` or `workflow_run` triggers that check out pull request code run attacker code with repository secrets; untrusted values such as issue or PR titles in inline scripts allow script injection	No privileged checkout of untrusted code; untrusted input passed through an intermediate environment variable, as GitHub's hardening guidance recommends
Webhooks	Webhook endpoints that accept unauthenticated requests can be triggered by anyone	A secret token configured on every webhook
Pinned-Dependencies	A third-party action referenced by a movable tag runs with the workflow's secrets	Actions pinned to full commit SHAs
Branch-Protection, Code-Review	A stolen maintainer or bot token can merge directly	Required reviews and status checks that tokens cannot bypass

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

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.
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).
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).
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.
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.
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.
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

Situation	Use	Trade-off
Vetting a new dependency	Public API results, specific checks plus manual review of SECURITY.md and release process	Public data may lag the latest commit and omits three checks
Hardening repositories you own	GitHub Action with SARIF upload	Needs an admin-capable token for full Branch-Protection results
Bulk assessment of many repositories	CLI or Docker image (`ghcr.io/ossf/scorecard`) with a GitHub App or several tokens in rotation	Rate limits; the tokens are NHIs to govern
Small team	Action on key repositories plus a short dependency rule list	Less automation, more judgement
Large organisation	Probe-level results fed into an ASPM or dependency policy engine	Needs tuning and an exception workflow

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

Scorecard area	Framework reference
Dependency vetting with Scorecard results	NIST SSDF PW.4.1 and PW.4.4; NIST SP 800-53 SR-3 Supply Chain Controls and Processes, SR-6 Supplier Assessments and Reviews; CSF 2.0 GV.SC-07
Signed-Releases, SBOM	SSDF PS.2 and PS.3; SP 800-53 CM-14 Signed Components, SR-4 Provenance; SLSA provenance
Token-Permissions, Dangerous-Workflow	SP 800-53 AC-6 Least Privilege; SSDF PO.5 and PS.1; ATT&CK T1528 Steal Application Access Token
Vulnerabilities, Dependency-Update-Tool	SP 800-53 RA-5 Vulnerability Monitoring and Scanning; CSF 2.0 ID.RA-01
SAST, Fuzzing, Code-Review	SP 800-53 SA-15 Development Process, Standards, and Tools; SSDF PW.7 and PW.8
Threats addressed overall	ATT&CK T1195.001 Compromise Software Dependencies and Development Tools, T1195.002 Compromise Software Supply Chain

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.

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