A build provenance attestation is a signed, machine-readable statement that connects an artifact digest to the build definition, resolved source and dependencies, builder identity, and invocation details that produced it. It should answer a deployment controller's question automatically: did an allowed builder create these exact bytes from an approved source under an expected workflow? A spreadsheet of release links cannot answer that reliably, and a signature over an artifact proves only that a key or identity signed it, not how the artifact came to exist.
The current SLSA 1.2 build provenance model uses an in-toto statement whose subject identifies output artifacts by digest and whose predicate describes build definition and run details. Adopting it does not require an evidence committee or a manual packet for every release. The builder can generate and sign the attestation during CI; policy can verify it before promotion; storage can retain the attestation beside the artifact lifecycle. Human review remains for exceptions and policy changes, not ordinary evidence transcription.
Define the threat and verification policy
Start with threats: a developer uploads local bytes under a release tag, an untrusted pull-request workflow obtains signing authority, a compromised build step substitutes source, an artifact is replaced after approval, or a valid attestation from a test repository is accepted in production. For each release class, define allowed subject type, source organization and repository, source reference or review state, build type, builder identity, signer or issuer, and required companion evidence. Policy should reject unexpected claims and unknown builders rather than checking only that some signature is valid.
| Claim | Example value | Verifier question | Failure |
|---|---|---|---|
| Subject digest | sha256 of image manifest | Are these the bytes being deployed? | Reject |
| Builder ID | Hosted production builder URI | Is this trusted build isolation? | Reject or lower trust tier |
| Build type | Versioned workflow build definition | Can claims be interpreted? | Reject unknown type |
| Resolved source | Repository plus commit digest | Was approved source used? | Reject |
| External parameters | Workflow and release inputs | Were unsafe inputs supplied? | Policy evaluate |
| Signer identity | CI workload identity and issuer | May this identity attest for builder? | Reject |
Choose the builder trust boundary
Provenance is only as trustworthy as the system that observes the build and emits the statement. If the same tenant-controlled script can choose arbitrary subjects and claims, a signature adds little. Prefer hosted or hardened builders where the control plane captures source, workflow, and output digest outside untrusted build steps. Separate pull-request testing from release builds, use ephemeral isolated workers, minimize credentials, pin reusable workflows and actions, and prevent ordinary repository code from selecting a more privileged builder mode.
Document what each builder ID means: operator, isolation, source acquisition, claim completeness, network access, secrets, signing path, and incident response. Different security modes need distinct identities. A self-hosted runner that persists between jobs should not share the trust label of an ephemeral managed runner merely because both execute the same YAML. Inventory builder versions and dependencies so a vulnerability can identify affected attestations. Rotate signing relationships without changing the semantic builder identity unless the trust boundary itself changes.
Generate the attestation in CI
Produce the artifact, upload it to immutable storage, and obtain its canonical digest from the storage or registry. Construct an in-toto Statement v1 with that digest as subject and the SLSA predicate type. Populate build type, external parameters, resolved dependencies, builder ID, invocation ID, and timestamps according to the builder's guarantees. Do not place secret values in parameters or byproducts. When one build emits multiple artifacts, include each subject or create clearly linked statements according to consumer needs.
Use short-lived workload identity for signing instead of a long-lived private key in repository secrets. Bind issuance to the expected CI identity, repository, workflow, and reference. GitHub's artifact attestation action can generate provenance for binaries and images and relies on scoped workflow permissions. Equivalent systems should keep the signing operation in a protected control plane. Ensure reruns create distinguishable invocation evidence while subjects with identical bytes remain verifiable.
Distribute evidence with the artifact lifecycle
A verifier needs to discover the attestation from the artifact digest. OCI referrers, transparency-backed bundles, repository attestation stores, or a controlled evidence service can provide that mapping. Store media type, predicate type, subject digest, signer material, and any inclusion evidence without relying on a mutable file name. Copy attestations when artifacts cross registries and verify the copy. Apply retention and deletion holds consistently: preserving provenance after deleting the artifact may support audit, while preserving an artifact without evidence prevents future trusted deployment.
| Lifecycle event | Artifact control | Attestation control | Audit record |
|---|---|---|---|
| Create | Immutable digest | Signed subject and predicate | Invocation and source |
| Promote | Same approved digest | Policy verification result | Environment and approver |
| Replicate | Destination digest compared | Bundle or referrer copied | Source and destination |
| Rollback | Retained prior digest | Prior policy rechecked | Reason and configuration |
| Revoke | Block deployment | Distrust signer or claim scope | Affected subjects |
| Retire | Delete after retention | Retain or delete by policy | Disposition evidence |
Verify at the deployment boundary
Verification first confirms cryptographic integrity and trusted identity, then evaluates claims. Sigstore's verification guidance supports certificate identity and issuer constraints and checks image digest claims. Add organization policy for subject repository, builder, build type, source reference, and required fields. Resolve a tag to a digest before verification and deploy that digest. Return a structured result with policy version and failed rule so operators can distinguish missing evidence from bad identity or disallowed source.
Enforce at the earliest durable trust boundary: registry admission, promotion service, Kubernetes admission, package publication, or deployment controller. CI verification alone is insufficient because later manual paths may bypass it. Run policy in audit mode to inventory failures before blocking, then enforce high-confidence rules for protected environments. Cache successful verification by subject digest and policy version, not tag. Re-evaluate when policy, trusted roots, signer revocation, or builder assessment changes.
Handle exceptions and revocation without paperwork
An exception is a signed policy object, not an email. It names the subject digest, failed rule, environment, business reason, compensating evidence, approver, creation time, and expiry. It cannot authorize a mutable tag or future artifacts. Emergency deployment should still record available source, checksums, and actor, then trigger a post-event rebuild in the trusted path. Track exception count, duration, repeated causes, and artifacts still running after expiry. Improve the builder or integration when the same exception recurs.
Revocation may concern a signing identity, builder version, source commit, workflow, dependency, or specific subject. Maintain an index from these claims to deployed artifacts so incident response can find exposure. A transparency log can show that an attestation existed, but it does not make a compromised builder trustworthy. Update trust policy, quarantine affected subjects, and retain the original evidence plus incident disposition. Rebuilding clean source on a repaired builder produces a new subject and provenance; do not overwrite the old record.
Measure coverage and evidence quality
Measure the percentage of production subjects with discoverable provenance, verification pass rate by rule, unknown builder count, claim completeness, exception age, evidence lookup latency, and time to identify deployed subjects for a revoked builder. Sample attestations and compare claims with source control and registry records. Test policy with intentionally malformed subjects, wrong repositories, unexpected workflows, missing dependencies, expired identities, and valid signatures over disallowed claims. A dashboard of attestation volume without deployment enforcement is activity, not assurance.
Roll out by artifact class. Begin with a controlled container build and one non-production admission gate. Establish subject discovery and explainable verification, then enforce in production and add binaries or packages. Generate audit evidence from the same verification events used operationally, producing periodic summaries rather than manual screenshots. Assign ownership across build platform, security policy, release engineering, and service teams so a failing claim reaches the group capable of fixing it.
Build provenance key takeaways
- Define allowed builder, signer, source, workflow, and subject claims from explicit threats.
- Generate attestations in a builder control plane that untrusted build steps cannot forge.
- Use the canonical artifact digest as the subject and keep secrets out of predicates.
- Make attestations discoverable and retain them with the artifact and rollback lifecycle.
- Verify cryptography and claims at the deployment boundary using versioned policy.
- Represent exceptions as scoped, expiring machine-readable policy and index claims for revocation response.
Build provenance FAQ
Is a signed artifact the same as provenance? No. A signature authenticates a statement or object. Provenance adds structured claims about the build and source; policy must verify both identity and those claims.
Does provenance prove the software is vulnerability-free? No. It supports traceability and integrity decisions. Vulnerability scans, tests, review, SBOMs, and runtime controls answer different questions and can be linked as companion attestations.
Must every developer understand the attestation schema? No. Platform tooling should generate and verify it. Developers need actionable failure messages and a documented path to fix inputs or request a narrow exception.
Conclusion
Provenance becomes useful when it is ordinary delivery data: generated by a trustworthy builder, attached to exact bytes, discovered automatically, evaluated by policy, and retained for rollback and response. That workflow replaces screenshots and release packets with repeatable evidence while making exceptions more precise. Start with a narrow trusted path, enforce claims where artifacts enter production, and grow coverage from measured gaps.