ossf/scorecard-action

Run OpenSSF Scorecard supply-chain checks on your repo and surface results in code scanning.

Official actionCategory: Security & Supply ChainLatest v2View on GitHub

What it does

ossf/scorecard-action runs the OpenSSF Scorecard checks, things like Branch-Protection, Pinned-Dependencies, Token-Permissions, and Dangerous-Workflow, against your own repository.

Results are written as SARIF (or JSON) and typically uploaded to GitHub code scanning; with publish_results: true, public repos can also publish scores to the public Scorecard API and earn the badge.

Usage

workflow (.yml)

on:
  branch_protection_rule:
  schedule:
    - cron: '30 1 * * 6'
  push:
    branches: [main]
permissions: read-all
jobs:
  analysis:
    runs-on: ubuntu-latest
    permissions:
      security-events: write   # upload SARIF
      id-token: write          # publish results
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - uses: ossf/scorecard-action@v2.4.3
        with:
          results_file: results.sarif
          results_format: sarif
          publish_results: true
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Inputs

Input	Description	Default	Required
`results_file`	Path to file to store results.	-	Yes
`results_format`	Format of the results: json or sarif.	-	Yes
`repo_token`	GitHub token with read access.	`${{ github.token }}`	No
`publish_results`	Publish results to the public Scorecard API.	`false`	No
`file_mode`	Method to fetch files from GitHub.	`archive`	No

Notes

publish_results: true requires id-token: write (the publish step authenticates via OIDC) and is intended for public repositories on the default branch.

Check out with persist-credentials: false; the Token-Permissions philosophy the tool scores you on applies to its own workflow too.

Common errors

A failure when publishing results usually means id-token: write is missing from the job permissions, or the workflow is running on a branch other than the default branch.
Low Pinned-Dependencies or Token-Permissions scores are findings about your repo, not action misconfiguration, the fix is SHA-pinning your actions and adding least-privilege permissions: blocks.

Security and pinning

Keep workflow-level permissions: read-all and grant security-events: write / id-token: write only on the analysis job.
Pin scorecard-action (and every other action in the workflow) to a full commit SHA, Scorecard's own Pinned-Dependencies check will flag you otherwise.

Alternatives and related

step-security/harden-runnerMonitor and restrict a runner's network egress to detect and block CI supply-chain attacks. actions/dependency-review-actionBlock pull requests that introduce dependencies with known vulnerabilities or bad licenses. github/codeql-actionRun GitHub CodeQL static analysis to find security vulnerabilities in your code.

Frequently asked questions

How do I get the OpenSSF Scorecard badge on my README?

Run the action on the default branch of a public repo with publish_results: true and id-token: write, then embed the badge URL from api.scorecard.dev for your repo.