From f03fe8f346d6494f06dbed4fa9bd61fe5f267418 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Guilherme=20Vanz?= Date: Fri, 11 Oct 2024 09:35:02 -0300 Subject: [PATCH 1/2] feat: how to verify container image and attestation files. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updates the tutorial of how to verify the signatures of the Kubewarden components adding a section about how to verify the container image signatures and their attestation files. Signed-off-by: José Guilherme Vanz --- docs/tutorials/verifying-kubewarden.md | 114 +++++++++++++++++++------ 1 file changed, 87 insertions(+), 27 deletions(-) diff --git a/docs/tutorials/verifying-kubewarden.md b/docs/tutorials/verifying-kubewarden.md index fed419b0b5..a986e3509f 100644 --- a/docs/tutorials/verifying-kubewarden.md +++ b/docs/tutorials/verifying-kubewarden.md @@ -20,6 +20,91 @@ following info, where `*` matches any following characters: - subject: `https://github.com/kubewarden/*` - x509 certificate extension for GHA, "github_workflow_repository": `kubewarden/*` +:::important +The subject used in the `--certificate-identity-regexp` cosign CLI flag in this +tutorial utilizes the `https://github.com/kubewarden/*` values to simplify the +explanation. However, this allows artifacts from repositories with the same prefix to +bypass validation. For example: `github.com/kubewarden/policy-server1`. + +If you want a more secure check, you need to use a full URL: + +``` +https://github.com/kubewarden/policy-server/.github/workflows/container-image.yml@refs/tags/v1.18.0 +``` + +Note that the URL includes the full repository path, the workflow file path, +and the version tag. If you follow this best practice, you can use the cosign +CLI flag `--certificate-identity` with the full URL. +::: + +The Kubewarden team is also making efforts to improve the secure supply chain +and to make the whole stack SLSA level 3 compliant. Therefore, the main +artifacts also include SBOM and provenance files. In the following sections, we +will show how to verify the different artifacts produced by the Kubewarden team +and how to ensure the secure supply chain of the artifacts using SBOM and +provenance files. + +## Container images + +To verify the keyless signed container images produced by the Kubewarden team, +you can use the `cosign` CLI tool. For example, to verify the +`kubewarden/policy-server` image, you can execute the following command: + +``` +cosign verify ghcr.io/kubewarden/policy-server:v1.18.0 \ + --certificate-identity-regexp 'https://github.com/kubewarden/*' \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com + +Verification for ghcr.io/kubewarden/policy-server:v1.18.0 -- +The following checks were performed on each of these signatures: + - The cosign claims were validated + - Existence of the claims in the transparency log was verified offline + - The code-signing certificate was verified using trusted certificate authority certificates + + +``` + +You can then verify that the certificate in the returned JSON contains the +correct issuer, subject, and `github_workflow_repository` extensions. + +The same applies to all other images produced by the Kubewarden team, such as +`kubewarden/kubewarden-controller` and `kubewarden/audit-scanner`. + +All container images also have SBOM and provenance files that can be used to +ensure the secure supply chain of the images. You can find attestation files on +the release page of the component or attached to the container image in the OCI +registry. + +We use Docker to build the images and their attestations. Therefore, the cosign +command [does not yet support](https://github.com/sigstore/cosign/issues/2688) +the verification of the attestations generated by Docker from the OCI registry. +For this reason, you need to download the files from the release page or the +registry and verify them locally. If you want to download the attestation files +from the OCI registry, you can follow the [Docker +documentation](https://docs.docker.com/build/metadata/attestations/attestation-storage/) +and use tools like `crane` or `docker` itself to download the files from the +registry. + +When downloading the tarball with attestation files from the release page of +the Kubewarden components, extract them, verify the signature for the checksum +file, and then check the attestation files: + +```console +$ tar -xvf attestation-amd64.tar.gz + +$ cosign verify-blob --bundle audit-scanner-attestation-amd64-checksum-cosign.bundle \ + --certificate-oidc-issuer=https://token.actions.githubusercontent.com \ + --certificate-identity="https://github.com/kubewarden/audit-scanner/.github/workflows/attestation.yml@refs/tags/v1.18.0" \ + audit-scanner-attestation-amd64-checksum.txt +Verified OK + +$ sha256sum -c audit-scanner-attestation-amd64-checksum.txt +audit-scanner-attestation-amd64-provenance.json: OK +audit-scanner-attestation-amd64-sbom-451fac2e52226302ff449bfe053b3831fd93409b4dad24581b6121cc24daa2c2.json: OK +``` + +Now that the files integrity is verified, you can inspect the SBOM and Provenance files + ## Helm charts You can find our Helm charts in our `https://` traditional Helm repository under @@ -53,13 +138,6 @@ The following checks were performed on each of these signatures: You can then verify that the cert in the returned json contains the correct issuer, subject, and `github_workflow_repository` extensions. -### Container images & policies referenced in the charts {#container-images} - -#### Obtaining the lists - -Both the production images used in our Helm charts and our development images -(tagged `:latest`) are signed with Sigstore's keyless signing. - Kubewarden charts ship `imagelist.txt` and (`policylist.txt` when relevant) inside of the chart. Hence, if you already verified the chart, you can use those lists to verify the consumed container images and policies. @@ -84,26 +162,8 @@ ghcr.io/kubewarden/policy-server:v0.3.1 ghcr.io/kubewarden/kubectl:v1.21.4 ``` -### Verifying the lists - -Now, for each image in that list you can verify their Sigstore signatures. E.g: -``` -cosign verify ghcr.io/kubewarden/policy-server:v1.5.3 \ - --certificate-identity-regexp 'https://github.com/kubewarden/*' \ - --certificate-oidc-issuer https://token.actions.githubusercontent.com - -Verification for ghcr.io/kubewarden/policy-server:v1.5.3 -- -The following checks were performed on each of these signatures: - - The cosign claims were validated - - Existence of the claims in the transparency log was verified offline - - The code-signing certificate was verified using trusted certificate authority certificates - - -``` - -You can then verify that the cert in the returned json contains the correct -issuer, subject, and `github_workflow_repository` extensions. - +Now, for each image in that list you can verify their Sigstore signatures following the +instructions from the [previous section](#container-images). ## kwctl From d456fd465bc2979ba99fbe82784dabb143485a01 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADctor=20Cuadrado=20Juan?= <2196685+viccuad@users.noreply.github.com> Date: Fri, 18 Oct 2024 14:20:25 +0200 Subject: [PATCH 2/2] Update docs/tutorials/verifying-kubewarden.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: John Krug Signed-off-by: Víctor Cuadrado Juan <2196685+viccuad@users.noreply.github.com> --- docs/tutorials/verifying-kubewarden.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/verifying-kubewarden.md b/docs/tutorials/verifying-kubewarden.md index a986e3509f..52d44870b3 100644 --- a/docs/tutorials/verifying-kubewarden.md +++ b/docs/tutorials/verifying-kubewarden.md @@ -75,7 +75,7 @@ ensure the secure supply chain of the images. You can find attestation files on the release page of the component or attached to the container image in the OCI registry. -We use Docker to build the images and their attestations. Therefore, the cosign +We use Docker to build the images and their attestations. However, the cosign command [does not yet support](https://github.com/sigstore/cosign/issues/2688) the verification of the attestations generated by Docker from the OCI registry. For this reason, you need to download the files from the release page or the