Skip to content

Commit bc0422f

Browse files
dervoetidervoeti
committed
docs: Document SLSA provenance attestations and SPDX SBOMs
1 parent 3a7a6de commit bc0422f

4 files changed

Lines changed: 90 additions & 1 deletion

File tree

‎modules/concepts/pages/artifact-registries/container-images.adoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,12 @@ Products are either built from source code or official artifacts are used.
2929
Beyond that, Stackable also adds plugins or extensions that are not shipped by default, to support features such as xref:operators:monitoring.adoc[] or xref:opa:index.adoc[OpenPolicyAgent] support.
3030

3131
Since Stackable release 24.3, {stackable-sboms}[SBOMs{external-link-icon}^] for all images are provided.
32+
Since release 26.7, SBOMs are available in both the CycloneDX and SPDX formats.
3233
Have a look at the xref:guides:viewing-and-verifying-sboms.adoc[] guide to learn how to use SBOMs.
3334

35+
Additionally, since release 26.7, all images carry SLSA build provenance attestations at SLSA Level 3.
36+
See the xref:guides:verifying-image-provenance.adoc[] guide for details.
37+
3438
[#multi-platform-support]
3539
== Multi-platform support
3640

‎modules/guides/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,6 @@
55
** xref:running-stackable-in-an-airgapped-environment.adoc[]
66
** xref:viewing-and-verifying-sboms.adoc[]
77
** xref:enabling-verification-of-image-signatures.adoc[]
8+
** xref:verifying-image-provenance.adoc[]
89
** xref:kubernetes-cluster-domain.adoc[]
910
** xref:deploy-operators-and-csi-drivers-separately.adoc[]

‎modules/guides/pages/verifying-image-provenance.adoc‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
= Verifying SLSA provenance of Stackable images
2+
:description: Learn how to verify the SLSA build provenance attestations of Stackable Data Platform container images using slsa-verifier.
3+
4+
Starting with SDP 26.7, all Stackable container images, both product images and operator images, are published with https://slsa.dev/[SLSA{external-link-icon}^] build provenance attestations.
5+
6+
Provenance is a signed statement describing how an artifact was built: which source repository and commit it was built from, which workflow built it, and on what infrastructure. With it, you can verify that an image you pulled from our registry was really built by Stackable's CI and it allows you to trace how it was built.
7+
8+
The provenance is generated with the https://github.com/slsa-framework/slsa-github-generator[slsa-github-generator{external-link-icon}^] container workflow, which meets the requirements of *SLSA Level 3*: the provenance is created and signed by a trusted builder that is isolated from the project's own build workflow, so a compromised build job cannot forge it. Just like our xref:guides:viewing-and-verifying-sboms.adoc[SBOM attestations] and xref:guides:enabling-verification-of-image-signatures.adoc[images], the attestation is signed keylessly via https://www.sigstore.dev/[Sigstore{external-link-icon}^] (with GitHub Actions as the OIDC identity provider) and published in our OCI registry next to the image.
9+
10+
== Verifying provenance with slsa-verifier
11+
12+
The recommended tool for verification is https://github.com/slsa-framework/slsa-verifier[slsa-verifier{external-link-icon}^]. It verifies the signature on the provenance and checks that the image was built from the source repository you expect.
13+
14+
`slsa-verifier` requires the image to be referenced by digest, not by tag. You can obtain the digest of an image with a tool like https://github.com/google/go-containerregistry/tree/main/cmd/crane[crane{external-link-icon}^]:
15+
16+
[source,bash]
17+
----
18+
crane digest oci.stackable.tech/sdp/kafka:3.9.1-stackable26.7.0
19+
----
20+
21+
Product images are built from the https://github.com/stackabletech/docker-images[docker-images{external-link-icon}^] repository:
22+
23+
[source,bash]
24+
----
25+
slsa-verifier verify-image \
26+
oci.stackable.tech/sdp/kafka@sha256:... \
27+
--source-uri github.com/stackabletech/docker-images
28+
----
29+
30+
Operator images are built from their respective operator repository:
31+
32+
[source,bash]
33+
----
34+
slsa-verifier verify-image \
35+
oci.stackable.tech/sdp/kafka-operator@sha256:... \
36+
--source-uri github.com/stackabletech/kafka-operator
37+
----
38+
39+
On success, `slsa-verifier` prints `PASSED: SLSA verification passed` and exits with code 0. It can also print the full verified provenance with `--print-provenance`, which is useful if you want to inspect the exact commit and workflow the image was built from.
40+
41+
== Verifying provenance with cosign
42+
43+
Alternatively, https://github.com/sigstore/cosign[cosign{external-link-icon}^] can verify and extract the provenance attestation. Two things to note:
44+
45+
* The certificate identity is the trusted builder workflow of the slsa-github-generator project, not a Stackable workflow, because the provenance is deliberately signed by that isolated builder.
46+
* The slsa-github-generator attaches the provenance in the legacy attestation format, so cosign 3 needs the `--new-bundle-format=false` flag to find it.
47+
48+
[source,bash]
49+
----
50+
cosign verify-attestation --type slsaprovenance \
51+
--new-bundle-format=false \
52+
--certificate-identity-regexp \
53+
'^https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@refs/tags/v.+' \
54+
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
55+
oci.stackable.tech/sdp/kafka@sha256:... \
56+
| jq '.payload' -r | base64 -d | jq '.predicate'
57+
----
58+
59+
The extracted predicate contains, among other things, the source repository and commit digest under `invocation.configSource` and the builder identity under `builder.id`. If you use cosign directly, make sure to check these fields yourself; `slsa-verifier` does this for you.

‎modules/guides/pages/viewing-and-verifying-sboms.adoc‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
= Viewing and verifying SBOMs of the Stackable Data Platform
22
:page-aliases: tutorials:viewing-and-verifying-sboms.adoc
3-
:description: Learn to view and verify SBOMs for Stackable Data Platform using the CycloneDX standards and cosign. Ensure SBOM authenticity with Policy Controller.
3+
:description: Learn to view and verify SBOMs for Stackable Data Platform using the CycloneDX and SPDX standards and cosign. Ensure SBOM authenticity with Policy Controller.
44

55
With release 24.3 of SDP, we started providing SBOMs (Software Bill of Materials) for our container images. Please note that they currently are in a draft stage and we are continually working on improving them. As a first step, we aim to provide a list of all primary (top level) components and their versions included in each container image. Our SBOMs follow the https://cyclonedx.org/[CycloneDX{external-link-icon}^] standard and are available in JSON format.
66

77
NOTE: Starting with SDP 25.7, we now embed the exact source code used to build each product directly into our images. You can find the source code in files ending with `-src.tar.gz` within the `/stackable` directory of each image.
88

9+
Starting with SDP 26.7, every image additionally carries an SBOM in the https://spdx.dev/[SPDX{external-link-icon}^] format (SPDX JSON), attested alongside the CycloneDX SBOM. The SPDX SBOM is derived from the CycloneDX SBOM, so both formats describe the same component inventory. Container images also come with xref:guides:verifying-image-provenance.adoc[SLSA build provenance] since SDP 26.7.
10+
911
You can browse through our SBOMs at https://sboms.stackable.tech/[https://sboms.stackable.tech/{external-link-icon}^].
1012

1113
You will find a simple hierarchical structure, one directory per release, containing a list of all container images included in that release. For each container image, one SBOM per version of the image is listed.
@@ -40,6 +42,29 @@ If the identity of the signer matches, you can be sure the contents of the attes
4042

4143
You can now be sure that the SBOM was attested to the container image you're interested in by a Stackable Github Action workflow, it's even possible to look at the workflow to see how exactly this happened.
4244

45+
=== Extracting the SPDX variant
46+
47+
For images from SDP 26.7 or newer, the SPDX SBOM can be verified and extracted with `--type spdxjson` (requires cosign 3).
48+
The SBOM attestations are attached to the platform-specific images rather than the multi-arch image index, so first determine the digest of the image for your platform, for example with https://github.com/google/go-containerregistry/tree/main/cmd/crane[crane{external-link-icon}^]:
49+
50+
[source,bash]
51+
----
52+
crane manifest oci.stackable.tech/sdp/airflow-operator:26.7.0 \
53+
| jq -r '.manifests[] | select(.platform.architecture=="amd64") | .digest'
54+
----
55+
56+
Then verify and extract the SPDX SBOM using that digest:
57+
58+
[source,bash]
59+
----
60+
cosign verify-attestation --type spdxjson \
61+
--certificate-identity-regexp \
62+
'^https://github.com/stackabletech/.+/.github/workflows/.+@.+' \
63+
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
64+
oci.stackable.tech/sdp/airflow-operator@sha256:... \
65+
| jq '.payload' -r | base64 -d | jq '.predicate'
66+
----
67+
4368
== Enabling automatic verification of SBOMs
4469
Similar to our xref:enabling-verification-of-image-signatures.adoc[image signature verification] guide, it's possible to enforce that only container images with SBOMs that are signed by Stackable are allowed to run in your cluster. Sigstore's https://docs.sigstore.dev/policy-controller/overview/[Policy Controller{external-link-icon}^] can be used to achieve this.
4570

0 commit comments

Comments
 (0)