OpenSSF Scorecard for coding agents

Before a coding agent changes code in a GitHub repository, you can use OpenSSF Scorecard to check the repository's security practices. Scorecard runs automated checks called heuristics: rules that look for signs of practices such as code review or pinned dependencies. It gives each check a score from 0 to 10.

An agent can use the results to point out repository risks before proposing changes. Scorecard does not inspect whether an agent read a secret, chose a misspelled package name, or changed a workflow safely. Its scores describe the checks it runs, so read the individual results rather than treating the overall score as a security verdict. The OpenSSF Scorecard project also cautions that its checks can produce false positives and false negatives.

Install and scan a public repository

The Scorecard README lists Homebrew for macOS and Linux among its install options. It names macOS and Linux as the supported platforms.

brew install scorecard

The README also documents a Docker image at ghcr.io/ossf/scorecard and prebuilt binaries on the releases page. Nix and Arch Linux packages are listed too.

Scorecard needs a GitHub token before it scans, as explained in the next section. With the token set, this command scans Scorecard's own public repository and requests JSON output:

scorecard --repo=github.com/ossf/scorecard --format=json --show-details

The CLI runs on your machine, but the scan contacts GitHub and retrieves public information about the repository. It does not edit the repository. The official command documentation describes --repo for selecting a repository and --format=json for machine-readable output. The --show-details flag adds the findings behind each score. To run only some checks, add --checks with a list of check names, for example --checks=Code-Review,Token-Permissions.

In the JSON, each check has a score and a reason that explains it. An agent can use the results to point out gaps, such as a low score on a check of a repository practice. It should preserve the check's explanation instead of reporting only an aggregate score. A check that could not collect reliable data is inconclusive. The text table shows it as ?, and the JSON gives it a score of -1. The output of a real scan depends on the repository, so the agent should report what the command returns.

Handle GitHub authentication

GitHub limits unauthenticated API requests, and the Scorecard setup documentation says you must authenticate before running Scorecard. The usual way is a classic GitHub personal access token in the GITHUB_AUTH_TOKEN environment variable. The README suggests the public_repo scope. If your environment already sets GITHUB_TOKEN or GH_TOKEN, Scorecard reads those as well. A GitHub App installation is the documented option for higher rate limits.

export GITHUB_AUTH_TOKEN="<your-github-token>"

The placeholder is not a real token. Store the token in the shell or the execution environment that launches the command. Do not paste it into an agent prompt or print it in a command transcript.

The agent does not need to change files to scan a public repository. Scorecard only reads from GitHub, but the token can allow more. GitHub's public_repo scope includes write access to public repositories that the token owner can push to. Keep the token out of any report the agent produces.

Use results to review agent work

Ask an agent to scan a repository before it proposes a change to CI, the automation that builds, tests, or deploys code. The agent can identify relevant Scorecard checks, quote their reasons, and ask for review where the results point to a gap. The repository's existing practices provide context for a proposed change, but they do not prove that the change is safe.

For example, an agent can run the public-repository command above and summarize checks relevant to workflow security or dependency maintenance. It should label the report as a Scorecard assessment and avoid claiming that the score predicts whether the agent introduced a vulnerability. The checks documentation explains what each check looks for and how to fix a low score.

A prompt for that task could be:

Run OpenSSF Scorecard against github.com/ossf/scorecard with JSON output. Summarize the individual check names, scores, and explanations that relate to CI security or dependency maintenance. Do not change files, and do not treat the aggregate score as a security verdict.

Know what Scorecard cannot assess

Scorecard checks repository security practices, but it does not assess how a coding agent behaves. Rules for agents, like which files they may read or when they must ask before changing CI, belong in your own repository policy and in code review.

The README also says the aggregate score tells you nothing about the individual behaviors of a repository, and that scores change as the project adds or refines checks. Use Scorecard as one part of your review. When a check matters to the proposed change, inspect that check's result and explanation, then review the actual files the agent touched.