From daa09890e8e82d3ca59c3b60a1537586b2e30804 Mon Sep 17 00:00:00 2001 From: Justin Chadwell Date: Thu, 8 Dec 2022 11:53:18 +0000 Subject: [PATCH] docs: add slsa provenance documentation Signed-off-by: Justin Chadwell --- docs/slsa.md | 314 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 314 insertions(+) create mode 100644 docs/slsa.md diff --git a/docs/slsa.md b/docs/slsa.md new file mode 100644 index 0000000000000..9b823cd8546a4 --- /dev/null +++ b/docs/slsa.md @@ -0,0 +1,314 @@ +# SLSA provenance + +BuildKit supports automatic creation of [SLSA Provenance](https://slsa.dev/provenance) +attestations to record the build process of the image, including details such +as: + +- Build timestamps +- Build parameters and environment +- Version control metadata +- Source code details +- Materials consumed during the build + +All provenance generated by BuildKit is wrapped inside [in-toto attestations](https://github.com/in-toto/attestation) +in the [SLSA Provenance format](https://slsa.dev/provenance/v0.2). + +When the final output format is a container image, provenance is attached +using the [attestation storage](./attestation-storage.md). + +To build an image with attached provenance use the `attest:provenance` option: + +```bash +buildctl build \ + --frontend=dockerfile.v0 \ + --local context=. \ + --local dockerfile=. \ + --opt attest:provenance= +``` + +You can also specify custom parameters for the provenance: + +```bash +buildctl build \ + --frontend=dockerfile.v0 \ + --local context=. \ + --local dockerfile=. \ + --opt attest:provenance=mode=min,inline-only=true +``` + +## Parameters + +| Parameter | Type | Default | Description | +| ------------- | -------------- | ---------------- | ------------------------------------------------------------------------------------------------- | +| `mode` | `min`,`max` | `max` | Configures the amount of provenance to be generated. See [mode](#mode) | +| `inline-only` | `true`,`false` | `false` | Only embed provenance into exporters that support inline content. See [inline-only](#inline-only) | + +### `mode` + +Provenance can be generated in one of two `mode`s: `min` or `max`. By default, +when provenance is enabled, the `mode` parameter will be set to `max`. + +In `min` mode, BuildKit generate only the bare minimum amount of provenance, +including: + +- Build timestamps +- The frontend used +- The inputs used + +However, the values of build-arguments, the identities of secrets, and rich +layer metadata will not be included. `mode=min` should be safe to set on all +builds, as it does not leak information from any part of the build environment. + +In `max` mode, BuildKit generates all of the above, as well as: + +- The source Dockerfile, and rich layer metadata with sourcemaps to connect the + source with the build result +- The values of passed build arguments +- Metadata about secrets and ssh mounts + +Wherever possible, you should prefer `mode=max` as it contains signifantly +more detailed information for analysis. However, on some builds it may not be +appropriate, as it includes the values of various build arguments and metadata +about secrets - these builds should be refactored to prefer passing hidden +values through secrets wherever possible, to prevent unneccessary information +leakage. + +### `inline-only` + +When generated, provenance is by included in all exporters that support +attestations. The `inline-only` parameter allows configuring this behavior, to +only include the provenance results in exporters that support inline content, +specifically only exporters that produce container images. + +Since other exporters produce attestations into separate files, in their +filesystems, you may not want to include the provenance in these cases. + +### VCS + +## Output + +To inspect the provenance that was 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 provenance for a `mode=min` build: + +```json +{ + "_type": "https://in-toto.io/Statement/v0.1", + "predicateType": "https://slsa.dev/provenance/v0.2", + "subject": [ + { + "name": "pkg:docker//@?platform=", + "digest": { + "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862" + } + } + ], + "predicate": { + "builder": { + "id": "" + }, + "buildType": "https://mobyproject.org/buildkit@v1", + "materials": [ + { + "uri": "pkg:docker/alpine@latest?platform=linux%2Famd64", + "digest": { + "sha256": "8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4" + } + } + ], + "invocation": { + "configSource": { + "entryPoint": "Dockerfile" + }, + "parameters": { + "frontend": "dockerfile.v0", + "args": {}, + "locals": [ + { + "name": "context" + }, + { + "name": "dockerfile" + } + ] + }, + "environment": { + "platform": "linux/amd64" + } + }, + "metadata": { + "buildInvocationID": "yirbp1aosi1vqjmi3z6bc75nb", + "buildStartedOn": "2022-12-08T11:48:59.466513707Z", + "buildFinishedOn": "2022-12-08T11:49:01.256820297Z", + "reproducible": false, + "completeness": { + "parameters": true, + "environment": true, + "materials": false + }, + "https://mobyproject.org/buildkit@v1#metadata": {} + } + } +} +``` + +For a similar build, but with `mode=max`: + +```json +{ + "_type": "https://in-toto.io/Statement/v0.1", + "predicateType": "https://slsa.dev/provenance/v0.2", + "subject": [ + { + "name": "pkg:docker//@?platform=", + "digest": { + "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862" + } + } + ], + "predicate": { + "builder": { + "id": "" + }, + "buildType": "https://mobyproject.org/buildkit@v1", + "materials": [ + { + "uri": "pkg:docker/alpine@latest?platform=linux%2Famd64", + "digest": { + "sha256": "8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4" + } + } + ], + "invocation": { + "configSource": { + "entryPoint": "Dockerfile" + }, + "parameters": { + "frontend": "dockerfile.v0", + "args": {}, + "locals": [ + { + "name": "context" + }, + { + "name": "dockerfile" + } + ] + }, + "environment": { + "platform": "linux/amd64" + } + }, + "buildConfig": { + "llbDefinition": [ + { + "id": "step0", + "op": { + "Op": { + "source": { + "identifier": "docker-image://docker.io/library/alpine:latest@sha256:8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4" + } + }, + "platform": { + "Architecture": "amd64", + "OS": "linux" + }, + "constraints": {} + } + }, + { + "id": "step1", + "op": { + "Op": null + }, + "inputs": [ + "step0:0" + ] + } + ] + }, + "metadata": { + "buildInvocationID": "46ue2x93k3xj5l463dektwldw", + "buildStartedOn": "2022-12-08T11:50:54.953375437Z", + "buildFinishedOn": "2022-12-08T11:50:55.447841328Z", + "reproducible": false, + "completeness": { + "parameters": true, + "environment": true, + "materials": false + }, + "https://mobyproject.org/buildkit@v1#metadata": { + "source": { + "locations": { + "step0": { + "locations": [ + { + "ranges": [ + { + "start": { + "line": 1 + }, + "end": { + "line": 1 + } + } + ] + } + ] + } + }, + "infos": [ + { + "filename": "Dockerfile", + "data": "RlJPTSBhbHBpbmU6bGF0ZXN0Cg==", + "llbDefinition": [ + { + "id": "step0", + "op": { + "Op": { + "source": { + "identifier": "local://dockerfile", + "attrs": { + "local.differ": "none", + "local.followpaths": "[\"Dockerfile\",\"Dockerfile.dockerignore\",\"dockerfile\"]", + "local.session": "q2jnwdkas0i0iu4knchd92jaz", + "local.sharedkeyhint": "dockerfile" + } + } + }, + "constraints": {} + } + }, + { + "id": "step1", + "op": { + "Op": null + }, + "inputs": [ + "step0:0" + ] + } + ] + } + ] + }, + "layers": { + "step0:0": [ + [ + { + "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip", + "digest": "sha256:c158987b05517b6f2c5913f3acef1f2182a32345a304fe357e3ace5fadcad715", + "size": 3370706 + } + ] + ] + } + } + } + } +} +```