Using `docker buildx imagetools inspect`, how do you read an image's provenance and SBOM attestations?

### Why a separate command exists `docker image inspect` reads the local image store and reports the image **config**: entrypoint, environment, labels, layer digests. Attestations are not in the config and not in a layer — they are sibling manifests in the index — so that command structurally cannot show them, and neither can `docker history`. `docker buildx imagetools inspect` is the registry-facing tool: it resolves a reference over the distribution API and can walk the whole index without pulling the image at all. That distinction matters in practice, because the machine asking the question is often a CI runner or a laptop that has no business downloading a 400 MB PHP-FPM image just to read a build record. ### The three useful forms **1. The shape of what was pushed.** ```bash docker buildx imagetools inspect \ registry.example.com/billing/invoice-worker:2.7.3 --raw ``` This prints the index JSON verbatim. You are looking for entries with `"platform": {"os": "unknown", "architecture": "unknown"}` and the annotations `vnd.docker.reference.type: attestation-manifest` plus `vnd.docker.reference.digest`, which names the platform manifest each attestation describes. If those entries are absent, the build did not attach anything — or attached it and then lost it on the way to the registry. **2. The provenance record.** ```bash docker buildx imagetools inspect \ registry.example.com/billing/invoice-worker:2.7.3 \ --format '{{ json .Provenance }}' ``` The `--format` flag takes a Go template. Buildx fetches the attestation blob, unwraps the in-toto envelope and hands you the decoded predicate, so you can read build timestamps, the builder that ran it, the source context, and — if the build used `mode=max` — the full build definition and the build arguments. `{{ json .SBOM }}` does the same for the component inventory, and `{{ json . }}` dumps everything the command knows about the reference, including `.Manifest` and `.Image`. **3. One platform at a time.** For a multi-platform image there is one attestation set per platform, and `.Provenance` is therefore a map keyed by platform string. Ask for the one you deploy: ```bash docker buildx imagetools inspect "$IMAGE" \ --format '{{ json (index .Provenance "linux/arm64") }}' ``` Getting this wrong is the usual first stumble — people print `.Provenance` on a two-platform image, see a JSON object keyed by something that is not the predicate they expected, and conclude the attestation is malformed. ### Pin the reference you inspect Inspect by digest, not by tag, whenever the answer is going to be used for anything. A tag can be re-pointed between the moment you read the record and the moment the invoice-rendering worker is deployed, and then you have read a build record for bytes nobody is running: ```bash docker buildx imagetools inspect \ registry.example.com/billing/invoice-worker@sha256:4c91a7e0d5b3... \ --format '{{ json .Provenance }}' ``` ### Reading is not verifying This is the point an interviewer is usually probing. `imagetools inspect` performs no cryptographic check on what it prints. It fetches a blob the registry served and decodes it. If the attestation is unsigned — which is what a plain `docker buildx build --push` produces — then anyone who can push to that repository can replace the index with one whose provenance says whatever they like, and this command will faithfully print the lie. Treat the output as *what the artefact claims about itself*, useful for answering questions and for feeding a check, and keep the question of who signs and who enforces separate from the question of how you read it. ### Practical uses that justify learning it - **Triage after an incident.** Given only a running image digest, one command tells you which source revision and which builder produced it, without a rebuild and without guessing from tags. - **A CI assertion.** Because the output is JSON, a pipeline step can pipe it into a JSON processor and fail the job when, say, the recorded source reference is not the release branch. That is a cheap gate that costs one registry round trip. - **Debugging the attach path.** When a team believes it is producing attestations and is not, `--raw` settles it in seconds: either the extra manifests are in the index or they never arrived. - **Auditing what leaked.** After switching a build to `mode=max`, `{{ json .Provenance }}` is how you check whether a build argument you did not want published is now sitting in a public registry. ### What to remember One command, three shapes: `--raw` for structure, `{{ json .Provenance }}` and `{{ json .SBOM }}` for content, and an index into the map when the image is multi-platform. It reads from the registry, needs no pull, and proves nothing on its own.