With Docker BuildKit, build attestations live in the image's index as extra manifests. Each attestation manifest points to one platform specific image manifest and holds one layer of in-toto JSON. Because they are stored in the registry, you can inspect them without pulling the whole image.
This surprises people who expect an attestation to be a separate file somewhere. It travels with the image reference, which is what makes it useful and also what trips up some tooling.
The structure in plain terms
An image reference often resolves to an index, which lists one manifest per platform, such as amd64 and arm64. BuildKit adds attestation manifests to that same index. The Docker documentation says each one points at a single platform image manifest and contains a single layer with the attestation data, stored as JSON blobs in the in-toto format.
So a multi platform image can carry attestations for each platform, side by side with the image itself.
| Part | Role |
|---|---|
| Image index | Lists manifests for the image |
| Platform manifest | The runnable image for one platform |
| Attestation manifest | Points at one platform manifest, one layer of attestation data |
| Attestation layer | An in-toto JSON blob, such as provenance or an SBOM |
What gets attached and when
The documentation lists two types: SBOM and provenance. Provenance at mode=min is added by default. The SBOM is opt in with --sbom=true. Max level provenance is opt in with --provenance=mode=max. You can switch provenance off with --provenance=false, and the environment variable BUILDX_NO_DEFAULT_ATTESTATIONS disables the default provenance attestations.
Driver support matters. The docker driver needs the containerd image store, while the docker-container, kubernetes and remote drivers support attestations directly.
Things that surprise teams
The image digest you deploy. An index digest and a platform manifest digest differ. Make sure your verification and your deployment refer to the same one you intend.
Exporters. The local and tar exporters cannot store attestations in a manifest, so they write JSON files to the root of the export instead. If you build to a tarball in CI, look for those files.
Tooling that only understands single manifests. Some older scanners or copy tools may not carry the extra manifests along. When you copy an image between registries, check that the attestations arrived.
A short verification routine
- Build with attestations enabled and push to your registry.
- Inspect the index and confirm attestation manifests exist for each platform.
- Read the provenance JSON and compare the subject digest with the image you will deploy.
- After any registry copy or promotion, repeat steps two and three.
Why this matters for scanning
An SBOM attestation lets you rescan an image's contents later without rebuilding. Safeguard supports SBOM and container scanning, and the container image scan demo shows what a report looks like.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how findings are tied to image layers and components.
Quick check
Do I need to pull the image to read its attestations?
No. They are stored as manifests in the registry, so you can inspect them without pulling the full image.
Is provenance on by default in BuildKit?
Provenance at mode min is added by default. SBOMs are opt in.
Sources
Last reviewed: 19 October 2026.
