This document describes the actors in a Scorecard scan, what each one does,
and the external interfaces of the software this repository releases. The
behavior of each component is specified in more detail under
openspec/specs/.
- User: runs Scorecard against a repository or package, through the CLI,
the container image, the Go API, or
scorecard serve. - Scorecard: the
scorecardbinary or thepkg/scorecardlibrary. It collects data about a repository, evaluates it, and reports the result. - Repository host: GitHub (including GitHub Enterprise), GitLab (including self-managed instances), or Azure DevOps. Scorecard reads repository contents and metadata through the host's API, authenticated with a token the user provides. Scorecard can also scan a local directory.
- Auxiliary services: OSV supplies known vulnerabilities, through OSV-Scanner. OSS-Fuzz reports fuzzing enrollment, and the OpenSSF Best Practices API reports badge level. The npm, PyPI, RubyGems, and NuGet registries map a package to its source repository.
- Policy author: writes an optional policy file that selects which checks run and sets a minimum score for each.
- Repository maintainer: can add a Scorecard configuration file to their repository to annotate check results.
- The user names a repository, a package, or a local directory, plus the checks or probes to run, either directly or through a policy file.
- For a package, Scorecard looks up its source repository in the package registry.
- Scorecard creates a read-only client for the repository host and the auxiliary clients it needs.
- Each check collects raw data from repository files and the host's API
(
checks/raw/). Scorecard parses files such as workflows, Dockerfiles, and dependency manifests; it doesn't build or run the scanned repository's code. - Probes turn the raw data into findings, each a yes-or-no answer with a
location and remediation (
probes/). - Each check scores its findings from 0 to 10, or -1 when inconclusive
(
checks/evaluation/). The aggregate score weights checks by risk. - Scorecard attaches any maintainer annotations from the scanned repository and writes the result in the requested format. A policy never changes scores; SARIF output reports only enforced checks that score below the policy's minimum.
ossf/scorecard-actionruns Scorecard in GitHub Actions and can publish results to the REST API.ossf/scorecard-infraruns the weekly batch scan of over a million repositories and the REST API that serves its results and the results published by the Action.ossf/scorecard-webappis the scorecard.dev website.
Inputs:
- CLI: the
scorecardcommand, its flags, and its environment variables (spec, usage). - Authentication:
GITHUB_AUTH_TOKEN(orGITHUB_TOKEN,GH_TOKEN,GH_AUTH_TOKEN), or a GitHub App throughGITHUB_APP_KEY_PATH,GITHUB_APP_ID, andGITHUB_APP_INSTALLATION_ID;GITLAB_AUTH_TOKEN;AZURE_DEVOPS_AUTH_TOKEN(spec). - Go API: the
pkg/scorecardpackage (spec, reference). - HTTP server:
scorecard serve, which listens onPORT(default 8080) (spec). - Policy file:
--policy(spec). - Maintainer annotations: a Scorecard configuration file in the scanned repository (spec).
- Package names:
--npm,--pypi,--rubygems,--nuget(spec).
Outputs:
- Result formats: text, JSON, SARIF, probe findings, raw data, and in-toto
(spec). The JSON schemas are
json.v2.schemaandjson.raw.schema. - Release artifacts: binaries and archives on
GitHub Releases with SLSA
provenance, and the
ghcr.io/ossf/scorecardcontainer image.
Outbound calls: the repository host APIs and auxiliary services listed under Actors.