In `docker buildx build`, what does `--provenance=mode=max` record that `mode=min` does not?

### The same claim at two resolutions A provenance attestation answers "how did these bytes come to exist?". BuildKit lets you choose how much of the answer to publish, because the answer is written by the build and stored next to the image where anyone who can pull the image can read it. **`mode=min`** is the skeleton. It records the things that identify the build without describing its interior: the builder that ran it, the build's start and finish timestamps, the frontend in use, the source context reference — for a git-URL context, the remote and the revision that was checked out — and the subject digest of the image produced. **`mode=max`** is a superset. On top of everything above it carries the full build definition: the Dockerfile source itself, per-step metadata for the build graph, the resolved digests of the inputs the build actually consumed, and the complete set of build arguments **with their values**. ### Why `max` is not simply better The extra fidelity is genuinely useful. With `max` you can answer, months later, which base image digest a release was built on and what the Dockerfile said at the time, from the artefact alone, without trusting that a git tag still points where it did. That is exactly the question that arrives during an incident. The cost is disclosure. Build arguments are a documented, everyday way of parameterising a build, and plenty of pipelines pass things through them that should never have been there — a registry token, a package-index URL with credentials embedded, an internal hostname. With `mode=min` those values are simply absent from the record. With `mode=max` they are in a JSON blob a `docker buildx imagetools inspect` away, for anyone who can read the repository. Concretely: an invoice-rendering worker built from a PHP-FPM base takes a `--build-arg COMPOSER_AUTH` so that a private package repository will answer. Switch that pipeline from the default minimal provenance to `mode=max` and push to a repository that is readable organisation-wide, and the credential is now published — not in a layer, where a scanner or a review might have caught it, but in metadata almost nobody looks at. The defence is not "use `min`". It is to stop putting secrets in build arguments at all: ```dockerfile # syntax=docker/dockerfile:1 FROM php:8.3-fpm AS deps RUN --mount=type=secret,id=composer_auth,target=/root/.composer/auth.json \ composer install --no-dev --prefer-dist ``` A build secret mounted this way is present only for that one `RUN`, never lands in a layer, and is referenced in provenance by its id rather than its value. Once credentials are handled that way, `mode=max` becomes a much easier call. ### Size and noise `max` provenance is larger — the build definition for a multi-stage build is not small — and it is produced per platform, so a two-architecture image carries two of them. On its own this is rarely decisive; registry storage is cheap. It matters more when you multiply by thousands of builds a week with short retention windows, and when the extra index entries interact with tooling that did not expect an image reference to resolve to something with unknown-platform members. ### Choosing per pipeline A defensible position for most organisations: - **Internal images, private registry, no secrets in build args:** `mode=max`. The reconstruction value is real and the audience is bounded. - **Anything published externally or to a widely readable repository:** `mode=min` unless you have specifically audited what the build arguments contain. - **Third-party or vendor builds you consume:** you do not choose; you read what is there and note what is missing. And be explicit rather than relying on defaults. Recent Buildx versions attach `mode=min` provenance automatically when a build pushes to a registry, which means some teams have provenance they never decided to have and others have deleted it wholesale with `BUILDX_NO_DEFAULT_ATTESTATIONS=1` because an old tool choked on the index. Writing the flag into the pipeline makes the decision visible in review. ### What neither mode does Neither mode signs anything. Both write a record that the build asserts about itself, stored in the same registry as the image, writable by anyone who can push there. `mode=max` is a richer statement, not a more trustworthy one; increasing the detail of an unsigned claim does not make it harder to forge. What provenance adds over a bare signature is the *content* of the claim — which source revision, which builder, which inputs — rather than any additional assurance about who made it.