Understanding Image Provenance: Proof of where your container came from

Evidence in a courtroom is only admissible if every hand it passed through is documented: who collected it, who stored it, who moved it, and proof that no one tampered with it in between. Break the chain at any point and the evidence becomes difficult to trust, no matter how genuine it looks.

Software artifacts face a similar challenge. Before a container image reaches production, it passes through source repositories, build systems, dependency resolvers, registries, and deployment pipelines.

Provenance is the record that documents that journey.

What Is Image Provenance?

Provenance is the documented, verifiable record of where a software artifact came from and how it was produced.

For a container image, provenance answers: who built this, from what source code, at what point in time, in what environment, with what inputs, and that claim is cryptographically verifiable.

Think of it like a certificate of origin on a manufactured part. The part looks identical whether it was made in a certified facility under controlled conditions or assembled in someone's garage with counterfeit components. The certificate is what proves which one you're holding.

Provenance may sound like a niche security concept, but it has become increasingly important as software supply chain attacks move beyond application code and target build pipelines, dependencies, and CI/CD systems. When an image reaches production, teams need confidence that it was built from the expected source, by a trusted process, and has not been altered along the way.

Provenance provides that confidence by creating a verifiable record of the image’s journey from source code to deployment.

This becomes especially important in containerized environments, where a single image may contain components from multiple sources and build systems.

Provenance in Containerized Environments

Containers make provenance especially important, but also harder to establish and verify.

A typical container image is a stack of layers. Your application sits at the top. Below that: runtime dependencies, base OS utilities, foundational libraries like glibc and OpenSSL. Most of those layers came from somewhere else, a public registry, an upstream maintainer, an automated build pipeline you don't control.

That layered structure means the question "where did this come from?" has many answers, nested inside each other. Your application code came from your repo. The Python runtime came from an upstream build. The base OS layer came from a distribution maintainer.

A container without provenance is a black box at every layer. You know it runs. You don't know the path it took to get there.

Here's what a container's provenance chain looks like end-to-end:

Every step in the chain introduces an opportunity for tampering. Provenance creates a cryptographic record of each step, making any unauthorized changes visible.

What Image Provenance Actually Includes

A provenance record for a container image typically contains:

Builder identity — Who or what ran the build. Usually a specific CI/CD system with a verified identity, such as a service account, a workload identity, or a signing key tied to a build platform.

Source reference — The exact repository URL and git commit hash the image was built from. A commit hash, not a branch name, because hashes are immutable.

Build environment — The runner, OS, container image used during the build itself, compiler versions, and configuration flags. Two builds from the same source can produce different outputs if the environment differs.

Inputs and output hashes — Cryptographic hashes of everything that went into the build (Dockerfile, dependency lockfiles, build scripts) and the resulting image digest. If any input changed, the hash changes.

Timestamp — When the build occurred. Useful for audit trails and for detecting replayed or backdated records.

Signing key / identity — The cryptographic key that signed the provenance record, and ideally a transparency log entry proving the signature existed at that specific time.

Together, these fields let a consumer answer: "Is this image exactly what I expect, built the way I expect, by the system I trust?"

How Provenance Is Generated and Stored

Provenance doesn't appear automatically. It has to be built into the build pipeline.

The build pipeline's role

Provenance is generated at build time, by the build system itself. The most reliable provenance comes from hermetic builds - builds that run in isolated, reproducible environments where every input is pinned and every output is deterministic. If two builds from the same inputs produce different images, you don't have reproducibility, and your provenance record is weaker for it.

SLSA (Supply chain Levels for Software Artifacts) is the framework that defines what "good provenance" looks like and how much you can trust it, based on how the build was run. The SLSA Build Provenance specification defines the structure and requirements for provenance attestations.

Where provenance lives

Provenance records are stored as OCI artifacts: they live in the same registry as the image, attached to the image digest. When you pull an image, its provenance travels with it. No separate database, no external lookup required.

# Download provenance for an image
cosign download attestation myregistry/myapp:1.0.0

# Output: signed SLSA provenance JSON
# Shows: builder identity, source commit, build timestamp, input hashes

How Provenance Is Verified

Generating provenance is only half the story. You also need to verify it before anything gets deployed.

cosign verify

The most direct verification step. Checks that the image's cryptographic signature is valid and matches the expected signing identity.

cosign verify \
  --certificate-identity "https://github.com/myorg/myrepo/.github/workflows/build.yml@refs/heads/main" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  myregistry/myapp:1.0.0

If the image was tampered with after signing, this fails. If the signature came from an unexpected identity, this fails.

Policy enforcement with Kyverno and OPA

For Kubernetes environments, provenance verification should happen automatically at deployment time. Kyverno and OPA/Gatekeeper are admission controllers that intercept every pod creation request and enforce policies before anything runs. A policy can require that all images carry a valid Cosign signature from a trusted builder, a valid SLSA provenance attestation at a minimum level, and that the source commit is from an approved repository.

If an image can't produce valid provenance, the pod doesn't start.

Image Provenance vs. Image Integrity

These two concepts are related but distinct and conflating them leads to blind spots.

Integrity answers: has this image been modified since it was built? It's verified by checking the image digest, a SHA-256 hash of all the image layers. If even one byte changed, the digest changes. Pinning images by digest (myimage@sha256:abc123...) rather than by tag is the basic form of integrity verification.

Provenance answers: where did this image come from and how was it built? It's verified by checking the signed provenance record against your expectations of the build process.

You need both:

Digest pinning protects against attackers who replace an image behind a tag. Provenance verification protects against attackers who compromise the build process itself and produce a seemingly legitimate image from tampered source code.

Provenance, SBOMs, and Attestations: What's the Difference

