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. 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) 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.