Merge pull request #3260 from jedevc/attestations-docs

Attestations docs
moby · Dec 5, 2022 · 9624ab4 · 9624ab4
2 parents 7615120 + db5489f
commit 9624ab4
Show file tree

Hide file tree

Showing 2 changed files with 271 additions and 0 deletions.
diff --git a/docs/sbom-protocol.md b/docs/sbom-protocol.md
@@ -0,0 +1,73 @@
+# SBOM Scanning Protocol
+
+BuildKit supports automatic creation of [SBOMs](https://en.wikipedia.org/wiki/Software_supply_chain)
+for builds, attaching them as [image attestations](./attestation-storage.md).
+
+To scan the filesystem contents, a user can specify an SBOM generator image.
+When run, this image is passed the rootfs of the build stage as a read-only
+mount, writes its SBOM scan data to a specified directory.
+
+The SBOM generator image is expected to follow the rules of the BuildKit SBOM
+generator protocol, defined in this document.
+
+> **Note**
+>
+> Currently, only SBOMs in the [SPDX](https://spdx.dev) JSON format are
+> supported.
+>
+> These SBOMs will be attached to the final image as an in-toto attestation
+> with the `https://spdx.dev/Document` predicate type.
+
+## Implementations
+
+The following SBOM generator images are available:
+
+- [docker/buildkit-syft-scanner](https://github.com/docker/buildkit-syft-scanner)
+
+## Parameters
+
+A single run of a generator may specify multiple target filesystems to scan by
+passing multiple paths - the scanner should scan all of them. Each filesystem
+target has a **name**, specified by the final component of the path for that
+target. A generator may produce any number of scans for the available targets -
+though ideally it should aim to produce a single scan per target.
+
+These parameters will be passed to the generator image as environment variables
+by BuildKit:
+
+- `BUILDKIT_SCAN_DESTINATION` (required)
+
+  This variable specifies the directory where the scanner should write its
+  SBOM data. Scanners should write their SBOMs to `$BUILDKIT_SCAN_DESTINATION/<scan>.spdx.json`
+  where `<scan>` is the name of an arbitrary scan. A scanner may produce
+  multiple scans for a single target - scan names must be unique within a
+  target, but should not be considered significant by producers or consumers.
+
+- `BUILDKIT_SCAN_SOURCE` (required)
+
+  This variable specifies the main target, passing the path to the root
+  filesystem of the final build result.
+
+  The scanner should scan this filesystem, and write its SBOM scans to
+  `$BUILDKIT_SCAN_DESTINATION/<scan>.spdx.json`. If the scan name is not
+  significant the scan can be named `$(basename $BUILDKIT_SCAN_SOURCE)`.
+
+- `BUILDKIT_SCAN_SOURCE_EXTRAS` (optional)
+
+  This variable specifies additional targets, passing the path to a directory
+  of other root filesystems. If the variable is not set, is empty, or contains
+  a directory that does not exist, then no extras should be scanned.
+
+  The scanner should iterate through this directory, and write its SBOM scans
+  to `$BUILDKIT_SCAN_DESTINATION/<scan>.spdx.json`, similar to above.
+
+A scanner must not error if optional parameters are not set.
+
+The scanner should produce SBOM results for all filesystems specified in
+`BUILDKIT_SCAN_SOURCE` or `BUILDKIT_SCAN_SOURCE_EXTRAS` but must not produce
+SBOM results for any other filesystems.
+
+## Further reading
+
+See [frontend/attest/sbom.go](https://github.com/moby/buildkit/blob/master/frontend/attest/sbom.go)
+for the code that invokes the user-specified generator.
diff --git a/docs/sbom.md b/docs/sbom.md
@@ -0,0 +1,198 @@
+# SBOMs
+
+BuildKit supports automatic creation of [SBOMs](https://en.wikipedia.org/wiki/Software_supply_chain)
+to record the software components that make up the final image. These consist
+of a list of software packages and the files that they own.
+
+They also usually contain metadata about each component, such as software
+licenses, authors, and unique package identifiers which can be used for
+vulnerability scanning.
+
+All SBOMs generated by BuildKit are wrapped inside [in-toto attestations](https://github.com/in-toto/attestation)
+in the [SPDX](https://spdx.dev) JSON format. They can be generated using
+generator images that follow the [SBOM generator protocol](./sbom-protocol.md).
+
+When the final output format is a container image, these SBOMs are attached
+using the [attestation storage](./attestation-storage.md).
+
+To build an image with an attached SBOM (derived using the builtin default scanner,
+[docker/buildkit-syft-scanner](https://github.com/docker/buildkit-syft-scanner)),
+use the `attest:sbom` option:
+
+```bash
+buildctl build \
+    --frontend=dockerfile.v0 \
+    --local context=. \
+    --local dockerfile=. \
+    --opt attest:sbom=
+```
+
+You can also specify a custom SBOM generator image:
+
+```bash
+buildctl build \
+    --frontend=dockerfile.v0 \
+    --local context=. \
+    --local dockerfile=. \
+    --opt attest:sbom=generator=<registry>/<image>
+```
+
+## Dockerfile configuration
+
+By default, only the final build result is scanned - because of this, the
+resulting SBOM will not include build-time dependencies that may be installed
+in separate stages or the build context. This could cause you to miss
+vulnerabilities in those dependencies, which could impact the security of your
+final build artifacts.
+
+To include these build-time dependencies from your Dockerfile, you can set the
+build arguments `BUILDKIT_SBOM_SCAN_CONTEXT` and `BUILDKIT_SBOM_SCAN_STAGE` to
+additionally scan the build context and other build stages respectively. These
+build arguments are special values, and cannot be used for variable
+substitutions or as environment variables from within the Dockerfile, as they
+exist solely to change the behavior of the scanner.
+
+Both arguments can be set as global meta arguments (before a `FROM`) or can be
+individually set in each stage. If set globally, the value is propagated for
+each stage in the Dockerfile. They can take the following values:
+
+- `true`: enables context/stage scanning (e.g. `BUILDKIT_SBOM_SCAN_STAGE=true`)
+- `false`: disables context/stage scanning (e.g. `BUILDKIT_SBOM_SCAN_STAGE=false`)
+- `<stage-name>[,<stage-name>]`: enables context/stage scanning for all stages
+  listed in the comma-separated list of provided stages (e.g.
+  `BUILDKIT_SBOM_SCAN_STAGE=x,y` will scan stages called `x` and `y`).
+
+Scanning will *never* be enabled for a stage that is not built, even if it is
+enabled via the build arguments.
+
+For example:
+
+```dockerfile
+FROM alpine:latest as build
+# enable scanning for the intermediate build stage
+ARG BUILDKIT_SBOM_SCAN_STAGE=true
+WORKDIR /src
+COPY . .
+RUN ... # build some software
+
+FROM scratch as final
+# scan the build context only if the build is run to completion
+ARG BUILDKIT_SBOM_SCAN_CONTEXT=true
+COPY --from=build /path/to/software /path/to/software
+```
+
+You can also directly override these `ARG`s on the command line, by passing
+them as build arguments:
+
+```bash
+buildctl build \
+    --frontend=dockerfile.v0 \
+    --local context=. \
+    --local dockerfile=. \
+    --opt build-arg:BUILDKIT_SBOM_SCAN_STAGE=<value> \
+    --opt build-arg:BUILDKIT_SBOM_SCAN_CONTEXT=<value> \
+    --opt attest:sbom=
+```
+
+Scanning will only override existing `ARG` definitions in the Dockerfile, and
+so does not allow including other stages in the Dockerfile that do not declare
+`BUILDKIT_SBOM_SCAN` arguments.
+
+## Output
+
+To inspect the SBOMs that were generated, and attached to a container image,
+you can use the `docker buildx imagetools` command to explore the resulting
+image in your registry, following the format described in the [attestation storage](./attestation-storage.md).
+
+For example, for a simple Docker image based on `alpine:latest`, we might get
+the following SBOM:
+
+```json
+{
+  "_type": "https://in-toto.io/Statement/v0.1",
+  "predicateType": "https://spdx.dev/Document",
+  "subject": [
+    {
+      "name": "pkg:docker/<registry>/<image>@<tag/digest>?platform=<platform>",
+      "digest": {
+        "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862"
+      }
+    }
+  ],
+  "predicate": {
+    "SPDXID": "SPDXRef-DOCUMENT",
+    "name": "/run/src/core",
+    "spdxVersion": "SPDX-2.2",
+    "creationInfo": {
+      "created": "2022-11-09T10:12:01.338817553Z",
+      "creators": [
+        "Organization: Anchore, Inc",
+        "Tool: syft-[not provided]"
+      ],
+      "licenseListVersion": "3.18"
+    },
+    "dataLicense": "CC0-1.0",
+    "documentNamespace": "https://anchore.com/syft/dir/run/src/core-4006bb64-24b1-4a22-a18f-94efc6b90edb",
+    "files": [
+      {
+        "SPDXID": "SPDXRef-1ac501c94e2f9f81",
+        "comment": "layerID: sha256:9b18e9b68314027565b90ff6189d65942c0f7986da80df008b8431276885218e",
+        "fileName": "/bin/busybox",
+        "licenseConcluded": "NOASSERTION"
+      },
+      ...
+    ],
+    "packages": [
+      {
+        "SPDXID": "SPDXRef-980737451f148c56",
+        "description": "Size optimized toolbox of many common UNIX utilities",
+        "downloadLocation": "https://busybox.net/",
+        "externalRefs": [
+          {
+            "referenceCategory": "SECURITY",
+            "referenceLocator": "cpe:2.3:a:busybox:busybox:1.35.0-r17:*:*:*:*:*:*:*",
+            "referenceType": "cpe23Type"
+          },
+          {
+            "referenceCategory": "PACKAGE_MANAGER",
+            "referenceLocator": "pkg:alpine/busybox@1.35.0-r17?arch=aarch64&upstream=busybox&distro=alpine-3.16.2",
+            "referenceType": "purl"
+          }
+        ],
+        "filesAnalyzed": false,
+        "hasFiles": [
+          "SPDXRef-1ac501c94e2f9f81",
+          ...
+        ],
+        "licenseConcluded": "GPL-2.0-only",
+        "licenseDeclared": "GPL-2.0-only",
+        "name": "busybox",
+        "originator": "Person: Sören Tempel <soeren+alpine@soeren-tempel.net>",
+        "sourceInfo": "acquired package info from APK DB: lib/apk/db/installed",
+        "versionInfo": "1.35.0-r17"
+      },
+      ...
+    ],
+    "relationships": [
+      {
+        "relatedSpdxElement": "SPDXRef-1ac501c94e2f9f81",
+        "relationshipType": "CONTAINS",
+        "spdxElementId": "SPDXRef-980737451f148c56"
+      },
+      ...
+    ]
+  }
+}
+```
+
+The exact output will depend on the generator you use, however, generally:
+
+- The `files` key will contain a list of all files in the image.
+- The `packages` key will contain a list of all packages discovered from the
+  image.
+- The `relationships` key links together various files and packages, together
+  with metadata about how they relate to each other.
+
+Entries in the `files` and `packages` will contain a `comment` field that
+contains the `sha256` digest of the layer which introduced it if that layer is
+present in the final image.