Binary provenance is cryptographically verifiable metadata that records exactly how an artifact was produced: which source repository and commit, which build system, which build instructions, and when — signed by the builder so the claim can't be forged after the fact. It answers the question every incident responder eventually asks: "is this binary actually the output of that source code?" Without provenance, the honest answer is always "we assume so." With it, the answer is a signature check.
The reason this went from academic to urgent is SolarWinds. The SUNBURST implant was injected during the build — the source repository was clean, code review would have found nothing, and the signed installer was signed with a perfectly valid certificate. Provenance is the control aimed at precisely that gap: it binds the artifact to the build that made it, so a tampered build produces either missing or non-matching provenance.
What a provenance document actually contains
The de facto standard format is SLSA provenance (v1), an in-toto attestation with predicate type https://slsa.dev/provenance/v1. Stripped to essentials:
{
"_type": "https://in-toto.io/Statement/v1",
"subject": [
{ "name": "myapp", "digest": { "sha256": "7f83b1657ff1..." } }
],
"predicateType": "https://slsa.dev/provenance/v1",
"predicate": { "buildDefinition": "...", "runDetails": "..." }
}
The parts that matter operationally:
- subject.digest — the sha256 of the exact artifact being described. Provenance is bound to bytes, not to a filename or version string.
- buildDefinition.externalParameters — the source repo URI, the git ref/commit, the workflow file path. This is where "built from
github.com/yourco/api@abc1234" lives. - runDetails.builder.id — who did the building, e.g. GitHub's hosted runner identity or your Tekton Chains service account.
The whole statement is wrapped in a DSSE envelope and signed. With Sigstore keyless signing, the certificate embeds the builder's OIDC identity, so you don't manage long-lived signing keys at all.
Provenance vs signing vs SBOM
These three get conflated constantly, and the differences decide what attacks each one stops:
| Artifact | Question it answers | What it does NOT tell you |
|---|---|---|
| Code signature | "Was this signed by someone holding key X?" | Whether the build was tampered with before signing |
| SBOM | "What components are inside this artifact?" | Who built it, or from what source |
| Provenance | "What source and build process produced these exact bytes?" | Whether the source itself was malicious |
SolarWinds shipped signed malware. A signature proves custody of a key at signing time — nothing about what happened upstream of the signature. Provenance moves the trust boundary back to the build platform. An SBOM complements both by describing contents rather than origins; mature pipelines emit SBOM and provenance side by side from the same build, and the two together are what regulators increasingly mean when they say "software supply chain transparency."
Generating provenance in practice
If you build on GitHub Actions, artifact attestations made this nearly free:
permissions:
id-token: write
attestations: write
steps:
- uses: actions/attest-build-provenance@v2
with:
subject-path: dist/myapp
Verification is one command:
gh attestation verify dist/myapp --repo yourco/api
Elsewhere in the ecosystem: npm publish --provenance attaches SLSA provenance to npm packages (the green checkmark on npmjs.com); the slsa-framework/slsa-github-generator reusable workflows produce Build Level 3 provenance where the signing happens outside the job that could be compromised; Tekton Chains and GitLab's runner attestations cover the self-hosted world; and for containers, cosign attest --predicate provenance.json --type slsaprovenance pushes the attestation to the registry next to the image.
SLSA levels grade how trustworthy the provenance itself is. Level 1 is "provenance exists." Level 2 adds a hosted builder and signatures. Level 3 requires the build platform to protect the signing material from the build job itself — meaning a malicious build step can't forge its own paperwork. That distinction is the whole point; self-reported provenance from a compromised runner is worth exactly nothing.
Verification is the part everyone skips
Generating provenance and never verifying it is compliance theater with extra YAML. The control only exists at the moment of consumption:
- Admission control: a Kubernetes policy (Kyverno, Sigstore policy-controller, or OPA Gatekeeper with cosign) that rejects images lacking provenance from an approved
builder.idand repository. This is enforcement, everything else is reporting. - Ingest checks: verify
npmprovenance andgh attestation verifyresults when vendoring third-party artifacts. Consuming provenance from your upstreams is covered in more depth in our provenance attestation consumer workflow guide. - Release gates: CI refuses to promote an artifact to the prod registry unless its digest has matching, valid provenance.
Two verification details that bite people: check the repository and ref, not just signature validity (valid provenance from github.com/attacker/fork passes a naive check), and pin the expected builder.id (provenance signed by an unexpected builder identity should fail closed).
For teams under EO 14028 attestation requirements, EU CRA due diligence, or plain SOC 2 change-management scrutiny, provenance turns "trust our process" into evidence an auditor can independently verify. Platforms like Safeguard track which of your artifacts carry valid provenance and surface the gaps, which matters because coverage is always more ragged than anyone believes until it's measured.
Frequently asked questions
Is binary provenance the same as SLSA?
Not quite. Provenance is the artifact — the signed statement about how something was built. SLSA is the framework that defines the provenance format and grades build platforms (Levels 1–3) on how resistant the provenance is to forgery. You can emit provenance without meeting any SLSA level, but its trustworthiness is what the levels measure.
Does provenance prove the software is safe?
No. It proves the artifact came from a specific source commit via a specific build process. If that source contains a backdoor, the provenance faithfully attests to a backdoored build. Provenance eliminates build-time tampering as a blind spot; source review, dependency scanning, and reachability analysis handle the rest.
What's the minimum viable setup for a small team?
GitHub-hosted builds plus actions/attest-build-provenance plus a gh attestation verify step at deploy time — roughly an afternoon of work, no key management. Add registry-level enforcement (cosign policy in your cluster) once the happy path is stable.
Do I need provenance for internal-only artifacts?
Arguably more than for public ones. Internal artifacts skip external scrutiny entirely, and build-injection attacks specifically target that trust. Internal provenance plus admission control means a compromised CI runner produces artifacts your cluster refuses to run — which converts a supply chain breach into a deployment error.