diff --git a/docs/_data/main-nav.yaml b/docs/_data/main-nav.yaml index 08e877f..1910b91 100644 --- 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 index 8996ac4..81dacc5 100644 --- 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 new file mode 100644 index 0000000..7dd7a6e --- /dev/null +++ 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 new file mode 100644 index 0000000..75bde99 --- /dev/null +++ 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 | +|---|---|---| +| `` | GitHub repository | `insomnia` | +| `version` | Artifact version to download | `9.3.0-beta.4` | +| `` | Single / Space separated isno binary files | `inso-*-9.3.0-beta.4.{pkg,tar.xz,zip}` | +| `` | 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 '' \ + --source-uri 'github.com/Kong/' \ + +``` + +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 '' \ + --source-uri 'github.com/Kong/' \ + --build-workflow-input 'version=9.3.0-beta.4' \ + +``` + +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 new file mode 100644 index 0000000..d3ba034 --- /dev/null +++ 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 | +|---|---|---| +| `` | GitHub repository | `insomnia` | +| `` | GitHub workflow name | `Release Publish` | +| `` | Github workflow trigger name | `workflow_dispatch` | +| `` | 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 `` for the image using `regctl`. + + ```sh + regctl manifest digest : + ``` + +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 \ + :@sha256: \ + --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 \ + :@sha256: \ + --print-provenance \ + --provenance-repository kong/notary \ + --source-uri 'github.com/Kong/' +``` + +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 \ + :@sha256: \ + --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/' \ + --certificate-github-workflow-name='' \ + --certificate-github-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 \ + :@sha256: \ + --print-provenance \ + --provenance-repository kong/notary \ + --build-workflow-input 'version=9.3.0-beta.4' \ + --source-uri 'github.com/Kong/' +``` + +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 new file mode 100644 index 0000000..d0b977f --- /dev/null +++ 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_-*.spdx.json` and `image_-*.cyclonedx.json` diff --git a/docs/inso-cli/verify-signed-images.md b/docs/inso-cli/verify-signed-images.md new file mode 100644 index 0000000..5063c4c --- /dev/null +++ b/docs/inso-cli/verify-signed-images.md @@ -0,0 +1,86 @@ +--- +layout: article-detail +title: Verify Signatures for Signed Inso CLI Images +category: "Inso CLI" +category-url: inso-cli +--- + +Inso CLI 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 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 Docker image details, a GitHub repo name, and a GitHub workflow filename. + +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 | +|---|---|---| +| `` | Github repository | `insomnia` | +| `` | Github workflow filename | `release-publish.yml` | +| `` | Github workflow name | `Release Publish` | + +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. + +## Examples + +### Prerequisites + +For both examples, you need to: + +1. Ensure `cosign` is installed. + +2. Collect the necessary image details. + +3. Set the `COSIGN_REPOSITORY` environment variable: + + ```sh + export COSIGN_REPOSITORY=kong/notary + ``` + +{:.important .no-icon} +> Github owner is case-sensitive (`Kong/insomnia` vs `kong/insomnia`). + +### Minimal example + +Run the `cosign verify ...` command: + +```sh +cosign verify \ + kong/:@sha256: \ + --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \ + --certificate-identity-regexp='https://github.com/Kong//.github/workflows/' +``` + +Here's the same example using sample values instead of placeholders: + +```sh +cosign verify \ + 'kong/inso:9.3.0-beta.4@sha256:e1fd25efe702d5e2095f5595f8b452f50b65aa8e8e1209863fbef3f241d364c8' \ + --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \ + --certificate-identity-regexp='https://github.com/Kong/insomnia/.github/workflows/release-publish.yml' +``` + +### Complete example + +```sh +cosign verify \ + :@sha256: \ + --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \ + --certificate-identity-regexp='https://github.com/Kong//.github/workflows/' \ + -a repo='Kong/' \ + -a workflow='' +``` + +Here's the same example using sample values instead of placeholders: + +```sh +cosign verify \ + 'kong/inso:9.3.0-beta.4@sha256:e1fd25efe702d5e2095f5595f8b452f50b65aa8e8e1209863fbef3f241d364c8' \ + --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \ + --certificate-identity-regexp='https://github.com/Kong/insomnia/.github/workflows/release-publish.yml' \ + -a repo='Kong/insomnia' \ + -a workflow='Release Publish' +``` diff --git a/docs/insomnia/sbom.md b/docs/insomnia/sbom.md new file mode 100644 index 0000000..7f586ed --- /dev/null +++ b/docs/insomnia/sbom.md @@ -0,0 +1,14 @@ +--- +layout: article-detail +title: Software Bill of Materials +category: "Insomnia SBOM" +category-url: security +--- + +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. + +## Download SBOM + +1. Navigate to Insomnia [GitHub Releases](https://updates.insomnia.rest/downloads/release/latest?app=com.insomnia.app&channel=beta) + +2. Download the `sbom.spdx.json` and `sbom.cyclonedx.json` SBOM files for Insomnia App diff --git a/docs/insomnia/verify-binary-provenance.md b/docs/insomnia/verify-binary-provenance.md new file mode 100644 index 0000000..7892a71 --- /dev/null +++ b/docs/insomnia/verify-binary-provenance.md @@ -0,0 +1,98 @@ +--- +layout: article-detail +title: Verifying Build Provenance for Signed Insomnia Binaries +category: "Verifying Build Provenance for Signed Insomnia Binaries" +category-url: security +--- + +Kong produces build provenance for Insomnia Application binary artifacts, which can be verified using `cosign` / `slsa-verifier`. + +This guide provides steps to verify build provenance for signed Insomnia Application 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 | +|---|---|---| +| `` | GitHub repository | `insomnia` | +| `version` | Artifact version to download | `9.3.0-beta.4` | +| `` | Single / Space separated isnomnia binary files | `Insomnia.Core-9.3.0-beta.4.{snap,tar.gz,zip,rpm,dmg,deb,exe,AppImage}` | +| `` | 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 Insomnia Core Application Binaries](https://updates.insomnia.rest/downloads/release/latest?app=com.insomnia.core&channel=beta) with file pattern `Insomnia.Core-.{snap,tar.gz,zip,rpm,dmg,deb,exe,AppImage}` + +3. [Download Insomnia Binary Provenance Attestation](https://updates.insomnia.rest/downloads/release/latest?app=com.insomnia.core&channel=beta) with pattern `insomnia-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 '' \ + --source-uri 'github.com/Kong/' \ + +``` + +Here's the same example using sample values instead of placeholders: + +```sh +slsa-verifier verify-artifact \ + --print-provenance \ + --provenance-path 'insomnia-provenance.intoto.jsonl' \ + --source-uri 'github.com/Kong/insomnia' \ + Insomnia.Core-9.3.0-beta.4.{snap,tar.gz,zip,rpm,dmg,deb,AppImage,exe} +``` + +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 '' \ + --source-uri 'github.com/Kong/' \ + --build-workflow-input 'version=9.3.0-beta.4' \ + +``` + +Here's the same example using sample values instead of placeholders: + +```sh +slsa-verifier verify-artifact \ + --print-provenance \ + --provenance-path 'insomnia-provenance.intoto.jsonl' \ + --source-uri 'github.com/Kong/insomnia' \ + --build-workflow-input 'version=9.3.0-beta.4' \ + Insomnia.Core-9.3.0-beta.4.{snap,tar.gz,zip,rpm,dmg,deb,AppImage,exe} +```