docs(mesh)[SEC-1079]: Mesh SLSA build provenance and image signatures for verification

app/_data/docs_nav_mesh_2.7.x.yml

@@ -32,6 +32,11 @@ inherit:
       url: /support-policy/
       action: insert
       index: -3
+    - path: [ Introduction ]
+      text: Software Bill of Materials
+      url: /sbom
+      action: insert
+      index: -3
     - path: [ Introduction, Release notes]
       url: /mesh/changelog
       src: /mesh/changelog
@@ -158,6 +163,8 @@ inherit:
           url: /features/access-audit
         - text: MeshGlobalRateLimit (beta)
           url: /features/meshglobalratelimit
+        - text: Verify signatures for signed Kong Mesh images
+          url: /features/signed-images
     - path: [ Reference ]
       action: modify
       icon: /assets/images/icons/documentation/icn-references-color.svg

app/_data/docs_nav_mesh_2.8.x.yml

@@ -32,6 +32,11 @@ inherit:
       url: /support-policy/
       action: insert
       index: -3
+    - path: [ Introduction ]
+      text: Software Bill of Materials
+      url: /sbom
+      action: insert
+      index: -3
     - path: [ Introduction, Release notes]
       url: /mesh/changelog
       src: /mesh/changelog
@@ -158,6 +163,14 @@ inherit:
           url: /features/access-audit
         - text: MeshGlobalRateLimit (beta)
           url: /features/meshglobalratelimit
+        - text: Verify signatures for signed Kong Mesh images
+          url: /features/signed-images
+        - text: Build provenance
+          items:
+            - text: Verify build provenance for signed Kong Mesh images
+              url: /features/provenance-verification-images
+            - text: Verify build provenance for signed Kong Mesh binaries
+              url: /features/provenance-verification-binaries
     - path: [ Reference ]
       action: modify
       icon: /assets/images/icons/documentation/icn-references-color.svg

app/_data/tables/features/mesh.yml

@@ -97,6 +97,14 @@ features:
           Allows you to store and fetch auditing logs for operations that were performed on the cluster. When used with RBAC, it allows us to have full visibility into how the system is being governed and configured by the users.
         kuma: false
         mesh: true
+      - name: Signed Images
+        tooltip: Kong Mesh container images are signed and verifiable in accordance with SLSA guidelines.
+        kuma: false
+        mesh: true
+      - name: Build Provenance
+        tooltip: Kong Mesh container images and binaries generate build level provenance and are verifiable in accordance with SLSA guidelines.
+        kuma: false
+        mesh: true
   - name: Universal Platform Distributions
     items:
       - name: Containers, Kubernetes & OpenShift

app/_src/gateway/kong-enterprise/provenance-verification.md

@@ -108,7 +108,7 @@ slsa-verifier verify-image \
    --source-uri 'github.com/Kong/kong-ee'
 ```
 
-The command will print "Verified SLASA provenance" if successful:
+The command will print "Verified SLSA provenance" if successful:
 
 ```sh
 ...

app/_src/mesh/features/index.md

@@ -57,3 +57,23 @@ See the [UBI documentation](/mesh/{{page.release}}/features/ubi-images/) for mor
 
 You can [install {{site.mesh_product_name}} on Windows](/mesh/{{page.release}}/installation/windows/).
 {% endif_version %}
+
+{% if_version gte:2.7.x %}
+
+## Docker container image signing
+
+Starting with {{site.mesh_product_name}} 2.7.4, Docker container images are signed, and can be verified using `cosign` with signatures published to a Docker Hub repository. Read the [Verify signatures for signed {{site.mesh_product_name}} images](/mesh/{{ page.release }}/features/signed-images/) documentation to learn more.
+{% endif_version %}
+
+{% if_version gte:2.8.x %}
+
+## Build provenance
+
+Starting with {{site.mesh_product_name}} 2.8.0, {{site.mesh_product_name}} produces build provenance for Docker container images and binaries and can be verified using `cosign` / `slsa-verifier`.
+
+See the following documentation to learn more:
+
+* [Verify build provenance for signed {{site.mesh_product_name}} images](/mesh/{{ page.release }}/features/provenance-verification-images/)
+
+* [Verify build provenance for signed {{site.mesh_product_name}} binaries](/mesh/{{ page.release }}/features/provenance-verification-binaries/)
+{% endif_version %}

