diff --git a/docs/guides/integration/docker.md b/docs/guides/integration/docker.md index dbbbb118dc04..08e2d4f18d14 100644 --- a/docs/guides/integration/docker.md +++ b/docs/guides/integration/docker.md @@ -503,13 +503,15 @@ RUN uv pip install -e . ## Verifying image provenance -The docker images are signed during the build process to provide proof of their origin, and you can -verify these attestations that a given image was produced by the uv project with the -[GitHub cli tool `gh`](https://cli.github.com/): +The Docker images are signed during the build process to provide proof of their origin. These +attestations can be used to verify that an image was produced from an official channel. + +For example, you can verify the attestations with the +[GitHub CLI tool `gh`](https://cli.github.com/): ```console $ gh attestation verify --owner astral-sh oci://ghcr.io/astral-sh/uv:latest -Loaded digest sha256:5adf09a5a526f380237408032a9308000d14d5947eafa687ad6c6a2476787b4f for oci://ghcr.io/astral-sh/uv:latest +Loaded digest sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx for oci://ghcr.io/astral-sh/uv:latest Loaded 1 attestation from GitHub API The following policy criteria will be enforced: @@ -520,7 +522,7 @@ The following policy criteria will be enforced: ✓ Verification succeeded! -sha256:5adf09a5a526f380237408032a9308000d14d5947eafa687ad6c6a2476787b4f was attested by: +sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx was attested by: REPO PREDICATE_TYPE WORKFLOW astral-sh/uv https://slsa.dev/provenance/v1 .github/workflows/build-docker.yml@refs/heads/main ``` @@ -528,14 +530,6 @@ astral-sh/uv https://slsa.dev/provenance/v1 .github/workflows/build-docker.yml This tells you that the specific Docker image was built by the official uv Github release workflow and hasn't been tampered with since. -!!! tip - - Attestations are provided for both the ditroless main image, and for the derived images. - - You probably want to verify the attestation for a specific version tag, rather than `:latest`, - or even the specific image digest, such as - `ghcr.io/astral-sh/uv:0.5.28@sha256:5adf09a5a526f380237408032a9308000d14d5947eafa687ad6c6a2476787b4f`. - GitHub attestations build on the [sigstore.dev infrastructure](https://www.sigstore.dev/). As such you can also use the [`cosign` command](https://github.com/sigstore/cosign) to verify the attestation blob against the (multi-platform) manifest for `uv`: @@ -543,10 +537,10 @@ attestation blob against the (multi-platform) manifest for `uv`: ```console $ REPO=astral-sh/uv $ gh attestation download --repo $REPO oci://ghcr.io/${REPO}:latest -Wrote attestations to file sha256:5adf09a5a526f380237408032a9308000d14d5947eafa687ad6c6a2476787b4f.jsonl. +Wrote attestations to file sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.jsonl. Any previous content has been overwritten -The trusted metadata is now available at sha256:5adf09a5a526f380237408032a9308000d14d5947eafa687ad6c6a2476787b4f.jsonl +The trusted metadata is now available at sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.jsonl $ docker buildx imagetools inspect ghcr.io/${REPO}:latest --format "{{json .Manifest}}" > manifest.json $ cosign verify-blob-attestation \ --new-bundle-format \ @@ -556,3 +550,9 @@ $ cosign verify-blob-attestation \ <(jq -j '.|del(.digest,.size)' manifest.json) Verified OK ``` + +!!! tip + + These examples use `latest`, but best practice is to verify the attestation for a specific + version tag, e.g., `ghcr.io/astral-sh/uv:0.5.28`, or (even better) the specific image digest, + such as `ghcr.io/astral-sh/uv:0.5.27@sha256:5adf09a5a526f380237408032a9308000d14d5947eafa687ad6c6a2476787b4f`.