These three terms appear together constantly. Here's what each one actually is:

SBOM (Software Bill of Materials) is an inventory of what's in the image — every package, library, and dependency, with versions and licenses. It answers "what is this image made of?"

Provenance is the record of how the image was built — who built it, from what source, in what environment. It answers "where did this image come from?"

Attestation is the signed wrapper around both. An attestation is a cryptographically signed statement asserting that a claim is true — "this image has this SBOM" or "this image was built with this provenance." Without the attestation, an SBOM or provenance document is just a file. With the attestation, it's a verifiable claim tied to the specific image digest.

All three travel together as OCI artifacts attached to the image. Verifying the attestation proves the claim hasn't been forged or swapped in transit.

Why Image Provenance Matters

Provenance isn't a compliance checkbox. It's the answer to questions that come up constantly in real operations, and that most teams currently can't answer well.

Accountability and audit trails

Accountability means being able to prove what shipped and who produced it. Without provenance, that takes piecing together scattered deployment logs, registry tags, and CI histories, and the trail goes cold fast. Provenance makes the record durable and self-contained: every image carries its own audit trail of source commit, build time, and builder identity. That turns "we think this came from our pipeline" into something you can prove, which is what a compliance audit, a customer security review, or post-incident forensics demands.

Attack prevention

Most container supply chain attacks succeed because build inputs aren't verified. A dependency is swapped. A build action is modified. A tag is pointed at malicious code.

Workflows that pinned to a tag rather than a verified commit hash ran the malicious version silently. Provenance enforcement makes this class of attack detectable: if a build input doesn't match the recorded hash, verification fails before anything deploys.

Trust across handoffs

Images change hands, from build system to registry to deployment pipeline to production cluster. Each handoff is a point where trust has to be re-established. Provenance makes that re-establishment automatic. Instead of assuming the image that arrived is the image that was built, every consumer in the chain can verify it independently.

Compliance evidence

Regulations and frameworks, from EO 14028 to NIST SSDF to PCI DSS 4.0, increasingly require organizations to demonstrate that they know what's in their software and where it came from. Provenance, combined with SBOMs, is the machine-readable evidence that satisfies those requirements. The alternative is manual documentation that's expensive to produce and impossible to keep current.

Before and After: Container With vs. Without Provenance

Here's what the same image looks like from a security and audit perspective:

The images may be functionally identical. The difference is what you can prove about each one.

Common Provenance Standards and Technologies

A quick map of the tools and standards you'll encounter:

SLSA (Supply chain Levels for Software Artifacts)

SLSA is a framework, not a tool, that defines levels of supply chain security maturity. Each level adds requirements around how builds are run and how provenance is generated:

• SLSA Level 1: Provenance exists and documents the build process. Unsigned.

• SLSA Level 2: Provenance is signed by the build service. Build runs on a hosted platform.

• SLSA Level 3: Build platform is hardened. Source and build are verified. Provenance is signed by a trusted, isolated build environment.

Most organizations treat SLSA L3 as the practical production target, which requires real build isolation and cryptographic signing without the extreme requirements of theoretical higher levels.

in-toto

The underlying framework for defining and verifying supply chain layouts: the ordered sequence of steps that must happen for a build to be considered valid. SLSA provenance is often implemented using in-toto attestations, doing the per-step verification that makes provenance granular rather than just a single top-level claim.

Sigstore (Cosign + Rekor + Fulcio)

The open source project that makes signing practical at scale:

• Cosign: Signs images and attestations, verifies signatures, downloads provenance from OCI registries

• Rekor: The public transparency log where signatures are recorded immutably, so even if a signing key is later compromised, the timestamp is preserved

• Fulcio: Issues short-lived signing certificates tied to OIDC identities, enabling keyless signing with no long-lived key management required

OCI Attestations and Metadata

The OCI Image Specification 1.1 introduced the Referrers API, a standard way to attach provenance, SBOMs, signatures, and scan results directly to an image digest in any compliant registry. Before this, tools used inconsistent ad-hoc approaches. Now, any OCI 1.1-compliant registry (Docker Hub, ECR, GCR, Harbor, Quay) can store and serve provenance alongside the image it describes, which is what makes "provenance travels with the image" actually true in practice.

Challenges in Implementing Image Provenance

Provenance is well-understood in theory. In practice, several things slow adoption:

Tooling immaturity

The ecosystem is still consolidating. SLSA 1.0 was finalized in 2023. OCI 1.1 with the Referrers API is relatively recent. Cosign and Rekor are stable, but workflows around keyless signing in enterprise environments still require careful setup. Expect rough edges.

Multi-stage builds and third-party base images

Provenance is straightforward when you control the entire build. It gets complicated when your image starts FROM an image you didn't build. Your provenance record documents your steps, but it can't extend into the base image unless that image also ships provenance. This is a real gap in most traditional base images, and the reason source-built base images, where provenance is generated from the ground up, close something that stripping and hardening can't.

Verification at scale

Generating provenance is easier than consuming it. At scale, you need automated verification at every deployment point: admission controllers in every cluster, policy definitions for every image source, and handling for images that predate your provenance requirements. Rolling this out across an organization with hundreds of services is a sustained engineering effort.

Developer adoption friction

Provenance is invisible to developers until something breaks. Getting teams to pin build actions by commit hash, use hermetic build environments, and treat unsigned images as a policy violation requires tooling investment and cultural change. The security benefit is real, but it has to be made frictionless, otherwise developers route around it.

Where to Go From Here

Provenance is a foundational property of modern container security — not something you add later, but something that has to be built into the pipeline from the start. Once you have it, you can answer questions that were previously unanswerable: exactly what ran in production, exactly where it came from, exactly when it was built.