Skip to content

Commit f074883

Browse files
willdollmanwilldollman
authored
Add documentation for verifying container signatures (#931)
Add documentation for verifying container signatures using `src signature verify`, as introduced in sourcegraph/src-cli#1143. Also update SBOM documentation to align with the signature verification docs. - https://sourcegraph-docs-git-will-container-6ad7d6-sourcegraph-f8c71130.vercel.app/docs/cli/how-tos/verify_container_signatures - https://sourcegraph-docs-git-will-container-6ad7d6-sourcegraph-f8c71130.vercel.app/docs/cli/how-tos/fetch_sboms ## Pull Request approval You will need to get your PR approved by at least one member of the Sourcegraph team. For reviews of docs formatting, styles, and component usage, please tag the docs team via the #docs Slack channel.
1 parent 7846272 commit f074883

File tree

3 files changed

+67
-11
lines changed

3 files changed

+67
-11
lines changed

‎docs/cli/how-tos/fetch_sboms.mdx

+21-11
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,26 @@
11
# How to fetch SBOMs for Sourcegraph
22

3-
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.
3+
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.
44

5-
To retrieve the SBOMs for a specific release, you can use the `src` command line interface for Sourcegraph:
5+
Use the Sourcegraph CLI (`src`) to fetch SBOMs for a specific release.
66

7-
1. Install `src` by following the [Quickstart](../quickstart.mdx).
8-
2. Install `cosign` by following the [Installation Guide](https://docs.sigstore.dev/cosign/system_config/installation/).
9-
3. Identify the version of Sourcegraph your require SBOMs for. This may be a [recent release](../../CHANGELOG.mdx), or your instance's current version.
10-
1. SBOMs are only available for Sourcegraph release 5.9.0 and later.
11-
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.
12-
![](https://storage.googleapis.com/sourcegraph-assets/docs/images/settings/view-version-scaled.png)
13-
4. Run `src sbom fetch -v <version>` to fetch SBOMs for all containers in this release. `src` will automatically validate that all SBOMs were signed by Sourcegraph.
7+
## Prerequisites
8+
9+
1. Install `src` following the [Quickstart](../quickstart.mdx).
10+
11+
2. Install `cosign` following the [Installation Guide](https://docs.sigstore.dev/cosign/system_config/installation/).
12+
13+
## Fetching SBOMs
14+
15+
1. Determine the Sourcegraph version to verify. Use either a [recent release](../../CHANGELOG.mdx) or your instance's current version.
16+
17+
> **Note:** SBOMs are only available only for Sourcegraph release 5.9.0 and later.
18+
19+
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).
20+
21+
![Version location in settings](https://storage.googleapis.com/sourcegraph-assets/docs/images/settings/view-version-scaled.png)
22+
23+
2. Run `src sbom fetch -v <version>` to fetch SBOMs for all containers in this release. `src` will automatically validate that all SBOMs were signed by Sourcegraph.
1424
```
1525
# Fetch SBOMs for Sourcegraph release 5.9.0
1626
$ 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
2939
3040
Your Sourcegraph deployment may not use all of these images. Please check your deployment to confirm which images are used.
3141
```
32-
5. Once completed, you can find the set of validated SBOMs under `sourcegraph-sboms/sourcegraph-<version>/`.
42+
3. Once completed, find the set of validated SBOMs under `sourcegraph-sboms/sourcegraph-<version>/`.
3343

34-
**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.
44+
**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.

‎docs/cli/how-tos/index.mdx

+1
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,5 @@ The following how-tos apply to the `src` command line interface to Sourcegraph:
66
- [Revoking an access token](/cli/how-tos/revoking_an_access_token)
77
- [Managing access tokens](/cli/how-tos/managing_access_tokens)
88
- [How to fetch SBOMs for Sourcegraph](/cli/how-tos/fetch_sboms)
9+
- [How to verify container signatures for Sourcegraph releases](/cli/how-tos/verify_container_signatures)
910

‎docs/cli/how-tos/verify_container_signatures.mdx

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# How to verify container signatures for Sourcegraph releases
2+
3+
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.
4+
5+
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.
6+
7+
## Prerequisites
8+
9+
1. Install `src` following the [Quickstart](../quickstart.mdx).
10+
11+
2. Install `cosign` following the [Installation Guide](https://docs.sigstore.dev/cosign/system_config/installation/).
12+
13+
## Verification Process
14+
15+
1. Determine the Sourcegraph version to verify. Use either a [recent release](../../CHANGELOG.mdx) or your instance's current version.
16+
17+
> **Note:** Signature verification is available only for Sourcegraph release 5.11.4013 and later.
18+
19+
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).
20+
21+
![Version location in settings](https://storage.googleapis.com/sourcegraph-assets/docs/images/settings/view-version-scaled.png)
22+
23+
2. Run the verification command:
24+
25+
```bash:terminal
26+
# Verify signatures for Sourcegraph release 5.11.6271
27+
$ src signature verify -v 5.11.6271 -d sourcegraph-digests/
28+
29+
Verifying signatures for all 40 images in the Sourcegraph 5.11.6271 release...
30+
31+
✅ sourcegraph/batcheshelper@sha256:f77538c3ff985abd5fdb1cc1eb7068418cb84e0d0df629d353bdf0910e232e86
32+
✅ sourcegraph/bundled-executor@sha256:5ba1d2c4a3df2620532400de736df81d52d7b07deb07ca26832edbe78f566cfd
33+
✅ sourcegraph/cody-gateway@sha256:bfeeb0d2bb45543553dc950678da5ed6de052a85cd25a6b3b0b5690e425ee57c
34+
35+
[...]
36+
37+
🟢 Verified signatures and digests for 40 images
38+
39+
Verified digests have been written to 'sourcegraph-digests/sourcegraph-5.11.6271/verified-digests.txt'.
40+
41+
Your Sourcegraph deployment may not use all of these images. Please check your deployment to confirm which images are used.
42+
```
43+
3. After verification completes, find the validated image digests in `sourcegraph-digests/sourcegraph-<version>/`.
44+
45+
**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.

0 commit comments

Comments
 (0)