app/_src/mesh/features/provenance-verification-binaries.md

@@ -0,0 +1,47 @@
+---
+title: Verify Build Provenance for Kong Mesh Binaries
+badge: enterprise
+---
+
+Starting with 2.8.0, {{site.mesh_product_name}} produces build provenance for binary artifacts, which can be verified using `slsa-verifier` with attestations published to a Docker Hub repository.
+
+This guide provides steps to verify build provenance for signed {{site.mesh_product_name}} binary artifacts with an example leveraging optional annotations for increased trust.
+
+Because Kong uses GitHub Actions to build and release, Kong also uses GitHub's OIDC identity to generate build provenance for binary artifacts, which is why many of these details are GitHub-related.
+
+## Prerequisites
+
+* [`slsa-verifier`](https://github.com/slsa-framework/slsa-verifier?tab=readme-ov-file#installation) is installed.
+
+* [Download security assets](https://packages.konghq.com/public/kong-mesh-binaries-release/raw/names/security-assets/versions/{{page.version}}/security-assets.tar.gz) for the required version of {{site.mesh_product_name}} binaries
+
+* Extract the downloaded `security-assets.tar.gz` to access the provenance file `kong-mesh.intoto.jsonl`
+
+   ```sh
+   tar -xvzf security-assets.tar.gz
+   ```
+
+* [Download compressed binaries](https://cloudsmith.io/~kong/repos/kong-mesh-binaries-release/packages/?q=name%3Akong-mesh-*+version%3A{{page.version}}) for the required version  of {{site.mesh_product_name}}
+
+* The GitHub owner is case-sensitive (`Kong/kong-mesh` vs `kong/kong-mesh`).
+
+## Example
+
+{% navtabs %}
+{% navtab slsa-verifier %}
+
+1. Change to directory where the `security-assets.tar.gz` and compressed binaries are downloaded
+
+2. Run the `slsa-verifier verify-artifact ...` command:
+
+   ```sh
+   slsa-verifier verify-artifact \
+      --print-provenance \
+      --provenance-path 'kong-mesh.intoto.jsonl' \
+      --source-uri 'github.com/Kong/kong-mesh' \
+      --source-tag '{{page.version}}' \
+      kong-mesh-{{page.version}}-*-*.tar.gz
+   ```
+
+{% endnavtab %}
+{% endnavtabs %}

app/_src/mesh/features/provenance-verification-images.md

@@ -0,0 +1,76 @@
+---
+title: Verify build provenance for signed Kong Mesh images
+badge: enterprise
+---
+
+Starting with 2.8.0, {{site.mesh_product_name}} produces build provenance for Docker container images, which can be verified using `cosign` / `slsa-verifier` with attestations published to a Docker Hub repository.
+
+This guide provides steps to verify build provenance for signed {{site.mesh_product_name}} Docker container images with an example to verify an image provenance leveraging any optional annotations for increased trust.
+
+Because Kong uses GitHub Actions to build and release, Kong also uses GitHub's OIDC identity to generate build provenance for container images, which is why many of these details are GitHub-related.
+
+## Prerequisites
+
+* [`Cosign`](https://docs.sigstore.dev/system_config/installation/) / [`slsa-verifier`](https://github.com/slsa-framework/slsa-verifier?tab=readme-ov-file#installation) is installed
+
+* [`regctl`](https://github.com/regclient/regclient/blob/main/docs/install.md) is installed
+
+* Collect the necessary image details.
+
+* The GitHub owner is case-sensitive (`Kong/kong-mesh` vs `kong/kong-mesh`).
+
+## Example with kong/kuma-cp
+
+{{site.mesh_product_name}} image provenance can be verified using `cosign` or `slsa-verifier`:
+
+{% navtabs %}
+{% navtab cosign %}
+
+1. Set the `COSIGN_REPOSITORY` environment variable:
+
+   ```sh
+   export COSIGN_REPOSITORY=kong/notary
+   ```
+
+2. Parse the image manifest using `regctl`:
+
+   ```sh
+   export IMAGE_DIGEST=$(regctl manifest digest kong/kuma-cp:{{page.version}})
+   ```
+
+3. Run the `cosign verify-attestation ...` command:
+
+   ```sh
+   cosign verify-attestation \
+      kong/kuma-cp:{{page.version}}@${IMAGE_DIGEST} \
+      --type='slsaprovenance' \
+      --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
+      --certificate-identity-regexp='^https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@refs/tags/v[0-9]+.[0-9]+.[0-9]+$' \
+      --certificate-github-workflow-repository='Kong/kong-mesh' \
+      --certificate-github-workflow-name='build-test-distribute' \
+      --certificate-github-workflow-trigger='push'
+   ```
+
+{% endnavtab %}
+
+{% navtab slsa-verifier %}
+
+1. Parse the image manifest using `regctl`
+
+   ```sh
+   export IMAGE_DIGEST=$(regctl manifest digest kong/kuma-cp:{{page.version}})
+   ```
+
+2. Run the `slsa-verifier verify-image ...` command:
+
+   ```sh
+   slsa-verifier verify-image \
+      kong/kuma-cp:{{page.version}}@${IMAGE_DIGEST} \
+      --print-provenance \
+      --provenance-repository 'kong/notary' \
+      --source-uri 'github.com/Kong/kong-mesh' \
+      --source-tag '{{page.version}}'
+   ```
+
+{% endnavtab %}
+{% endnavtabs %}

app/_src/mesh/features/signed-images.md

@@ -0,0 +1,47 @@
+---
+title: Verify signatures for signed Kong Mesh images
+badge: enterprise
+---
+
+Starting with {{site.mesh_product_name}} 2.7.4, Docker container images are now signed using `cosign` with signatures published to a Docker Hub repository.
+
+This guide provides steps to verify signatures for signed {{site.mesh_product_name}} Docker container images with an example used to verify an image leveraging optional annotations for increased trust.
+
+Because Kong uses GitHub Actions to build and release, Kong also uses GitHub's OIDC identity to sign images, which is why many of these details are GitHub-related.
+
+## Prerequisites
+
+* [`Cosign`](https://docs.sigstore.dev/system_config/installation/) is installed
+
+* [`regctl`](https://github.com/regclient/regclient/blob/main/docs/install.md) is installed
+
+* Collect the necessary image details.
+
+* The GitHub owner is case-sensitive (`Kong/kong-mesh` vs `kong/kong-mesh`)
+
+### Example with kong/kuma-cp
+
+The {{site.mesh_product_name}} image signature can be verified using `cosign`:
+
+1. Set the `COSIGN_REPOSITORY` environment variable:
+
+   ```sh
+   export COSIGN_REPOSITORY=kong/notary
+   ```
+
+2. Parse the image manifest using `regctl`
+
+   ```sh
+   IMAGE_DIGEST=$(regctl manifest digest kong/kuma-cp:{{page.version}})
+   ```
+
+3. Run the `cosign verify ...` command:
+
+   ```sh
+   cosign verify \
+      kong/kuma-cp:{{page.version}}@${IMAGE_DIGEST} \
+      --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
+      --certificate-identity-regexp='https://github.com/Kong/kong-mesh/.github/workflows/kuma-_build_publish.yaml' \
+      -a repo='Kong/kong-mesh' \
+      -a workflow='build-test-distribute'
+   ```

app/_src/mesh/sbom.md

@@ -0,0 +1,21 @@
+---
+title: Software Bill of Materials
+toc: false
+---
+
+A software bill of materials (SBOM) is an inventory of all software components (proprietary and open source), open source licenses, and dependencies in a given product. A software bill of materials (SBOM) provides visibility into the software supply chain and any license compliance, security, and quality risks that may exist.
+
+Starting in {{site.mesh_product_name}} 2.7.4, we are generating SBOMs for {{site.mesh_product_name}} and Docker container images.
+
+1. [Download security assets](https://packages.konghq.com/public/kong-mesh-binaries-release/raw/names/security-assets/versions/{{page.version}}/security-assets.tar.gz) for the latest version of {{site.mesh_product_name}}
+
+2. Extract the downloaded `security-assets.tar.gz`
+
+    ```sh
+    tar -xvzf security-assets.tar.gz
+    ```
+
+3. Access the below SBOMs:
+
+   * `sbom.spdx.json` and `sbom.cyclonedx.json` are the SBOM files for **binaries** built from {{site.mesh_product_name}}
+   * `image_<image_name>-*.spdx.json` and `image_<image_name>-*.cyclonedx.json` are the SBOM files for **docker container images** of {{site.mesh_product_name}}