From 5edbf355abc3b66aa02600fcbf31c32036cf0237 Mon Sep 17 00:00:00 2001
From: Evan Anderson <evan.k.anderson@gmail.com>
Date: Tue, 14 Jan 2025 06:37:01 -0800
Subject: [PATCH] Add documentation on fetching Knative supply-chain security
 attestations (#6193)

---
 config/nav.yml                              |  4 +-
 docs/reference/security/verifying-images.md | 49 +++++++++++++++++++++
 2 files changed, 52 insertions(+), 1 deletion(-)
 create mode 100644 docs/reference/security/verifying-images.md

diff --git a/config/nav.yml b/config/nav.yml
index 391dcb7e844..7c6fc0691c9 100644
--- a/config/nav.yml
+++ b/config/nav.yml
@@ -343,7 +343,9 @@ nav:
       - Eventing code samples: samples/eventing.md
     # Reference docs
     - Reference:
-      - Security: reference/security/README.md
+      - Security:
+        - Security Model and Disclosure: reference/security/README.md
+        - Verifying Knative Images: reference/security/verifying-images.md 
       - Release notes: reference/relnotes/README.md
     - Blog: /blog/
     - About:
diff --git a/docs/reference/security/verifying-images.md b/docs/reference/security/verifying-images.md
new file mode 100644
index 00000000000..5a9204a2fca
--- /dev/null
+++ b/docs/reference/security/verifying-images.md
@@ -0,0 +1,49 @@
+# Verifying Knative Images
+
+Knative publishes SBOMs and SLSA provenance documents for each image in the
+Knative release. You can also use this information to configure [the sigstore
+policy controller](https://docs.sigstore.dev/policy-controller/overview/) or
+other admission controllers to check for these image attestations.
+
+## Prerequisites
+
+You will need to install the [cosign tool](https://github.com/sigstore/cosign/tree/main)
+to fetch and interact with the attestations stored in the container registry.
+
+## Knative SLSA Provenance (signed)
+
+The Knative build process produces a SLSA [in-toto](https://in-toto.io/)
+attestation for each image in the build process. For a given image in the
+Knative release manifests, you can verify the build attestation using the
+following:
+
+```bash
+cosign verify-attestation \
+  --certificate-oidc-issuer https://accounts.google.com \
+  --certificate-identity signer@knative-releases.iam.gserviceaccount.com \
+  --type slsaprovenance02 \
+  $IMAGE
+```
+
+Note that the in-toto document is base64 encoded in the `.payload` attribute
+of the attestation; you can use `jq` to extract this with the following
+invocation:
+
+```bash
+cosign verify-attestation \
+  --certificate-oidc-issuer https://accounts.google.com \
+  --certificate-identity signer@knative-releases.iam.gserviceaccount.com \
+  --type slsaprovenance02 \
+  $IMAGE | jq -r .payload | base64 --decode | jq
+```
+
+## Knative SBOMs
+
+For each container image, Knative publishes an SBOM corresponding to each
+image. These SBOMs are produced during compilation by the
+[`ko` tool](https://ko.build/), and can be downloaded using the `cosign download sbom`
+command. Note that the image references in the Knative manifests are to
+multi-architecture images; to extract the software components for a particular
+architecture (as different architectures may build with different libraries),
+you will need to run `cosign download sbom` on the architecture-specific image
+(e.g. for `linux/amd64`).