How do you publish a Docker Hub image with SLSA provenance?

To publish a Docker Hub image with provenance, build it with docker buildx build and the provenance attestation option, then push. BuildKit attaches a signed-off record of the source, builder and base images to the image. Use mode min by default, and mode max only if your build arguments hold no secrets.

What is provenance for a container image?

Provenance is a statement about how an artifact was built: which source revision, which build steps, which base images. Docker's documentation says BuildKit generates it in the SLSA provenance format, with schema version 0.2 as the default and version 1 available as an option.

It answers a question a registry tag cannot. A tag says "this is acme/api:1.4". Provenance says "this digest came from this repository at this commit, built from these inputs."

How do you create it?

Docker's docs give the flag directly. A minimal example:

docker buildx build \
  --tag <namespace>/<image>:<version> \
  --attest type=provenance,mode=max,version=v1 \
  --push .

The shorthand --provenance=true also works. Because the attestation is stored alongside the image in the registry, you need a build that pushes (or exports through the image exporter), not a plain local load.

Should you use mode min or mode max?

Docker describes two levels.

Min, the default, records build timestamps, the frontend, the build materials (base images), the source repository and revision, the platform, and reproducibility. Docker states min is safe for all builds because it does not leak anything from the build environment.

Max adds the build graph definition, the Dockerfile contents and source maps. Docker recommends max when possible because it is far richer for analysis. But it also exposes the values of build arguments.

That is the trap. If anyone passes a token with --build-arg, max mode publishes it inside the attestation. Docker's guidance is to refactor those builds to use secret mounts, which never end up in provenance. Fix that first, then switch to max.

How do you inspect what you published?

Use imagetools inspect with a Go template. All provenance data sits under the .Provenance attribute:

docker buildx imagetools inspect <namespace>/<image>:<version> \
  --format "{{ json .Provenance.SLSA }}"

Check three fields in the output: the source repository and revision, the materials list (are your base images pinned by digest?), and the build type. If the revision is not the commit you intended to release, stop.

Does provenance prove the image is safe?

No. SLSA's own levels page describes Build level 1 as "provenance exists", level 2 as a hosted build platform, and level 3 as hardened builds. Provenance generated on a developer laptop is useful for inventory but is weak evidence, because the same machine produced both the image and its claim.

The stronger setup is to build on a hosted CI platform, sign the attestation, and verify the signature before deploy. Sigstore's cosign documentation describes keyless signing, where a short-lived certificate binds an ephemeral key to an OpenID Connect identity and the event goes into the Rekor transparency log. Deploy-time verification can then require "built by this workflow in this repository."

Which Docker Hub specifics matter?

• Pull and deploy by digest. Docker's pull documentation describes digests as the immutable identifier, unlike tags.
• Provenance covers the image you built, not the image tags you later move. Promote by digest.
• Record base images by digest so the materials list is reproducible.

Safeguard's SBOM and dependency scanning can read what is inside the image you attested, which complements provenance: provenance says where it came from, the scan says what is in it.

What to do

1. Move any secrets out of build arguments and into secret mounts.
2. Add --attest type=provenance,mode=max (or --provenance=mode=max) to your release build.
3. Build on hosted CI, not a laptop, for anything you ship.
4. Sign the image and attestation, for example with cosign keyless signing.
5. Verify the signature and the source revision before deploy.
6. Deploy by digest and pin base images by digest.

Quick check

Sources

• SLSA provenance attestations, Docker Docs, fetched 18 October 2026
• docker image pull, Docker Docs, fetched 18 October 2026
• SLSA levels, slsa.dev, fetched 18 October 2026
• Cosign signing overview, Sigstore, fetched 18 October 2026

Last reviewed: 18 October 2026.