Skip to content

Commit

Permalink
feat: how to verify container image and attestation files.
Browse files Browse the repository at this point in the history 
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 <[email protected]>
  • Loading branch information
@jvanz
jvanz committed Oct 11, 2024
1 parent b022ab0 commit f03fe8f
Showing 1 changed file with 87 additions and 27 deletions.
114 changes: 87 additions & 27 deletions docs/tutorials/verifying-kubewarden.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
<snipped json>
```

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
Expand Down Expand Up @@ -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.
Expand All @@ -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
<snipped json>
```
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
Expand Down

0 comments on commit f03fe8f

Please sign in to comment.