From 04374b03cc4b61e8529f0b864cd5a26ac7cfd83c Mon Sep 17 00:00:00 2001
From: Martijn Pieters <mj@zopatista.com>
Date: Tue, 4 Feb 2025 21:38:19 +0000
Subject: [PATCH] Docs on how to verify uv docker image attestations (#11140)

As [requested by
@zanieb](https://github.com/astral-sh/uv/pull/8685#issuecomment-2627556992).
---
 docs/guides/integration/docker.md | 56 +++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/docs/guides/integration/docker.md b/docs/guides/integration/docker.md
index f7fd46777..f87ad3774 100644
--- a/docs/guides/integration/docker.md
+++ b/docs/guides/integration/docker.md
@@ -500,3 +500,59 @@ RUN uv pip install -r pyproject.toml
 COPY . .
 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/):
+
+```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 1 attestation from GitHub API
+
+The following policy criteria will be enforced:
+- OIDC Issuer must match:................... https://token.actions.githubusercontent.com
+- Source Repository Owner URI must match:... https://github.com/astral-sh
+- Predicate type must match:................ https://slsa.dev/provenance/v1
+- Subject Alternative Name must match regex: (?i)^https://github.com/astral-sh/
+
+✓ Verification succeeded!
+
+sha256:5adf09a5a526f380237408032a9308000d14d5947eafa687ad6c6a2476787b4f was attested by:
+REPO          PREDICATE_TYPE                  WORKFLOW
+astral-sh/uv  https://slsa.dev/provenance/v1  .github/workflows/build-docker.yml@refs/heads/main
+```
+
+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.27@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`:
+
+```console
+$ REPO=astral-sh/uv
+$ gh attestation download --repo $REPO oci://ghcr.io/${REPO}:latest
+Wrote attestations to file sha256:5adf09a5a526f380237408032a9308000d14d5947eafa687ad6c6a2476787b4f.jsonl.
+Any previous content has been overwritten
+
+The trusted metadata is now available at sha256:5adf09a5a526f380237408032a9308000d14d5947eafa687ad6c6a2476787b4f.jsonl
+$ docker buildx imagetools inspect ghcr.io/${REPO}:latest --format "{{json .Manifest}}" > manifest.json
+$ cosign verify-blob-attestation \
+    --new-bundle-format \
+    --bundle "$(jq -r .digest manifest.json).jsonl"  \
+    --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
+    --certificate-identity-regexp="^https://github\.com/${REPO}/.*" \
+    <(jq -j '.|del(.digest,.size)' manifest.json)
+Verified OK
+```