scorecard-infra

OpenSSF Scorecard Infrastructure

The infrastructure that runs OpenSSF Scorecard as a service — and the work to make it run anywhere.

Scorecard results are heuristic signals, not a verdict. Nothing here asserts that a repository "is secure" or "is insecure"; every result declares its source, freshness, and completeness. A score of -1 means inconclusive, not failing.

Contents

• About The Project
• Getting Started
  • Prerequisites
  • Installation
• Usage
  • Batch scanning pipeline
  • Results API (api.scorecard.dev)
  • Results API server
  • Provider-agnostic migration
• Roadmap
• Contributing
• License
• Contact
• Acknowledgements

About The Project

ossf/scorecard is the engine: checks, probes, scoring, output formats. This repository is what surrounds it — the batch pipeline that scans 1M+ repositories every week, the API that serves what it produces, and the design for moving that stack off any single cloud provider.

These are one system's present and future, not three unrelated projects. The pipeline is a producer writing Scorecard results to a bucket; the API is the consumer reading them back out over HTTP. Both arrived here from elsewhere, so that the whole hosted data path lives in one place — which is the precondition for moving it.

flowchart LR
    ACT["Scorecard<br/>GitHub Action"]

    subgraph produce["Producer · cron/ — AWS (live 2026-09-06)"]
        direction TB
        CTL["batch controller"] --> WKR["scan workers"]
        WKR --> COR[("weekly results")]
        COR --> S3[("S3 buckets")]
    end

    subgraph serve["Serving tier · api/ — AWS"]
        direction TB
        BKT[("results bucket")]
        API["results API"]
        BKT --> API
        API -- "publish" --> BKT
    end

    COR -- "copied" --> BKT
    ACT -- "POST · Sigstore-verified" --> API
    API --> CDN{{"CDN<br/>api.scorecard.dev"}}
    CDN --> VW["scorecard.dev<br/>viewer"]
    CDN --> BDG["img.shields.io<br/>badge"]
    CDN --> MCP["scorecard-mcp,<br/>other API clients"]

Arrows follow results, not requests. One thing the picture is worth reading carefully for: the Action's POST path is the only one that refreshes the edge promptly, because the cache purge fires from the publish handler; batch-produced results reach clients as the cache expires.

They share a repository and, so far, no code. Converging them is the point of landing them together; it has not happened yet and should be done as its own change rather than incidentally (designs C11 and W10, in migrate-batch-pipeline and migrate-api).

Where the effort is going. Both trees are actively developed. The migration described in scorecard#5208 is complete, and api/ and cron/ are held to the same rules as the rest of the repository.

Getting Started

Prerequisites

Common to everything here:

• Go matching go.mod (1.25.x). If builds fail with a Go tool version mismatch across many stdlib packages, a stray GOROOT is the cause — prefix commands with env -u GOROOT.

Each component adds its own — an object store and SCM token, ko and protoc, a cluster and its cloud dependencies. They are listed in that component's README, linked from Usage below.

Installation

git clone https://github.com/ossf/scorecard-infra
cd scorecard-infra
make build     # go build ./...
make help      # every target, grouped

Building an individual component:

Usage

Batch scanning pipeline

cron/ is the batch scanning pipeline behind the weekly public Scorecard scan of 1M+ repositories. It was imported from ossf/scorecard with its full commit history — 466 commits dating to 2020 — because the operational history is the runbook: quota workarounds, shard sizing, SQS ack deadlines, and result formatting migrations exist only as commit messages. cron/initial-graft.md records the terms of that import, including what could not come across and where to trace it.

Production is AWS (live 2026-09-06). See:

• cron/README.md for the pipeline components, the scan inventories and how to add a repository to the weekly scan, and the build targets.
• deploy/cron/README.md for the AWS batch plane deployment: infrastructure, configuration, apply order, and verification.

Results API (api.scorecard.dev)

The service behind api.scorecard.dev and api.securityscorecards.dev, imported from ossf/scorecard-webapp with its full history. This is the API that ships. It is what every live consumer already talks to: the project website's result viewer, img.shields.io, the Scorecard GitHub Action's upload path, and scorecard-mcp.

The website that consumed it stays in ossf/scorecard-webapp, which remains its home; only the Go API moved.

Endpoints, unchanged by the migration:

Found a bug in the API? Open an issue in this repository. Bugs in the viewer at scorecard.dev belong in ossf/scorecard-webapp.

See api/README.md for the tree layout, build targets, image publication, and the two counterintuitive things about this tree — and deploy/api/README.md for the deployment itself.

Results API server

cmd/scorecard-api and internal/ hold a separate, provider-agnostic implementation of the results contract. It is not the deployment path, and nothing in production uses it — what ships is api/, above. It is documented in cmd/scorecard-api/README.md.

Provider-agnostic migration

Scorecard's hosted infrastructure is being migrated to a new home. The purpose of the work in docs/research/ is to make that migration provider-agnostic — portable across any cloud or self-hosted target rather than tied to a single provider — with the smallest reliable footprint.

• docs/research/data-infra.md — the reconciled reference design: object store, serving tier, interchange format, public dataset, and cost transparency. Written to be proposable to the Scorecard Infrastructure Working Group; it is not an official artifact yet, and nothing in it is committed.
• docs/research/infra-seed-0.md and infra-seed-1.md — the two research passes it reconciles (component-selection breadth; correctness/protocol critique and data model).

This is the arc that gives the two systems above a shared destination. Getting the pipeline out of ossf/scorecard is the precondition for it, not the work itself.

Roadmap

The infrastructure migration — what is moving, what has already moved, and what it means for consumers — is announced and tracked in ossf/scorecard#5208.

Backlog ownership across the Scorecard repositories, including which issues belong here, is in #77.

Per-change plans live in openspec/changes/; openspec list shows their live status.

Contributing

Contributions are welcome. For detailed contributing guidelines — including how to add a repository to the weekly scan, and the rules that apply to the cron/ tree — please see CONTRIBUTING.md.

make build     # go build ./...
make test      # go test ./... -race
make lint      # golangci-lint run ./...   (config in .golangci.yml, aligned with ossf/scorecard)
make help      # every target, grouped — including the pipeline targets

An S3-compatible integration test runs when SCORECARD_TEST_S3_URL is set (e.g. a local self-hosted S3-compatible store), and is skipped otherwise.

This repository is developed spec-first with OpenSpec; see AGENTS.md for conventions and openspec/ for the specs and change proposals.

Participation is governed by our Code of Conduct.

License

Distributed under the Apache-2.0 License. See LICENSE for more information.

Data served from Scorecard is licensed under CDLA Permissive 2.0.

Contact

• Maintainers — MAINTAINERS.md
• Questions and help — SUPPORT.md, or open an issue
• Security vulnerabilities — SECURITY.md. Please do not open a public issue; escalation goes to scorecard-steering@lists.openssf.org.

Project Link: https://github.com/ossf/scorecard-infra

Acknowledgements

• The batch scanning pipeline was imported from ossf/scorecard with its full commit history. git blame attributes to its original authors, not to the merge — see cron/initial-graft.md.
• The results API was imported from ossf/scorecard-webapp with its full history — see api/initial-graft.md.
• This README was adapted from https://github.com/bloomberg/oss-template.