Use docker buildx build with the sbom option set to true to attach a software bill of materials, and set the provenance option to mode=max for a fuller build record. Provenance at the minimal level is added by default. Both are stored as attestations next to the image in the registry.
What the two attestations are
Docker's documentation defines build attestations as metadata that describes how an image was built and what it contains. BuildKit creates them at build time and attaches them to the final image. There are two kinds.
| Attestation | Answers | Default |
|---|---|---|
| SBOM | What software is in or was used to build the image | Off, opt in |
| Provenance | How the image was built | On at the min level |
The documented switches are the sbom option set to true, the provenance option set to mode=max, and the provenance option set to false to turn it off. An environment variable, BUILDX_NO_DEFAULT_ATTESTATIONS, disables the default provenance globally.
How they are stored
Attestations follow the in-toto format and are saved as JSON blobs. For images in a registry, each attestation is a manifest referenced from the image index, so you can inspect it without pulling the whole image. The local and tar exporters cannot store manifests, so they write the attestations as JSON files in the root of the export instead.
Builder requirements
This catches people out. With the default docker driver, attestations need the containerd image store, and the build fails without it. The docker-container, kubernetes and remote drivers support them, and when you push, the attestations are kept whatever the daemon image store is. If your CI uses a plain daemon setup, test one build end to end before you roll it out.
Steps to adopt
- Pick a builder that supports attestations and confirm with a test build.
- Turn on the SBOM option and the max provenance mode for release builds.
- Push to your registry and inspect the image index to confirm the attestation manifests are present.
- Feed the SBOM to your scanner so findings come from the same list of components you shipped.
- Decide what verifies provenance before deploy, since an attestation nobody checks protects nothing.
What they do not prove
An SBOM generated at build time lists what the tool could detect. It can miss software copied in as an unpackaged binary, and it says nothing about whether components are vulnerable. Provenance records how the build ran, but a record is only as trustworthy as the builder and signing around it. Read what a container image SBOM contains and misses before you promise coverage to a buyer.
Try it yourself
Click through it at your own pace, or open it full screen.
Quick check
Do I get an SBOM without any flags?
No. Minimal provenance is on by default, but the SBOM must be enabled with the sbom option.
Why did my build fail after enabling attestations?
You may be on the docker driver without the containerd image store. Switch builders or enable that store, then retry.
Safeguard
Safeguard does SBOM and dependency scanning, and its policies and gates can run in CI so a bad image does not reach production. You can try a free scan before deciding anything.
Sources
Last reviewed: 19 October 2026.
