Provenance of what you deploy

How do you know the thing running in production is the thing you built?

Point at a process running in production and ask a simple-sounding question: what source code is that? The usual answer comes quickly — it is version 4.2.1, and here is the commit tagged 4.2.1 in the repository.

But notice what that answer actually rests on. It rests on a name. Somebody labelled a file with a version, and somebody else believes the label refers to that commit. Between the commit and the running process sits a build machine, an artefact registry, a deployment system, and several copies. If you were asked to demonstrate the link rather than assert it, what evidence would you have?

Work backwards from the running thing and count the joints. The process was started from a file on a host. That file was pulled from a registry by a tag. The tag pointed at something a build system pushed. The build ran on a machine, checked out a commit, and pulled in dependencies from elsewhere. Each of those is a handover, and at each one the question repeats: is what arrived what was sent?

Now ask what a version number does about any of that. Nothing, because a version number is a claim someone attached, and a tag is mutable — it can be repointed at a different file tomorrow with nothing visibly changing. Trusting a name is trusting whoever last wrote it.

So what would be better? Notice the property we want: a way to refer to an artefact that cannot be true of any other artefact. That is what a cryptographic digest gives you. Address the file by the hash of its contents and the reference is the content — you cannot swap the file and keep the name, because changing the file changes the name. Every joint can be nailed down the same way: this deployment used digest X, which is what the build produced, which came from commit Y.

But be careful here, because there is a step the reasoning skips. A hash proves that the file you have now is the file someone hashed. It does not tell you who hashed it, or that they were entitled to. Anyone can compute a hash of anything. So you need something that binds the digest to an origin — a signature over the digest by a key you have reason to trust. Hash gives you integrity; signature gives you authenticity. They answer different questions and neither substitutes for the other.

Push once more. Suppose you have a signed digest. What have you learned? That some key holder vouched for this file. You still do not know what the file is — what source it came from, what built it, whether the dependencies were the reviewed ones. That gap is what a provenance attestation fills: a signed statement describing how the artefact was produced — source repository and commit, builder identity, parameters, inputs — issued by the build system rather than by the developer.

That relocation of trust is the important move. The developer's laptop is the least trustworthy point in the chain — most humans, least observation. Provenance shifts the claim to a build service that cannot be told what to say about itself, because the attestation is generated by the platform rather than supplied by the job. That is exactly the distinction the SLSA framework's higher levels draw.

What none of it says is that the code is good. A perfectly attested artefact can be built from a commit containing a deliberate backdoor. Provenance answers "is this what was built, from what we think, by whom" — it makes the question of what was reviewed answerable, and says nothing about the review.

There is also a practical limit. Two builds of the same commit usually produce different bytes — timestamps, file ordering, paths, embedded build ids — so you generally cannot verify an artefact by rebuilding and comparing unless the build was made reproducible on purpose. Where that work has been done, an outsider can check; where it has not, you are trusting the builder's attestation rather than testing it.

Three refinements worth keeping.

First, separate the three questions that get bundled together. Integrity: is this byte-for-byte the artefact I mean? — answered by a digest. Authenticity: did someone I trust produce it? — answered by a signature. Provenance: from what source, by what process, with which inputs? — answered by an attestation. A team with checksums and no signatures has integrity against corruption but not against substitution.

Second, an inventory of contents is a different artefact again. A software bill of materials lists what is inside the thing; provenance describes where it came from. When a vulnerability is announced in a deep dependency, the bill of materials tells you whether you are affected, and provenance tells you that the bill describes the artefact you actually shipped.

Third, the verification has to happen at the point of use, not at the point of publication. Signing an artefact and then deploying by mutable tag, with nothing checking the signature at admission time, produces all the ceremony and none of the guarantee. The question a policy engine should ask before starting a container is whether this digest carries an attestation naming an approved source and builder — and it should refuse if not.

• Reproducible builds, and what it takes to make a compilation deterministic.
• Sigstore and keyless signing, which tie signatures to short-lived identities rather than long-lived keys.
• Admission control, where the verification either happens or does not.

Every term the collection defines is gathered in the glossary.