--- slug: build-provenance type: concept summary: "A cryptographically verifiable record of how an artifact was built (its source, builder, and parameters) that lets a consumer check origin rather than trust it." created: 2026-06-16 updated: 2026-06-16 related: artifact: relation: uses note: "Provenance is the attestation attached to an artifact, describing how that artifact was produced." pipeline-as-code: relation: depends-on note: "Provenance attests to the build a pipeline ran, so a versioned pipeline definition is what makes the attestation meaningful." continuous-delivery: relation: complements note: "A delivery pipeline is where provenance is generated, and verifying it becomes a release gate." continuous-deployment: relation: complements note: "When deploys happen automatically, verifying provenance is the gate that keeps an unattested build out of production." rollback: relation: supports note: "Provenance lets you prove which build you are reverting to, not just which version number." agent-provenance: relation: complements note: "Agent provenance records which agent authored a change; build provenance records how the resulting artifact was built, and together they form a custody chain from author to binary." trust-boundary: relation: complements note: "A build pipeline is a trust boundary, and provenance is how a consumer checks what crossed it." blast-radius: relation: complements note: "A poisoned build expands blast radius silently; provenance is how that compromise is detected before it spreads." least-privilege: relation: complements note: "Provenance and least privilege are the two halves of a defensible build: limit what the pipeline can do, then attest to what it did." --- # Build Provenance > **Concept** > > Vocabulary that names a phenomenon. *A cryptographically verifiable record of how a software artifact was produced, so a consumer can check where it came from instead of trusting that it came from the right place.* *Also known as: Build Attestation, SLSA Provenance* You download a container image, install a package, or pull a binary into your release. The version number says `2.4.1`. The question provenance answers is the one the version number can't: was this `2.4.1` actually built from the source you reviewed, on the build system you trust, or is it something a tampered pipeline slipped in under the same name? A version string is a label anyone can write. Build provenance is the receipt that proves the label is honest. ## What It Is Build provenance is a record of *how an artifact was built*: which source revision it came from, who or what built it, on which build platform, at what time, with which parameters and dependencies. Crucially, the record is signed, so it is tamper-evident. A consumer downstream can verify that the attestation is authentic and that the artifact it describes is the one in their hands. It helps to set provenance next to its close cousin, the Software Bill of Materials. An SBOM is an inventory: it lists *what is inside* a finished artifact, every library and version that went into it. Provenance is a chain of custody: it documents *how the artifact came to be*. The two answer different questions. SBOM answers "what is in this binary?" Provenance answers "was this binary built from the code I think it was, through a pipeline that wasn't compromised?" You can have a perfect SBOM for a binary that a hijacked build server produced from poisoned source. The SBOM would be accurate and the artifact would still be dangerous. Provenance is the part SBOM structurally cannot supply. The idea has converged on a standard family. SLSA (Supply-chain Levels for Software Artifacts) defines a `provenance` predicate, a structured statement of the build's inputs and environment, carried inside the in-toto attestation format. Signing infrastructure such as Sigstore makes the statement authentically attributable to its builder without anyone having to manage long-lived private keys. And major build platforms, including GitHub Actions and Google Cloud Build, now emit these attestations automatically as a build runs. So provenance is not a bespoke thing each team invents; it's a named, portable record other tools know how to read and check. > **📝 Note** > > SLSA describes build integrity as a ladder of levels, from "provenance exists" at the bottom to "provenance is generated by a hardened, isolated builder and is non-falsifiable" near the top. The levels give a team a way to talk about *how much* a given attestation is worth, rather than treating provenance as a single box to tick. ## Why It Matters The supply chain is where the agentic era applies the most pressure, and provenance is the pillar that takes the load. Software supply-chain attacks have climbed sharply, and the attacker's move is rarely to break your code on your machine. It's to compromise something upstream, a dependency or a build step, so that what ships is not what you reviewed. When the artifact in production diverges from the source in review, every other control you have is reasoning about the wrong thing. AI agents sharpen this. As agents author and land more code, and as humans review a smaller fraction of what gets written, the trust boundary between "a change merged" and "the binary in production is the attested output of that reviewed source" widens. [Agent Provenance](agent-provenance.md) closes one half of that gap by recording *which agent authored the change*. Build provenance closes the other half by recording *how the resulting artifact was built*. Together they give you a custody chain that runs from an agent-authored commit all the way to the signed binary, each link verifiable rather than assumed. This is the same shift this book keeps returning to: verification moves from *trusting the producer* to *checking the output*. You stop asking whether you trust the build server and start asking whether this specific artifact carries a valid attestation tracing it to reviewed source. That's a mechanical check a machine can run on every release, not a matter of faith in a vendor or a colleague. It scales the way trust does not. ## How to Recognize It You are looking at build provenance, or its absence, in a few concrete places: - **An attestation file or signature accompanies the artifact.** A container image with a Sigstore signature and an attached SLSA provenance statement has it; a tarball dropped on a download page with nothing but a version number does not. - **The build platform emits a provenance record.** If your CI generates an in-toto attestation naming the source commit, the workflow that ran, and the builder identity, provenance is being produced. If your release is built on a developer's laptop and copied to a server, there is nothing to attest. - **A consumer verifies before it consumes.** The presence of provenance only pays off when something checks it. Look for a deploy step or admission control that *rejects* an artifact whose provenance is missing, unsigned, or traces to the wrong source. Generation without verification is a receipt nobody reads. - **You can answer "what built this?" without forensics.** If, given a binary in production, you can name its source revision and build run from a signed record rather than reconstructing it from memory and logs, provenance is doing its job. A useful test: pick a build artifact you shipped last week and try to *prove* (not recall, prove) which commit it came from. If the proof is a signed attestation you can verify today, you have provenance. If the proof is "trust me, that's how the pipeline works," you don't. ## How It Plays Out A team ships a popular open-source library as a published package. After a wave of registry-account compromises in the ecosystem, they turn on build provenance: every release is now built only in a GitHub Actions workflow that emits a signed SLSA attestation tying the package to its exact source tag and build run. A downstream company adds a verification step to its install pipeline that refuses any version of the library whose provenance doesn't trace to that workflow. When an attacker later publishes a malicious version under a stolen maintainer token, it has no valid attestation from the trusted builder, and the downstream gate drops it on the floor before it ever reaches a developer's machine. A platform team runs continuous deployment, so a merge to main can reach production without a human in the loop. That automation is exactly what makes an unattested build dangerous: there's no review step to catch a substituted artifact. They make verification the gate. The deploy controller checks each image's provenance against policy (built by the sanctioned pipeline, from a commit on a protected branch), and an image that fails is never admitted. The fast path stays fast, but it now refuses to ship anything it can't trace. A developer asks an agent to cut a release. The agent runs the pipeline, which builds the artifact and produces its signed provenance automatically. Because the attestation records the source commit, the builder, and the parameters, the developer doesn't have to take the agent's word for what it shipped. Months later, investigating a regression, they reach for the binary in production and read its provenance to find the exact revision it was built from, then verify against that, instead of guessing which of the agent's many runs produced it. ## Consequences **Benefits.** Provenance turns origin from something you trust into something you check. A consumer — a deploy gate, an admission controller, another team, an agent — can verify mechanically that an artifact traces to reviewed source through an uncompromised build, and can do it on every release rather than spot-checking. It detects a whole class of supply-chain tampering that an SBOM would miss, because it watches *how* the artifact was made, not just what's inside it. And it gives you a precise answer to "which build is this?" that survives an incident, when memory and logs don't. **Liabilities.** Generation is cheap; verification is where the work and the value are. A pipeline that emits attestations nobody checks has added ceremony without adding safety, and it's easy to stop at the generating half because it's the half a platform turns on for you. Provenance is also only as strong as the builder that produced it: an attestation from a build environment an attacker controls is a confident statement of a lie, which is why SLSA grades builders by how hard they are to subvert. The verification policy itself becomes something you have to maintain: which builders you trust, which branches count, how you handle key rotation and revocation. And provenance proves *origin*, not *correctness* — a faithfully attested artifact built from reviewed source can still carry a bug or a vulnerability the review missed. It tells you the binary is what you think it is, not that what you think it is happens to be good. ## Sources - The [SLSA framework](https://slsa.dev/spec/v1.0/provenance) defines the `provenance` predicate and the levels-of-assurance ladder that gave build provenance a portable, standard shape. - The [in-toto](https://in-toto.io/) project, originated by Santiago Torres-Arias and collaborators, provides the attestation format that carries provenance statements as signed, machine-checkable claims about a build. - [Sigstore](https://www.sigstore.dev/) supplied the keyless signing and transparency-log infrastructure that makes a provenance statement authentically attributable to its builder without long-lived private keys. - The distinction between an SBOM (what is inside an artifact) and provenance (how the artifact was built) emerged from the broader software supply-chain security community as both practices matured alongside each other. --- - [Next: GitOps](gitops.md) - [Previous: Pipeline Synthesis](pipeline-synthesis.md)