In `docker buildx`, how do you attach an SBOM and provenance to an image, and where is that data stored?

### What an "attestation" is in this context An attestation is a JSON document that makes a claim **about** an artefact rather than being part of it. BuildKit can produce two kinds during a build: - an **SBOM attestation** — a machine-readable inventory of what a generator found inside the filesystem that the build produced; - a **provenance attestation** — a record of how the build ran: the builder's identity, start and finish timestamps, the frontend used, the source context, and (at `mode=max`) the full build definition. Both are wrapped as in-toto statements whose `subject` is the digest of the image manifest they describe, and they are stored as blobs with the media type `application/vnd.in-toto+json`. ### Turning them on ```bash docker buildx build \ --sbom=true \ --provenance=mode=max \ -t registry.example.com/billing/invoice-worker:2.7.3 \ --push . ``` `--sbom=true` and `--provenance=mode=max` are shorthands for the general form `--attest type=sbom` and `--attest type=provenance,mode=max`. The SBOM is not produced by the Dockerfile: BuildKit runs a separate generator image over the build result, and you can pin or replace it with `--sbom=generator=<image>`. On a multi-platform build (`--platform linux/amd64,linux/arm64`) you get one SBOM attestation **per** platform manifest, because each platform has a different filesystem. ### Where the data actually lands The key idea is that the pushed artefact stops being a single manifest and becomes an index. For a PHP-FPM invoice-rendering worker image built for one platform with both attestations on, the index has three entries: the real `linux/amd64` manifest, and two attestation manifests pointing back at it. ```json { "mediaType": "application/vnd.oci.image.index.v1+json", "manifests": [ { "digest": "sha256:4c91...", "platform": { "os": "linux", "architecture": "amd64" } }, { "digest": "sha256:b7e2...", "platform": { "os": "unknown", "architecture": "unknown" }, "annotations": { "vnd.docker.reference.type": "attestation-manifest", "vnd.docker.reference.digest": "sha256:4c91..." } } ] } ``` That `unknown/unknown` platform is deliberate: platform matching is how a client picks a manifest, so an entry that matches no real platform is invisible to a normal `docker pull`. Some registry web UIs display it as a stray "unknown/unknown" row, which surprises people the first time they see it. ### Why a sibling manifest and not a layer Putting the inventory into a layer would be the obvious thing to do, and it is wrong on three counts. First, layers are part of the image's identity, so the image digest would change whenever the document changed — you could no longer say "same bytes, extra metadata". Second, the document would then be shipped into every running container's filesystem; the invoice worker, capped at 128 MiB of memory and running as an unprivileged user, would carry a file it never reads and an attacker could. Third, a layer belongs to one platform manifest, so a multi-platform image could not carry one document per architecture cleanly. Keeping attestations as siblings in the index means the platform manifest's digest is byte-for-byte what it would have been without them; only the index digest differs. ### What has to be true for it to work Attestations require an image index, and the classic Docker image store cannot hold multi-manifest indexes. In practice that means one of: a `docker-container` buildx builder (`docker buildx create --use`) that pushes straight to a registry with `--push`; the OCI exporter writing a directory or tarball; or the containerd image store enabled in the engine. A build that ends with `--load` into the old image store, or an image round-tripped through `docker save`/`docker load`, does not keep them. `docker image inspect` and `docker history` will not show them either — they read the platform manifest and config, which is exactly the part attestations do not touch. ### Defaults and version behaviour Attestation support arrived with Buildx v0.10 / BuildKit v0.11. Recent Buildx versions also attach a **minimal** provenance attestation by default when a build pushes to a registry, which is why teams sometimes discover an index with an `unknown/unknown` entry they never asked for. Turn it off per build with `--provenance=false`, or globally with the environment variable `BUILDX_NO_DEFAULT_ATTESTATIONS=1`. ### What attaching does and does not buy you Attaching is not signing, and it is not verification. A plain registry push stores the attestation unsigned; anyone with push rights to that repository can overwrite the index with one carrying different claims. What you get is that the image now describes itself — what a generator saw inside it, and what the builder says it did — addressed by the same digest as the image, so an incident question like "which build produced these bytes" is answerable without a rebuild. Deciding who checks those claims, and what happens when the check fails, is a separate programme from producing them.