From 09e38db61d68349dd1533c02b6224239590c151c Mon Sep 17 00:00:00 2001 From: Will Dollman Date: Tue, 28 Jan 2025 21:46:42 +0000 Subject: [PATCH 1/3] Add signature validation howto --- .../how-tos/verify_container_signatures.mdx | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 docs/cli/how-tos/verify_container_signatures.mdx diff --git a/docs/cli/how-tos/verify_container_signatures.mdx b/docs/cli/how-tos/verify_container_signatures.mdx new file mode 100644 index 000000000..a4b68ed23 --- /dev/null +++ b/docs/cli/how-tos/verify_container_signatures.mdx @@ -0,0 +1,45 @@ +# How to verify container signatures for Sourcegraph releases + +Sourcegraph publishes cryptographic signatures for all container images included in each release. These signatures can be used to verify the authenticity and integrity of the downloaded images. + +To verify signatures for a specific release, use the Sourcegraph CLI (`src`). This tool validates that all images in the release were signed by Sourcegraph and displays the SHA256 hashes of the verified images. + +## Prerequisites + +1. Install `src` following the [Quickstart](../quickstart.mdx). + +2. Install `cosign` following the [Installation Guide](https://docs.sigstore.dev/cosign/system_config/installation/). + +## Verification Process + +1. Determine the Sourcegraph version to verify. Use either a [recent release](../../CHANGELOG.mdx) or your instance's current version. + + > **Note:** Signature verification is available only for Sourcegraph release 5.11.4013 and later. + + To find your instance's current version, check your deployment or view the Settings page on your Sourcegraph instance (version shown in bottom left corner). + + ![Version location in settings](https://storage.googleapis.com/sourcegraph-assets/docs/images/settings/view-version-scaled.png) + +2. Run the verification command: + + ```bash:terminal + # Verify signatures for Sourcegraph release 5.11.6271 + $ src signature verify -v 5.11.6271 -d sourcegraph-digests/ + + Verifying signatures for all 40 images in the Sourcegraph 5.11.6271 release... + + ✅ sourcegraph/batcheshelper@sha256:f77538c3ff985abd5fdb1cc1eb7068418cb84e0d0df629d353bdf0910e232e86 + ✅ sourcegraph/bundled-executor@sha256:5ba1d2c4a3df2620532400de736df81d52d7b07deb07ca26832edbe78f566cfd + ✅ sourcegraph/cody-gateway@sha256:bfeeb0d2bb45543553dc950678da5ed6de052a85cd25a6b3b0b5690e425ee57c + + [...] + + 🟢 Verified signatures and digests for 40 images + + Verified digests have been written to 'sourcegraph-digests/sourcegraph-5.11.6271/verified-digests.txt'. + + Your Sourcegraph deployment may not use all of these images. Please check your deployment to confirm which images are used. + ``` +3. After verification completes, find the validated image digests in `sourcegraph-digests/sourcegraph-/`. + +**Important:** The verification process checks all containers in a Sourcegraph release. Your instance typically uses only a subset of these containers. Review your deployment configuration to identify which containers are relevant to your deployment. From 3e492f2baf347391b91a6ea7cf3d4d55ea46c0e5 Mon Sep 17 00:00:00 2001 From: Will Dollman Date: Tue, 28 Jan 2025 21:46:48 +0000 Subject: [PATCH 2/3] Update index --- docs/cli/how-tos/index.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/cli/how-tos/index.mdx b/docs/cli/how-tos/index.mdx index 6c2a84d8e..0cefac94a 100644 --- a/docs/cli/how-tos/index.mdx +++ b/docs/cli/how-tos/index.mdx @@ -6,4 +6,5 @@ The following how-tos apply to the `src` command line interface to Sourcegraph: - [Revoking an access token](/cli/how-tos/revoking_an_access_token) - [Managing access tokens](/cli/how-tos/managing_access_tokens) - [How to fetch SBOMs for Sourcegraph](/cli/how-tos/fetch_sboms) +- [How to verify container signatures for Sourcegraph releases](/cli/how-tos/verify_container_signatures) From e2e156ef16e8e4a6c1d9724da5f78c264690265b Mon Sep 17 00:00:00 2001 From: Will Dollman Date: Tue, 28 Jan 2025 21:47:00 +0000 Subject: [PATCH 3/3] Update SBOM docs to align with signature verification --- docs/cli/how-tos/fetch_sboms.mdx | 32 +++++++++++++++++++++----------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/docs/cli/how-tos/fetch_sboms.mdx b/docs/cli/how-tos/fetch_sboms.mdx index d84819b2c..fd833209d 100644 --- a/docs/cli/how-tos/fetch_sboms.mdx +++ b/docs/cli/how-tos/fetch_sboms.mdx @@ -1,16 +1,26 @@ # How to fetch SBOMs for Sourcegraph -Sourcegraph publishes a Software Bill of Materials (SBOM) for each of its container images. The SBOMs for each Sourcegraph release are signed, and stored in our container registry alongside our published container images. +Sourcegraph generates and cryptographically signs a Software Bill of Materials (SBOM) for each container image in every release. These SBOMs are stored in our container registry alongside their corresponding images. -To retrieve the SBOMs for a specific release, you can use the `src` command line interface for Sourcegraph: +Use the Sourcegraph CLI (`src`) to fetch SBOMs for a specific release. -1. Install `src` by following the [Quickstart](../quickstart.mdx). -2. Install `cosign` by following the [Installation Guide](https://docs.sigstore.dev/cosign/system_config/installation/). -3. Identify the version of Sourcegraph your require SBOMs for. This may be a [recent release](../../CHANGELOG.mdx), or your instance's current version. - 1. SBOMs are only available for Sourcegraph release 5.9.0 and later. - 2. Find your instance's current version by checking your deployment, or by visiting the Settings page on your Sourcegraph instance and checking the version shown in the bottom left corner. - ![](https://storage.googleapis.com/sourcegraph-assets/docs/images/settings/view-version-scaled.png) -4. Run `src sbom fetch -v ` to fetch SBOMs for all containers in this release. `src` will automatically validate that all SBOMs were signed by Sourcegraph. +## Prerequisites + +1. Install `src` following the [Quickstart](../quickstart.mdx). + +2. Install `cosign` following the [Installation Guide](https://docs.sigstore.dev/cosign/system_config/installation/). + +## Fetching SBOMs + +1. Determine the Sourcegraph version to verify. Use either a [recent release](../../CHANGELOG.mdx) or your instance's current version. + + > **Note:** SBOMs are only available only for Sourcegraph release 5.9.0 and later. + + To find your instance's current version, check your deployment or view the Settings page on your Sourcegraph instance (version shown in bottom left corner). + + ![Version location in settings](https://storage.googleapis.com/sourcegraph-assets/docs/images/settings/view-version-scaled.png) + +2. Run `src sbom fetch -v ` to fetch SBOMs for all containers in this release. `src` will automatically validate that all SBOMs were signed by Sourcegraph. ``` # Fetch SBOMs for Sourcegraph release 5.9.0 $ src sbom fetch -v 5.9.0 @@ -29,6 +39,6 @@ To retrieve the SBOMs for a specific release, you can use the `src` command line Your Sourcegraph deployment may not use all of these images. Please check your deployment to confirm which images are used. ``` -5. Once completed, you can find the set of validated SBOMs under `sourcegraph-sboms/sourcegraph-/`. +3. Once completed, find the set of validated SBOMs under `sourcegraph-sboms/sourcegraph-/`. -**Note:** `src sbom fetch` will retrieve SBOMs for **all** containers that make up a Sourcegraph release. Your Sourcegraph instance will use only a subset of these containers - please check your deployment to determine which SBOM files are relevant to your deployment. +**Important:** `src sbom fetch` will retrieve SBOMs for **all** containers that make up a Sourcegraph release. Your Sourcegraph instance will use only a subset of these containers - please check your deployment to determine which SBOM files are relevant to your deployment.