From f2f82e0e8c6eb553ef934415b49d678d666b621e Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 5 Sep 2023 11:46:57 +0200 Subject: [PATCH] scout: view, generate, export sbom Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/build/attestations/_index.md | 2 +- content/build/attestations/sbom.md | 8 +- content/scout/sbom.md | 108 +++++++++++++++++++++++++++ data/toc.yaml | 2 + 4 files changed, 118 insertions(+), 2 deletions(-) create mode 100644 content/scout/sbom.md diff --git a/content/build/attestations/_index.md b/content/build/attestations/_index.md index 08351ec19f..60cd5196e8 100644 --- a/content/build/attestations/_index.md +++ b/content/build/attestations/_index.md @@ -158,4 +158,4 @@ To deep-dive into the specifics about how attestations are stored, see Learn more about the available attestation types and how to use them: - [Provenance](slsa-provenance.md) -- [SBOM](sbom.md) \ No newline at end of file +- [SBOM](sbom.md) diff --git a/content/build/attestations/sbom.md b/content/build/attestations/sbom.md index f53463491c..ee7cbfafd9 100644 --- a/content/build/attestations/sbom.md +++ b/content/build/attestations/sbom.md @@ -221,6 +221,12 @@ an image that implements the $ docker buildx build --attest type=sbom,generator= . ``` +> **Tip** +> +> The Docker Scout SBOM generator is available. See +> [../../scout/sbom.md#attest]. +{ .tip } + ## SBOM attestation example The following JSON example shows what an SBOM attestation might look like. @@ -324,4 +330,4 @@ The following JSON example shows what an SBOM attestation might look like. "spdxVersion": "SPDX-2.2" } } -``` \ No newline at end of file +``` diff --git a/content/scout/sbom.md b/content/scout/sbom.md new file mode 100644 index 0000000000..10453fb946 --- /dev/null +++ b/content/scout/sbom.md @@ -0,0 +1,108 @@ +--- +title: Docker Scout SBOMs +description: Use Docker Scout to extract the SBOM for your project. +keywords: scout, supply chain, sbom, software bill of material, spdx +--- + +As part of [image analysis](./image-analysis.md), Docker Scout generates a +Software Bill of Material (SBOM) for your project. The SBOM uses the Software +Package Data Exchange (SPDX) format. + +## View from CLI + +To view the contents of the SBOM that Docker Scout generates, you can use the +`docker scout sbom` command. + +```console +$ docker scout sbom [IMAGE] +``` + +By default, this prints the SBOM in a JSON format to stdout. + +> **Note** +> +> The JSON format produced by `docker scout sbom` is not SPDX-JSON. To generate +> SPDX, use the SBOM generator plugin for BuildKit, see [Attach the SBOM as a +> build attestation](#attest). + +Use the `--format list` flag to generate a human-readable output. + +```console +$ docker scout sbom --format list alpine + + Name Version Type +─────────────────────────────────────────────── + alpine-baselayout 3.4.3-r1 apk + alpine-baselayout-data 3.4.3-r1 apk + alpine-keys 2.4-r1 apk + apk-tools 2.14.0-r2 apk + busybox 1.36.1-r2 apk + busybox-binsh 1.36.1-r2 apk + ca-certificates 20230506-r0 apk + ca-certificates-bundle 20230506-r0 apk + libc-dev 0.7.2-r5 apk + libc-utils 0.7.2-r5 apk + libcrypto3 3.1.2-r0 apk + libssl3 3.1.2-r0 apk + musl 1.2.4-r1 apk + musl-utils 1.2.4-r1 apk + openssl 3.1.2-r0 apk + pax-utils 1.3.7-r1 apk + scanelf 1.3.7-r1 apk + ssl_client 1.36.1-r2 apk + zlib 1.2.13-r1 apk +``` + +For more information about the `docker scout sbom` command, refer to the [CLI +reference](../engine/reference/commandline/scout_sbom.md). + +## Attach as build attestation {#attest} + +You can generate the SBOM and attach it to the image at build-time as an +[attestation](../build/attestations/_index.md). BuildKit provides a default +SBOM generator which is different from what Docker Scout uses. You can swap out +the default generator and replace it with the Docker Scout SBOM generator, +which creates richer results and ensures better compatibility with the Docker +Scout image analysis. + +```console +$ docker build --tag / \ + --attest type=sbom,generator=docker/scout-sbom-indexer:latest \ + --push . +``` + +> **Note** +> +> The default, non-containerd image store doesn't currently support images with +> attestations. To build images with SBOM attestations, you can either turn on +> the [containerd image store](../desktop/containerd/_index.md) feature, or use +> a `docker-container` builder together with the `--push` flag to push the +> image (with attestations) directly to a registry. + +## Extract to file + +The command for extracting the SBOM of an image to an SDPX JSON file is +different depending on whether the image has been pushed to a registry or if +it's a local image. + +### Remote image + +To extract the SBOM of an image and save it to a file, you can use the `docker +buildx imagetools inspect` command. This command only works for images in a +registry. + +```console +$ docker buildx imagetools inspect --format "{{ json .SBOM }}" > sbom.spdx.json +``` + +### Local image + +To extract the SDPX file for a local image, build the image with the `local` +exporter and use the `scout-sbom-indexer` SBOM generator plugin. + +The following command saves the SBOM to a file at `build/sbom.spdx.json`. + +```console +$ docker build --attest type=sbom,generator=docker/scout-sbom-indexer:latest \ + --output build . +``` diff --git a/data/toc.yaml b/data/toc.yaml index 8e687dff36..52a81909be 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1925,6 +1925,8 @@ Manuals: title: Data handling - path: /scout/policy/ title: Policy + - path: /scout/sbom/ + title: SBOM - sectiontitle: Integrations section: - title: Overview