build_provenance v1.0.0

name: "build_provenance" description: "Make software releases provable: signed builds, reproducible builds, SLSA attestations, Sigstore signing, and admission-time verification. Use when setting up release signing, adding provenance to a CI pipeline, verifying an artifact's origin, or choosing between GPG, cosign, GitHub attestations, and SLSA levels."

Build Provenance

Purpose

Turn "trust me, I built this" into a checkable claim. A release gets a signed statement of exactly what source, workflow, and builder produced each artifact, built so independent rebuilds can reproduce the same bytes, and verified at the point of consumption (by a person with a CLI, or by a cluster at admission).

Workflow

1. Pick the provenance model first. For container images: cosign keyless signing + SLSA provenance. For release binaries: GitHub Artifact Attestations (actions/attest-build-provenance@v1) or slsa-github-generator for Build L3. For Debian-style packages: reproducibility with .buildinfo. See references/provenance-stack.md for the SLSA level ladder (L1/L2/L3) and what each tool actually guarantees.

1. Make the build reproducible before you sign anything. Pin the toolchain and lockfiles, set SOURCE_DATE_EPOCH from the commit timestamp, strip absolute paths (-ffile-prefix-map), sort inputs, and compare two builds byte-for-byte in CI. Signing a nondeterministic build proves origin but leaves tampering in the build window unverifiable.

1. Sign keyless, log publicly. Use Sigstore Fulcio + Rekor (via cosign or GitHub OIDC), never long-lived GPG keys you have to store, rotate, and pray nobody leaks. Sign by content digest (@sha256:...), never by tag.

1. Publish the provenance beside the artifact. Provenance files live with the release (.intoto.jsonl), SBOMs are signed too. Write the consumer's verification recipe into your release docs, not just "possible in theory."

1. Verify at the consuming end. Users check with slsa-verifier or gh attestation verify; clusters enforce with Kyverno verifyImages. Roll out enforcement in Audit mode first, then flip to Enforce.

Output Contract

Delivering a provenance setup means producing:

• Signed artifacts + provenance statements attached to each release, verifiable by an outsider with the documented commands.
• A double-build CI job proving reproducibility (or a documented gap).
• A written verification recipe a consumer can run in under 5 minutes.
• Optionally: an admission policy enforcing signature checks, landed in Audit before Enforce.

Operating Rules

• Keyless Sigstore first; long-lived signing keys only when a compliance regime forces them.
• Never sign by tag. Always by digest.
• State the SLSA level AND the spec version (levels differ between v1.0/v1.2; GitHub docs still reference v1.0). A level claim without a version is half a claim.
• When verifying, pin the source ref (--source-ref refs/tags/vX.Y.Z), not just the repo. An attestation names the workflow; without the tag, a borrowed attestation from another release passes.
• Provenance covers binaries and images. It does not cover the build environment being clean. Pair with reproducible builds or honest SLSA-level scoping.
• Validate provenance files locally with bin/check-provenance.py before publishing. It checks the in-toto envelope, SLSA predicate type, subject digests, and builder identity presence.
• Skip anything you cannot verify: unverified numbers, invented tool flags, and copied configs with untested pins get cut.