Image Provenance: Who Built It, When, and From What
Understanding container image provenance, SLSA supply chain security levels, BuildKit attestations, SBOM generation, and inspecting build origin metadata.
Published on • November 18, 2026
AI Assistant

In modern software supply chain security, running an unverified container image in production is a significant security risk. Image Provenance provides cryptographic proof detailing who built an image, which source repository commit was used, what build flags were passed, and what dependencies were embedded into the final layers.
With open standards like SLSA (Supply-chain Levels for Software Artifacts) and BuildKit’s native attestation support, container provenance has evolved from optional metadata to a core compliance requirement.
In this article, we will explore container provenance concepts, how to build images with cryptographic attestations, generate Software Bill of Materials (SBOMs), and inspect build lineage.
What is Image Provenance?
Provenance is verifiable metadata attached to a built artifact. For a container image, provenance answers four critical questions:
+-----------------------------------------------------------------------------------+
| Container Provenance Record |
+-----------------------------------------------------------------------------------+
| 1. SOURCE REPOSITORY : https://github.com/org/repo.git |
| 2. REVISION / COMMIT : git commit 7a8b9c0d1e2f3... |
| 3. BUILD ENVIRONMENT : GitHub Actions Runner #412 (BuildKit v0.12) |
| 4. BASE DEPENDENCIES : debian:bookworm-slim (digest sha256:4f2a...) |
+-----------------------------------------------------------------------------------+
Without provenance, an organization cannot verify whether an image tagged app:v1.2.0 in a registry actually matches the code reviewed and merged into the main git branch.
The SLSA Framework and Provenance Levels
The SLSA framework defines four levels of supply chain assurance:
- SLSA Level 1: Automated build process that generates un-signed provenance documentation.
- SLSA Level 2: Build executed on a dedicated build service; provenance signed by the build platform.
- SLSA Level 3: Build platform isolated from runner manipulation (hardened non-falsifiable provenance).
Generating Provenance Attestations with Docker Buildx
Docker Buildx (powered by BuildKit) includes native support for generating OCI provenance and SBOM attestations directly during image creation.
Building with Provenance Attestations
To build an image and attach SLSA-compliant provenance:
docker buildx build \
--provenance=mode=max \
--sbom=true \
--tag myregistry.com/team/service:v1.0.0 \
--push .
--provenance=mode=max: Captures full build metadata including source URL, git commit, build arguments, environment variables, base image digests, and intermediate step timelines.--sbom=true: Generates an in-toto Software Bill of Materials attestation listing all installed packages.
Inspecting Image Provenance
Once an image is built with BuildKit attestations, you can inspect its provenance records using docker buildx imagetools:
docker buildx imagetools inspect myregistry.com/team/service:v1.0.0 --format "{{json .Provenance}}"
Sample output snippet:
{
"_type": "https://in-toto.io/Statement/v0.1",
"predicateType": "https://slsa.dev/provenance/v0.2",
"subject": [
{
"name": "myregistry.com/team/service",
"digest": {
"sha256": "8a39c01f421e..."
}
}
],
"predicate": {
"builder": {
"id": "https://github.com/docker/build-push-action"
},
"invocation": {
"configSource": {
"uri": "git+https://github.com/myorg/myapp@refs/heads/main",
"digest": {
"sha1": "7a8b9c0d1e2f3..."
}
}
}
}
}
Automating Provenance in GitHub Actions
Using Docker’s official GitHub Action automatically records GitHub OIDC claims and workflow run details into the image provenance attestation:
name: Secure Build with Provenance
on:
push:
branches: [ "main" ]
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write # Required for OIDC identity claims
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to Registry
uses: docker/login-action@v3
with:
registry: myregistry.com
username: ${{ secrets.REGISTRY_USER }}
password: ${{ secrets.REGISTRY_TOKEN }}
- name: Build and Push with Provenance
uses: docker/build-push-action@v5
with:
context: .
push: true
tags: myregistry.com/team/service:${{ github.sha }}
provenance: mode=max
sbom: true
Verifying Provenance in Deployment Admission Controllers
In Kubernetes clusters, admission controllers (such as Kyverno or OPA Gatekeeper) can be configured to block container deployment unless valid, signed provenance attestations are present in the registry manifest.
For example, a Kyverno policy can enforce that all production images must originate from https://github.com/myorg/ and have been built by an authenticated GitHub Actions pipeline.
Summary
Container image provenance transforms black-box images into transparent, verifiable artifacts. By building with --provenance=mode=max and verifying attestations, organizations protect their production pipelines against supply chain tampering and unauthorized image injection.