Skip to content
Blog

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.