Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: container image signature and attestation verification #461

Merged
merged 2 commits into from
Oct 18, 2024
Merged

feat: container image signature and attestation verification #461

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f03fe8f
feat: how to verify container image and attestation files.
jvanz Oct 11, 2024
d456fd4
Update docs/tutorials/verifying-kubewarden.md
viccuad Oct 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 87 additions & 27 deletions docs/tutorials/verifying-kubewarden.md
View file
Open in desktop
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. 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
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
Loading