Provenance for binaries and image artifacts (#211)

Image Signature verification for Inso docker images Software bill of materials for binaries and image artifacts Signed-off-by: saisatishkarra <[email protected]>
Kong · Jun 25, 2024 · a9cafc4 · a9cafc4
1 parent e57edd9
commit a9cafc4
Show file tree

Hide file tree

Showing 9 changed files with 520 additions and 1 deletion.
diff --git a/docs/_data/main-nav.yaml b/docs/_data/main-nav.yaml
@@ -116,6 +116,10 @@ toc:
         url: /insomnia/analytics-collected
       - title: End to End Data Encryption
         url: /insomnia/data-encryption
+      - title: Software Bill of Materials
+        url: /insomnia/sbom
+      - title: Verifying Build Provenance for Signed Insomnia Binaries
+        url: /insomnia/verify-binary-provenance
   - title: Built-In Features
     collapse-id: features
     items:
@@ -185,6 +189,17 @@ toc:
         url: /inso-cli/configuration
       - title: Inso CLI on Docker
         url: /inso-cli/inso-on-docker
+      - title: Software Bill of Materials
+        url: /inso-cli/sbom
+      - title: Verifying Signatures for Signed Inso CLI Images
+        url: /inso-cli/verify-signed-images
+      - title: Verifying Inso CLI Build Provenance
+        url: /inso-cli/provenance
+        subfolderitems:
+          - title: Verifying Build Provenance for Signed Inso CLI Images
+            url: /inso-cli/provenance/verify-image-provenance
+          - title: Verifying Build Provenance for Signed Inso CLI Binaries
+            url: /inso-cli/provenance/verify-binary-provenance
       - title: Continuous Integration
         url: /inso-cli/continuous-integration
   - title: Pre-request Script

diff --git a/docs/inso-cli/inso-on-docker.md b/docs/inso-cli/inso-on-docker.md
@@ -1,6 +1,6 @@
 ---
 layout: article-detail
-title:  Inso CLI on Docker
+title: Inso CLI on Docker
 category: "Inso CLI"
 category-url: inso-cli
 ---
@@ -15,6 +15,10 @@ docker pull kong/inso:latest
 
 All available tags can be found on Inso-CLI's [Docker Hub page](https://hub.docker.com/r/kong/inso/tags).
 
+## Verify Signed Inso CLI Docker Image signatures
+
+Inso CLI docker images are signed and attestations are published to publish dockerhub repository. Refer [Verify Signatures for Signed Inso CLI Images](/inso-cli/verify-inso-docker-image-signature).
+
 ## Run Inso CLI commands
 
 To run Insomnia specs in `kong/inso` container, mount the specs folder on your host machine to a `/var/temp` folder in the container. See the following sections for some examples.

diff --git a/docs/inso-cli/provenance.md b/docs/inso-cli/provenance.md
@@ -0,0 +1,13 @@
+---
+layout: article-detail
+title: Verify Inso CLI Build Provenance
+category: "Inso CLI"
+category-url: inso-cli
+---
+
+## Build provenance
+
+Inso CLI artifacts produces build provenance for Docker container images and binaries and can be verified using `cosign` / `slsa-verifier`.
+
+* Read the [Verify Build Provenance for Signed Inso CLI Docker Images](/inso-cli/provenance/verify-image-provenance) to learn more.
+* Read the [Verify Build Provenance for Signed Inso Binaries](/inso-cli/provenance/verify-binary-provenance) to learn more.
diff --git a/docs/inso-cli/provenance/verify-binary-provenance.md b/docs/inso-cli/provenance/verify-binary-provenance.md
@@ -0,0 +1,98 @@
+---
+layout: article-detail
+title: Verifying Build Provenance for Inso CLI Binaries
+category: "Verifying Build Provenance for Signed Inso CLI Binaries"
+category-url: inso-cli-binary-build-provenance
+---
+
+Kong produces build provenance for Inso CLI binary artifacts, which can be verified using `cosign` / `slsa-verifier`.
+
+This guide provides steps to verify build provenance for signed Inso CLI binary artifacts in two different ways:
+
+* A minimal example, used to verify an binary artifacts without leveraging any annotations
+* A complete example, leveraging optional annotations for increased trust
+
+For the minimal example, you only need a compressed binary file(s) and provenance file.
+
+For the complete example, you need the same details as the minimal example, as well as any of the optional annotations you wish to verify:
+
+| Shorthand | Description | Example Value |
+|---|---|---|
+| `<repo>` | GitHub repository | `insomnia` |
+| `version` | Artifact version to download | `9.3.0-beta.4` |
+| `<binary-files>` | Single / Space separated isno binary files | `inso-*-9.3.0-beta.4.{pkg,tar.xz,zip}` |
+| `<provenance-file>` | Binary provenance file | `inso-provenance.intoto.jsonl` |
+
+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.
+
+## Examples
+
+### Prerequisites
+
+For both examples, you need to:
+
+1. Ensure `slsa-verifier` is installed.
+
+2. [Download Inso Binaries](https://updates.insomnia.rest/downloads/release/latest?app=com.insomnia.inso&channel=beta) with file pattern `inso-*.{pkg,tar.xz,zip}`
+
+3. [Download Inso Binary Provenance Attestation](https://updates.insomnia.rest/downloads/release/latest?app=com.insomnia.inso&channel=beta) with pattern `inso-provenance.intoto.jsonl`
+
+{:.important .no-icon}
+> The GitHub owner is case-sensitive (`Kong/insomnia` vs `kong/insomnia`).
+
+### Minimal example
+
+#### Using slsa-verifier
+
+Run the `slsa-verifier verify-artifact...` command:
+
+```sh
+slsa-verifier verify-artifact \
+   --print-provenance \
+   --provenance-path '<provenance-file>' \
+   --source-uri 'github.com/Kong/<repo>' \
+   <binary-files>
+```
+
+Here's the same example using sample values instead of placeholders:
+
+```sh
+slsa-verifier verify-artifact \
+   --print-provenance \
+   --provenance-path 'inso-provenance.intoto.jsonl' \
+   --source-uri 'github.com/Kong/insomnia' \
+   inso-*-9.3.0-beta.4.{zip,tar.xz,pkg}
+```
+
+The command will print "Verified SLSA provenance" if successful:
+
+```sh
+...
+PASSED: Verified SLSA provenance
+```
+
+### Complete example
+
+#### Using slsa-verifier
+
+Run the `slsa-verifier verify-artifact ...` command:
+
+```sh
+slsa-verifier verify-artifact \
+   --print-provenance \
+   --provenance-path '<provenance-file>' \
+   --source-uri 'github.com/Kong/<repo>' \
+   --build-workflow-input 'version=9.3.0-beta.4' \
+   <binary-files>
+```
+
+Here's the same example using sample values instead of placeholders:
+
+```sh
+slsa-verifier verify-artifact \
+   --print-provenance \
+   --provenance-path 'inso-provenance.intoto.jsonl' \
+   --source-uri 'github.com/Kong/insomnia' \
+   --build-workflow-input 'version=9.3.0-beta.4' \
+   inso-*-9.3.0-beta.4.{zip,tar.xz,pkg}
+```
diff --git a/docs/inso-cli/provenance/verify-image-provenance.md b/docs/inso-cli/provenance/verify-image-provenance.md
@@ -0,0 +1,171 @@
+---
+layout: article-detail
+title: Verifying Build Provenance for Signed Inso CLI Images
+category: "Verifying Build Provenance for Signed Inso CLI Images"
+category-url: inso-cli-image-build-provenance
+---
+
+Kong produces build provenance for Inso CLI 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 Inso CLI Docker container images in two different ways:
+
+* A minimal example, used to verify an image without leveraging any annotations
+* A complete example, leveraging optional annotations for increased trust
+
+For the minimal example, you only need a Docker manifest digest and a GitHub repo name.
+
+{:.important .no-icon}
+> The Docker manifest digest is required for build provenance verification. The manifest digest can be different from the platform specific image digest for a specific distribution.
+
+For the complete example, you need the same details as the minimal example, as well as any of the optional annotations you wish to verify:
+
+| Shorthand | Description | Example Value |
+|---|---|---|
+| `<repo>` | GitHub repository | `insomnia` |
+| `<workflow name>` | GitHub workflow name | `Release Publish` |
+| `<workflow trigger>` | Github workflow trigger name | `workflow_dispatch` |
+| `<version>` | version | `9.3.0-beta.4` |
+
+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.
+
+## Examples
+
+### Prerequisites
+
+For both examples, you need to:
+
+1. Ensure `cosign` / `slsa-verifier` is installed.
+
+2. Ensure `regctl` is installed.
+
+3. Collect the necessary image details.
+
+4. Parse the `<manifest_digest>` for the image using `regctl`.
+
+   ```sh
+   regctl manifest digest <image>:<tag>
+   ```
+
+5. Set the `COSIGN_REPOSITORY` environment variable:
+
+   ```sh
+   export COSIGN_REPOSITORY=kong/notary
+   ```
+
+{:.important .no-icon}
+> The GitHub owner is case-sensitive (`Kong/insomnia` vs `kong/insomnia`).
+
+### Minimal example
+
+#### Using Cosign
+
+Run the `cosign verify-attestation ...` command:
+
+```sh
+cosign verify-attestation \
+   <image>:<tag>@sha256:<manifest_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]+$'
+```
+
+Here's the same example using sample values instead of placeholders:
+
+```sh
+cosign verify-attestation \
+   'kong/inso:9.3.0-beta.4@sha256:e1fd25efe702d5e2095f5595f8b452f50b65aa8e8e1209863fbef3f241d364c8' \
+   --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]+$'
+```
+
+The command will exit with `0` when the `cosign` verification is completed:
+
+```sh
+...
+echo $?
+0
+```
+
+#### Using slsa-verifier
+
+Run the `slsa-verifier verify-image ...` command:
+
+```sh
+slsa-verifier verify-image \
+   <image>:<tag>@sha256:<manifest_digest> \
+   --print-provenance \
+   --provenance-repository kong/notary \
+   --source-uri 'github.com/Kong/<repo>'
+```
+
+Here's the same example using sample values instead of placeholders:
+
+```sh
+slsa-verifier verify-image \
+   'kong/inso:9.3.0-beta.4@sha256:e1fd25efe702d5e2095f5595f8b452f50b65aa8e8e1209863fbef3f241d364c8' \
+   --print-provenance \
+   --provenance-repository kong/notary \
+   --source-uri 'github.com/Kong/insomnia'
+```
+
+The command will print "Verified SLSA provenance" if successful:
+
+```sh
+...
+PASSED: Verified SLSA provenance
+```
+
+### Complete example
+
+#### Using Cosign
+
+Run the `cosign verify-attestation ...` command:
+
+```sh
+cosign verify-attestation \
+   <image>:<tag>@sha256:<manifest_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/<repo>' \
+   --certificate-github-workflow-name='<workflow name>' \
+   --certificate-github-workflow-trigger='<workflow trigger>'
+```
+
+Here's the same example using sample values instead of placeholders:
+
+```sh
+cosign verify-attestation \
+   'kong/inso:9.3.0-beta.4@sha256:e1fd25efe702d5e2095f5595f8b452f50b65aa8e8e1209863fbef3f241d364c8' \
+   --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/insomnia' \
+   --certificate-github-workflow-name='Release Publish' \
+   --certificate-github-workflow-trigger='workflow_dispatch'
+```
+
+#### Using slsa-verifier
+
+Run the `slsa-verifier verify-image ...` command:
+
+```sh
+slsa-verifier verify-image \
+   <image>:<tag>@sha256:<manifest_digest> \
+   --print-provenance \
+   --provenance-repository kong/notary \
+   --build-workflow-input 'version=9.3.0-beta.4' \
+   --source-uri 'github.com/Kong/<repo>'
+```
+
+Here's the same example using sample values instead of placeholders:
+
+```sh
+slsa-verifier verify-image \
+   'kong/inso:9.3.0-beta.4@sha256:e1fd25efe702d5e2095f5595f8b452f50b65aa8e8e1209863fbef3f241d364c8' \
+   --print-provenance \
+   --provenance-repository kong/notary \
+   --build-workflow-input 'version=9.3.0-beta.4' \
+   --source-uri 'github.com/Kong/insomnia'
+```
diff --git a/docs/inso-cli/sbom.md b/docs/inso-cli/sbom.md
@@ -0,0 +1,20 @@
+---
+layout: article-detail
+title: Software Bill of Materials
+category: "Inso CLI"
+category-url: inso-cli
+---
+
+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.
+
+We are generating SBOMs for both inso binaries and docker container images.
+
+## Download SBOM
+
+1. Navigate to Insomnia [GitHub Releases](https://updates.insomnia.rest/downloads/release/latest?app=com.insomnia.inso&channel=beta)
+
+2. Download the below SBOMs as needed:
+
+* SBOMs for Inso Binaries:  `sbom.spdx.json` and `sbom.cyclonedx.json`
+* SBOMs for Inso Docker Images:
+  * Linux: `image_<image_name>-*.spdx.json` and `image_<image_name>-*.cyclonedx.json`