When you download a binary, a container image, or an npm package, you are trusting that it was built from the source code you think it was. Build provenance is the signed, verifiable record that lets you check that trust instead of assuming it. This post explains what provenance is, why it matters for supply chain security, and how the SLSA framework grades how hard a build is to fake.
What build provenance actually is
Build provenance is metadata that describes where an artifact came from and how it was made. It answers plain questions: which source commit produced this file, which build system ran, which steps executed, and what inputs went in. The record is signed by the builder, so a consumer can verify it was not edited after the fact.
Think of it as a receipt attached to the artifact. A published package on its own says nothing about its own history. You see a name, a version, and a hash. None of that tells you the file was really built from the tagged commit in the real repository. Provenance fills that gap with a statement the builder signs, so the claim can be checked by anyone who holds the artifact.
A provenance statement usually carries these fields:
- The subject: the artifact name and a cryptographic digest, so the statement is bound to one exact file.
- The source: the repository URL and the commit that was checked out.
- The builder: which build system produced the artifact, named by identity, not by a label anyone can type.
- The build steps: the entry point, parameters, and inputs the build consumed.
Why build provenance matters for supply chain security
Without provenance, you trust a published artifact on faith. You pull it because it has the right name and version, and you assume the pipeline that made it did the honest thing. That assumption is exactly where supply chain attacks live.
Two things can go wrong that a name and a hash will never reveal. First, a build step can be compromised, so the source is clean but the output is not. A malicious dependency runs during the build, or an attacker with access to the build system injects code into the artifact. The commit looks fine; the binary does not match it. Second, the artifact can be swapped after the build, replaced in a registry or a mirror with a tampered copy that keeps the same version string.
Provenance catches both. If the signed statement says the artifact was built from commit a1b2c3d by the expected builder, and the file you hold has a different digest or points at a fork you have never heard of, the check fails before you deploy. This is the same class of risk covered in our writeups on malicious npm lifecycle scripts and npm lockfile injection, where the danger is code that runs during install or build rather than in the app itself.
A hash proves two files are identical. Provenance proves one file came from the source and the builder you expected. You need both to trust what you deploy.
SLSA: grading how hard a build is to fake
SLSA (Supply chain Levels for Software Artifacts) is a framework that describes build integrity in levels. Each level adds a stronger guarantee about how the artifact was produced and how trustworthy its provenance is. You do not have to hit the top level to benefit; the point is to know where you stand and to climb.
In plain terms the levels read like this:
- Level 0: no guarantees. There is no provenance at all. You trust the artifact because it showed up.
- Level 1: the build produces provenance describing how it was made. It is not yet resistant to tampering, but the history exists and can be read.
- Level 2: the build runs on a hosted service and signs the provenance, so casual tampering is caught. The signature ties the statement to a real builder.
- Level 3: the build is hardened and isolated so the provenance is very hard to forge. The steps that generate it are protected from the code being built, which makes the statement non falsifiable in practice.
The climb from level 0 to level 3 is a climb from “trust me” to “here is a signed record you can verify without trusting me.” That progression is the whole idea. A single number gives teams a shared way to say how much a build can be believed.
A concrete example: verifying provenance before you deploy
Say your service depends on a package called acme-parser at version 2.4.0. You expect it to be built from the repository github.com/acme/parser. Before you promote the release, you fetch the artifact and its provenance and check them together.
$ slsa-verifier verify-artifact acme-parser-2.4.0.tgz \
--provenance-path acme-parser-2.4.0.intoto.jsonl \
--source-uri github.com/acme/parser \
--source-tag v2.4.0
Verifying artifact acme-parser-2.4.0.tgz: PASSED
- source: github.com/acme/parser@refs/tags/v2.4.0
- commit: a1b2c3d4e5f6...
- builder: github.com/acme/parser/.github/workflows/release.ymlThe verifier does three things. It confirms the artifact digest matches the subject in the signed statement, so the file was not swapped. It confirms the source URI is the repository you named, so the build did not come from a fork. And it confirms the signature is from a builder you trust. If an attacker republishes a tampered 2.4.0 built from github.com/evil/parser, the --source-uri check fails and the deploy stops. Nothing about that catch depends on you reading the code; the record either matches your expectation or it does not.
How an SBOM fits alongside provenance
An SBOM (Software Bill of Materials) is the related idea. Where provenance says where the artifact came from, an SBOM says what is inside it: a list of the components and dependencies the artifact contains, with their versions. It is an ingredient label for software.
The two work together. Provenance tells you the artifact really came from the expected source and build. The SBOM then lets you ask what that trusted artifact is made of, so when a new flaw lands in a library you can look up whether you shipped it. Provenance answers “can I trust this build,” and the SBOM answers “given I trust it, what did I just pull in.” Neither replaces the other.
Putting it into practice
Adopting provenance is three habits, not one big project.
- Generate provenance in the pipeline. Have the build system emit a signed statement for every artifact it produces, so the receipt exists by default rather than as an afterthought.
- Verify it before deploy. Make the verification a gate. If the source URI, commit, or builder does not match what you expect, the release does not go out. A record no one checks protects nothing.
- Pin and record dependencies. Lock the exact versions and digests your build consumes and keep that record, so the inputs to your build are as verifiable as the output. This is the same discipline that keeps a CI/CD pipeline honest end to end.
Consider a team that generates provenance but never gates on it. An attacker swaps a dependency during the build, the artifact ships, and the signed statement sits in a bucket that no deploy step reads. The provenance was correct and useless, because verification was optional. The record only helps when something acts on a failed check.
Build provenance turns “I hope this is the real artifact” into “I can prove it, or I refuse to deploy.” That shift from faith to a checkable record is how you keep a compromised build step or a swapped artifact from slipping through unnoticed. For more on how attacks move through the build and delivery path, read our deep dives.
UnboundCompute is an autonomous security researcher that tests the assumptions an application makes, and a supply chain that ships unverified artifacts is one more assumption worth checking before an attacker does. Learn how we think about it on our about page.
Frequently asked questions
What is build provenance?
Build provenance is signed, verifiable metadata attached to an artifact that records where it came from: which source commit produced it, which build system ran, and which steps executed. Because the builder signs it, a consumer can check that a binary was really built from the expected source and was not tampered with, instead of trusting a name and a version on faith.
How is provenance different from a checksum or hash?
A hash only proves two files are byte for byte identical. It says nothing about where the file came from. Provenance ties the artifact digest to a source commit, a builder identity, and the build steps, all signed. You need both: the hash to confirm the exact file, and provenance to confirm it came from the source and builder you expected.
What are the SLSA levels in plain terms?
SLSA grades build integrity in levels. Level 0 gives no guarantees and no provenance. Level 1 produces provenance that describes the build but is not tamper resistant. Level 2 runs on a hosted service and signs the provenance so casual tampering is caught. Level 3 hardens and isolates the build so the provenance is very hard to forge. The climb goes from trust me to a signed record anyone can verify.
How do build provenance and an SBOM work together?
Provenance says where an artifact came from and how it was built. An SBOM, or Software Bill of Materials, lists what is inside the artifact: its components and their versions. Provenance answers whether you can trust the build, and the SBOM answers what that trusted build contains, so you can look up whether you shipped a newly disclosed vulnerable library. Neither replaces the other.
Put an autonomous researcher on your own systems
UnboundCompute is an autonomous security researcher that reasons about how an application fits together and proves the access control and injection bugs it finds. We are opening a small number of founding design partner seats: private early access pointed at a staging target you choose, and a say in what it looks for. If your team ships software worth pressure testing, apply to the design partner program.