From b7a4bca657e44e0bb69d0c1138fb7aaa8f431eaa Mon Sep 17 00:00:00 2001 From: Justin Chadwell Date: Thu, 8 Dec 2022 11:53:18 +0000 Subject: [PATCH 01/10] docs: add slsa provenance documentation Signed-off-by: Justin Chadwell --- docs/slsa.md | 338 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 338 insertions(+) create mode 100644 docs/slsa.md diff --git a/docs/slsa.md b/docs/slsa.md new file mode 100644 index 000000000000..2374751deeda --- /dev/null +++ b/docs/slsa.md @@ -0,0 +1,338 @@ +# 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) | +| `builder-id` | String | | Explicitly set SLSA [`builder.id`](https://slsa.dev/provenance/v0.2#builder.id) field | +| `reproducible` | `true`,`false` | `false` | Explicitly set SLSA [`metadata.reproducible`](https://slsa.dev/provenance/v0.2#metadata.reproducible) field | +| `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 + +Many BuildKit builds are started from the context of a version-controlled +source repository, such as git. If the build uses a remote git context, +BuildKit can extract the details automatically. However, if the build uses a +local context, if you want VCS detail included, you must include these details +manually. + +To include VCS details, you can set the additional frontend options +`vcs:source` and `vcs:revision`: + +```bash +buildctl build \ + --frontend=dockerfile.v0 \ + --local context=. \ + --local dockerfile=. \ + --opt attest:provenance= \ + --opt vcs:source=https://github.com/moby/buildkit \ + --opt vcs:revision=0c9b5aeb269c740650786ba77d882b0259415ec7 +``` + +These additional parameters will appear under the +`https://mobyproject.org/buildkit@v1#metadata` key in the provenance predicate. + +## 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 + } + ] + ] + } + } + } + } +} +``` From 4d807dd9948aa3fed22b385d28a4c2e9c0bbea31 Mon Sep 17 00:00:00 2001 From: Tonis Tiigi Date: Mon, 19 Dec 2022 10:25:16 -0800 Subject: [PATCH 02/10] docs: update provenance docs Signed-off-by: Tonis Tiigi --- docs/slsa.md | 301 ++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 272 insertions(+), 29 deletions(-) diff --git a/docs/slsa.md b/docs/slsa.md index 2374751deeda..9f302c38ad08 100644 --- a/docs/slsa.md +++ b/docs/slsa.md @@ -1,22 +1,22 @@ # 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: +attestations for the build process. Provenance attestations record information describing +how your build was performed and is important for tracking the security of your build pipeline. -- Build timestamps -- Build parameters and environment -- Version control metadata -- Source code details -- Materials consumed during the build +For example, provenance attestations created by BuildKit include details such as: + +- Build parameters and environment. +- Build timestamps. +- Version control metadata for your build sources. +- Build dependencies with their immutable checksums. For example, base images or external URLs used by the build. +- Descriptions of all build steps, with their source and layer mappings. 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: +To build an image with attached provenance with `buildctl`, use the `attest:provenance` option: ```bash buildctl build \ @@ -36,6 +36,14 @@ buildctl build \ --opt attest:provenance=mode=min,inline-only=true ``` +Provenance attestations can be attached to build results from all BuildKit exporters. +When the final output format is a container image(`image` or `oci` exporter), provenance is attached +to the image using the [attestation storage](./attestation-storage.md) specification. When creating a +multi-platform image, every single-platform subimage will have its own provenance. + +When using the `local` or `tar` exporter, the provenance will be written to a file named `provenance.json` +and exported with your build result. + ## Parameters | Parameter | Type | Default | Description | @@ -47,17 +55,17 @@ buildctl build \ ### `mode` -Provenance can be generated in one of two `mode`s: `min` or `max`. By default, +Provenance can be generated in one of two modes: `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, +In `min` mode, BuildKit generates only the bare minimum amount of provenance, including: - Build timestamps - The frontend used -- The inputs used +- The build materials -However, the values of build-arguments, the identities of secrets, and rich +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. @@ -68,16 +76,16 @@ In `max` mode, BuildKit generates all of the above, as well as: - The values of passed build arguments - Metadata about secrets and ssh mounts -Wherever possible, you should prefer `mode=max` as it contains signifantly +Wherever possible, you should prefer `mode=max` as it contains significantly 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 +values through secrets wherever possible to prevent unnecessary information leakage. ### `inline-only` -When generated, provenance is by included in all exporters that support +By default, 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. @@ -85,16 +93,254 @@ 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 -Many BuildKit builds are started from the context of a version-controlled -source repository, such as git. If the build uses a remote git context, -BuildKit can extract the details automatically. However, if the build uses a -local context, if you want VCS detail included, you must include these details -manually. +## Definition + +The provenance format generated by BuildKit is defined by the [SLSA Provenance format](https://slsa.dev/provenance/v0.2). + +The following is a selection of fields filled in by BuildKit: + +### `builder.id` [(SLSA)](https://slsa.dev/provenance/v0.2#builder.id) + +The `builder.id` field is set to the URL of the build, if available. This is value can be set with `builder-id` attestation parameter. + +``` + "builder": { + "id": "https://github.com/docker/buildx/actions/runs/3709599520" + }, +``` + +### `buildType` [(SLSA)](https://slsa.dev/provenance/v0.2#buildType) + +The `buildType` field is set to "https://mobyproject.org/buildkit@v1" can be used to determine the structure of the provenance content. + +``` + "buildType": "https://mobyproject.org/buildkit@v1", +``` + +### `invocation.configSource` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.configSource) + +Describes the config that initialized the build. + +``` + "invocation": { + "configSource": { + "uri": "https://github.com/moby/buildkit.git#refs/tags/v0.11.0-rc3", + "digest": { + "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0" + }, + "entryPoint": "Dockerfile" + }, +``` + +For builds that were initialized from a remote context like Git URL or HTTP URL, this structure +defines to URL to the context and its immutable digest. For frontend builds, the `entryPoint` field +defines the path for the Dockerfile that initialized the build (`filename` frontend option). + +### `invocation.parameters` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.parameters) + +Describes build inputs that were passed to the build. + +``` + "invocation": { + ... + "parameters": { + "frontend": "gateway.v0", + "args": { + "build-arg:BUILDKIT_CONTEXT_KEEP_GIT_DIR": "1", + "label:FOO": "bar", + "source": "docker/dockerfile-upstream:master", + "target": "release" + }, + "secrets": [ + { + "id": "GIT_AUTH_HEADER", + "optional": true + } + ... + ], + "ssh": [], + "locals": [], +``` + +- `frontend` defines BuildKit frontend used for the build. Currently, this can be `dockerfile.v0` or `gateway.v0`. +- `args` defines the build arguments passed to the BuildKit frontend. This maps to the `--opt` flag in `buildctl`. +The keys are specific to the frontend the build used. For example, in Dockerfile `build-arg:` and `label:` prefixes are +used for build arguments and labels, and `target` key defines the target stage that was built. +The `source` key defines the source image for the Gateway frontend, if used. +- `secrets` defines the secrets that were used to the build. Note that the actual secret values are not included. +- `ssh` defines the ssh forwards that were used to the build. +- `locals` defines if the build used any local sources. + + +### `invocation.environment` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.environment) + +``` + "environment": { + "platform": "linux/amd64" + } +``` + +The only value BuildKit currently sets is the `platform` of the current build machine. Note that this is not +necessarily the platform of the build result that can be determined from the `in-toto` subject field. + + +### `materials` [(SLSA)](https://slsa.dev/provenance/v0.2#materials) + +Defines all the external artifacts that were part of the build. These will be URLs to Git repositories +where the source code is coming from, HTTP URLs if you are building from a remote tarball or that you use +with `ADD` command in Dockerfile, or any Docker images that were used during the build. The URLs to +the Docker images will be in [Package URL](https://github.com/package-url/purl-spec) format. + +All the build materials will include the immutable checksum of the artifact. When building from a +mutable tag, you can use the digest information to determine if the artifact has been updated compared +to when the build ran. + +``` + "materials": [ + { + "uri": "pkg:docker/alpine@3.17?platform=linux%2Famd64", + "digest": { + "sha256": "8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4" + } + }, + { + "uri": "https://github.com/moby/buildkit.git#refs/tags/v0.11.0", + "digest": { + "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0" + } + } + ... + ], +``` + +### `buildConfig` [(SLSA)](https://slsa.dev/provenance/v0.2#buildConfig) + +Describes all the build steps performed during the build. + +BuildKit internally uses LLB definition to execute the build steps. The LLB definition of the build steps +is defined in `buildConfig.llbDefinition` field. + +Each LLB step is the JSON definition of the [LLB ProtoBuf API](https://github.com/moby/buildkit/blob/v0.10.0/solver/pb/ops.proto). +The dependencies for a vertex in the LLB graph can be found in the `inputs` field for every step. + +``` + "buildConfig": { + "llbDefinition": [ + { + "id": "step0", + "op": { + "Op": { + "exec": { + "meta": { + "args": [ + "/bin/sh", + "-c", + "go build ." + ], + "env": [ + "PATH=/go/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", + "GOPATH=/go", + "GOFLAGS=-mod=vendor", + ], + "cwd": "/src", + }, + "mounts": [...] + } + }, + "platform": {...}, + }, + "inputs": [ + "step8:0", + "step2:0", + ] + }, + ... +``` + +### `metadata.buildIncocationId` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildIncocationId) + +Unique identifier for the build invocation. Then building a multi-platform image with a single build request, +this value will be the same for all the single-platform subimages. + +``` + "metadata": { + "buildInvocationID": "rpv7a389uzil5lqmrgwhijwjz", +``` + +### `metadata.buildStartedOn` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildStartedOn) + +Timestamp when the build started. -To include VCS details, you can set the additional frontend options -`vcs:source` and `vcs:revision`: +``` + "buildStartedOn": "2021-11-17T15:00:00Z", +``` + +### `metadata.buildFinishedOn` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildFinishedOn) + +Timestamp when the build finished. + +``` + "buildFinishedOn": "2021-11-17T15:01:00Z", +``` + +### `metadata.completeness` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.completeness) + +Defines if the provenance information is complete. + +`completeness.parameters` is true if all the build arguments are included in the `invocation.parameters` field. +When building with `min` mode, the build arguments are not included in the provenance information and parameters +are not complete. Parameters are also not complete on direct LLB builds that did not use a frontend. + +`completeness.environment` is always true for BuildKit builds. + +`completeness.materials` is true if `materials` field includes all the dependencies of the build. When building +from untracked source in a local directory, the materials are not complete, while when building from a remote +Git repository all materials can be tracked by BuildKit and `completeness.materials` is true. + +`https://mobyproject.org/buildkit@v1#hermetic` is a custom field that is true if the build was hermetic and +did not access the network. In Dockerfiles, a build is hermetic if it does not use `RUN` commands or disables +network with `--network=none` flag. + +``` + "completeness": { + "parameters": true, + "environment": true, + "materials": true, + "https://mobyproject.org/buildkit@v1#hermetic": true + } + } +``` + +### `metadata.reproducible` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.reproducible) + +Defines if the build result is supposed to be byte-by-byte reproducible. This value can be set by the +user with the `reproducible=true` attestation parameter. + +``` + "reproducible": false +``` + +### `metadata.https://mobyproject.org/buildkit@v1#metadata` + +This extension field defines BuildKit-specific additional metadata that is not part of the SLSA provenance spec. + +`source` defines the source mapping of LLB build steps defined in `buildConfig.llbDefinition` to their +original source code (for example Dockerfile commands). `source.locations` contains the ranges of all the +Dockerfile commands that were executed by a LLB step. `source.infos` array contains the source code itself. +This mapping is present if the BuildKit frontend provided it when creating the LLB definition. + +`layers` defines the layer mapping of LLB build step mounts defined in `buildConfig.llbDefinition` to the +OCI descriptors of equivalent layers. This mapping is present if the layer data was available, usually +when attestation is for an image or if the build step pulled in image data as part of the build. + +`vcs` defines the optional metadata for the version control system that was used for the build. If a build +uses a remote context from Git repository, BuildKit can extract the details of the version control system +automatically and present it in the `invocation.configSource` field. But if the build uses a source from a +local directory, the VCS information is lost even if the directory contained a Git repository. In this case, +the build client can send additional `vcs:source` and `vcs:revision` build options and BuildKit will add +them to the provenance attestations as extra metadata. Note that contrary to the `invocation.configSource` +field, these values were not verified by BuildKit and should not be trusted other than for a metadata hint. ```bash buildctl build \ @@ -106,12 +352,9 @@ buildctl build \ --opt vcs:revision=0c9b5aeb269c740650786ba77d882b0259415ec7 ``` -These additional parameters will appear under the -`https://mobyproject.org/buildkit@v1#metadata` key in the provenance predicate. - ## Output -To inspect the provenance that was generated, and attached to a container +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). From c1963ec9df1cea17d19e90acdb03396a79005898 Mon Sep 17 00:00:00 2001 From: Tonis Tiigi Date: Tue, 20 Dec 2022 10:13:14 -0800 Subject: [PATCH 03/10] docs: update hermetic field after it was moved in implementation Signed-off-by: Tonis Tiigi --- docs/slsa.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/slsa.md b/docs/slsa.md index 9f302c38ad08..3078baf3cb56 100644 --- a/docs/slsa.md +++ b/docs/slsa.md @@ -298,16 +298,12 @@ are not complete. Parameters are also not complete on direct LLB builds that did from untracked source in a local directory, the materials are not complete, while when building from a remote Git repository all materials can be tracked by BuildKit and `completeness.materials` is true. -`https://mobyproject.org/buildkit@v1#hermetic` is a custom field that is true if the build was hermetic and -did not access the network. In Dockerfiles, a build is hermetic if it does not use `RUN` commands or disables -network with `--network=none` flag. ``` "completeness": { "parameters": true, "environment": true, - "materials": true, - "https://mobyproject.org/buildkit@v1#hermetic": true + "materials": true } } ``` @@ -321,6 +317,19 @@ user with the `reproducible=true` attestation parameter. "reproducible": false ``` + +### `metadata.https://mobyproject.org/buildkit@v1#hermetic` + +This extension field is set to true if the build was hermetic and did not access the network. +In Dockerfiles, a build is hermetic if it does not use `RUN` commands or disables +network with `--network=none` flag. + +``` + "metadata": { + "https://mobyproject.org/buildkit@v1#hermetic": true, + ... +``` + ### `metadata.https://mobyproject.org/buildkit@v1#metadata` This extension field defines BuildKit-specific additional metadata that is not part of the SLSA provenance spec. From 9c212c25bd8833d8ca799889e07a952198634f27 Mon Sep 17 00:00:00 2001 From: Tonis Tiigi Date: Tue, 20 Dec 2022 10:33:18 -0800 Subject: [PATCH 04/10] docs: add filename to provenance attestation Signed-off-by: Tonis Tiigi --- docs/slsa.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/slsa.md b/docs/slsa.md index 3078baf3cb56..f60632432fa3 100644 --- a/docs/slsa.md +++ b/docs/slsa.md @@ -46,12 +46,13 @@ and exported with your build result. ## Parameters -| Parameter | Type | Default | Description | +| Parameter | Type | Default | Description | | -------------- | -------------- | ---------------- | ----------------------------------------------------------------------------------------------------------- | -| `mode` | `min`,`max` | `max` | Configures the amount of provenance to be generated. See [mode](#mode) | -| `builder-id` | String | | Explicitly set SLSA [`builder.id`](https://slsa.dev/provenance/v0.2#builder.id) field | -| `reproducible` | `true`,`false` | `false` | Explicitly set SLSA [`metadata.reproducible`](https://slsa.dev/provenance/v0.2#metadata.reproducible) field | -| `inline-only` | `true`,`false` | `false` | Only embed provenance into exporters that support inline content. See [inline-only](#inline-only) | +| `mode` | `min`,`max` | `max` | Configures the amount of provenance to be generated. See [mode](#mode) | +| `builder-id` | String | | Explicitly set SLSA [`builder.id`](https://slsa.dev/provenance/v0.2#builder.id) field | +| `filename` | String | `provenance.json` | Set filename for provenance attestation when exported with `local` or `tar` exporter | +| `reproducible` | `true`,`false` | `false` | Explicitly set SLSA [`metadata.reproducible`](https://slsa.dev/provenance/v0.2#metadata.reproducible) field | +| `inline-only` | `true`,`false` | `false` | Only embed provenance into exporters that support inline content. See [inline-only](#inline-only) | ### `mode` From 066091a5006f0baef1b35cc5673aeaf685e377f1 Mon Sep 17 00:00:00 2001 From: David Karlsson Date: Thu, 22 Dec 2022 09:53:57 +0100 Subject: [PATCH 05/10] docs: slsa editorial fixes Signed-off-by: David Karlsson --- docs/slsa.md | 148 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 101 insertions(+), 47 deletions(-) diff --git a/docs/slsa.md b/docs/slsa.md index f60632432fa3..5f366ff27128 100644 --- a/docs/slsa.md +++ b/docs/slsa.md @@ -2,9 +2,10 @@ BuildKit supports automatic creation of [SLSA Provenance](https://slsa.dev/provenance) attestations for the build process. Provenance attestations record information describing -how your build was performed and is important for tracking the security of your build pipeline. +how a build was created, and is important for tracking the security of your software +artifacts. -For example, provenance attestations created by BuildKit include details such as: +Provenance attestations created by BuildKit include details such as: - Build parameters and environment. - Build timestamps. @@ -12,11 +13,12 @@ For example, provenance attestations created by BuildKit include details such as - Build dependencies with their immutable checksums. For example, base images or external URLs used by the build. - Descriptions of all build steps, with their source and layer mappings. -All provenance generated by BuildKit is wrapped inside [in-toto attestations](https://github.com/in-toto/attestation) +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). +## Build with provenance attestations -To build an image with attached provenance with `buildctl`, use the `attest:provenance` option: +To build an image with provenance attestations using `buildctl`, use the `attest:provenance` option: ```bash buildctl build \ @@ -26,7 +28,7 @@ buildctl build \ --opt attest:provenance= ``` -You can also specify custom parameters for the provenance: +You can also customize the attestations using parameters: ```bash buildctl build \ @@ -36,13 +38,13 @@ buildctl build \ --opt attest:provenance=mode=min,inline-only=true ``` -Provenance attestations can be attached to build results from all BuildKit exporters. -When the final output format is a container image(`image` or `oci` exporter), provenance is attached -to the image using the [attestation storage](./attestation-storage.md) specification. When creating a -multi-platform image, every single-platform subimage will have its own provenance. +All BuildKit exporters support attaching attestations to build results. +When the final output format is a container image (`image` or `oci` exporter), provenance is attached +to the image using the format described in the [attestation storage specification](./attestation-storage.md). +When creating a multi-platform image, each platform version of the image gets its own provenance. -When using the `local` or `tar` exporter, the provenance will be written to a file named `provenance.json` -and exported with your build result. +If you use the `local` or `tar` exporter, the provenance will be written to a file named `provenance.json` +and exported with your build result, in the root directory. ## Parameters @@ -99,11 +101,14 @@ filesystems, you may not want to include the provenance in these cases. The provenance format generated by BuildKit is defined by the [SLSA Provenance format](https://slsa.dev/provenance/v0.2). -The following is a selection of fields filled in by BuildKit: +This section describes how BuildKit populate each field, and whether the +field gets included when you generate attestations `mode=min` and `mode=max`. ### `builder.id` [(SLSA)](https://slsa.dev/provenance/v0.2#builder.id) -The `builder.id` field is set to the URL of the build, if available. This is value can be set with `builder-id` attestation parameter. +Included with `mode=min`. + +The `builder.id` field is set to the URL of the build, if available. ``` "builder": { @@ -111,8 +116,12 @@ The `builder.id` field is set to the URL of the build, if available. This is val }, ``` +This value can be set using the `builder-id` attestation parameter. + ### `buildType` [(SLSA)](https://slsa.dev/provenance/v0.2#buildType) +Included with `mode=min`. + The `buildType` field is set to "https://mobyproject.org/buildkit@v1" can be used to determine the structure of the provenance content. ``` @@ -121,6 +130,8 @@ The `buildType` field is set to "https://mobyproject.org/buildkit@v1" can be use ### `invocation.configSource` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.configSource) +Included with `mode=min`. + Describes the config that initialized the build. ``` @@ -134,12 +145,15 @@ Describes the config that initialized the build. }, ``` -For builds that were initialized from a remote context like Git URL or HTTP URL, this structure -defines to URL to the context and its immutable digest. For frontend builds, the `entryPoint` field -defines the path for the Dockerfile that initialized the build (`filename` frontend option). +For builds that were initialized from a remote context, like a Git or HTTP URL, this object +defines to URL to the context and its immutable digest. For builds using a local frontend, +such as a Dockerfile, the `entryPoint` field defines the path for the frontend file that +initialized the build (`filename` frontend option). ### `invocation.parameters` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.parameters) +Partially included with `mode=min`. + Describes build inputs that were passed to the build. ``` @@ -164,18 +178,26 @@ Describes build inputs that were passed to the build. "locals": [], ``` -- `frontend` defines BuildKit frontend used for the build. Currently, this can be `dockerfile.v0` or `gateway.v0`. +The following properties are included with both `mode=min` and `mode=max`: + +- `locals` lists any local sources used in the build, including the build context and frontend file. +- `frontend` defines type of BuildKit frontend used for the build. Currently, this can be `dockerfile.v0` or `gateway.v0`. - `args` defines the build arguments passed to the BuildKit frontend. This maps to the `--opt` flag in `buildctl`. -The keys are specific to the frontend the build used. For example, in Dockerfile `build-arg:` and `label:` prefixes are -used for build arguments and labels, and `target` key defines the target stage that was built. -The `source` key defines the source image for the Gateway frontend, if used. -- `secrets` defines the secrets that were used to the build. Note that the actual secret values are not included. + + The keys are specific to the frontend the build used. For example, in Dockerfile `build-arg:` and `label:` prefixes + are used for build arguments and labels, and `target` key defines the target stage that was built. The `source` key + defines the source image for the Gateway frontend, if used. + +The following properties are only included with `mode=max`: + +- `secrets` defines what secrets were used to the build. Note that actual secret values are not included. - `ssh` defines the ssh forwards that were used to the build. -- `locals` defines if the build used any local sources. ### `invocation.environment` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.environment) +Included with `mode=min`. + ``` "environment": { "platform": "linux/amd64" @@ -188,10 +210,15 @@ necessarily the platform of the build result that can be determined from the `in ### `materials` [(SLSA)](https://slsa.dev/provenance/v0.2#materials) -Defines all the external artifacts that were part of the build. These will be URLs to Git repositories -where the source code is coming from, HTTP URLs if you are building from a remote tarball or that you use -with `ADD` command in Dockerfile, or any Docker images that were used during the build. The URLs to -the Docker images will be in [Package URL](https://github.com/package-url/purl-spec) format. +Included with `mode=min`. + +Defines all the external artifacts that were part of the build. The value depends on the type of artifact: + +- The URL of Git repositories containing source code for the image +- HTTP URLs if you are building from a remote tarball, or that was included using an `ADD` command in Dockerfile +- Any Docker images that were used during the build + +The URLs to the Docker images will be in [Package URL](https://github.com/package-url/purl-spec) format. All the build materials will include the immutable checksum of the artifact. When building from a mutable tag, you can use the digest information to determine if the artifact has been updated compared @@ -217,7 +244,9 @@ to when the build ran. ### `buildConfig` [(SLSA)](https://slsa.dev/provenance/v0.2#buildConfig) -Describes all the build steps performed during the build. +Only included with `mode=max`. + +Defines the build steps performed during the build. BuildKit internally uses LLB definition to execute the build steps. The LLB definition of the build steps is defined in `buildConfig.llbDefinition` field. @@ -259,10 +288,12 @@ The dependencies for a vertex in the LLB graph can be found in the `inputs` fiel ... ``` -### `metadata.buildIncocationId` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildIncocationId) +### `metadata.buildInvocationId` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildIncocationId) + +Included with `mode=min`. -Unique identifier for the build invocation. Then building a multi-platform image with a single build request, -this value will be the same for all the single-platform subimages. +Unique identifier for the build invocation. When building a multi-platform image with a single build request, +this value will be the shared by all the platform versions of the image. ``` "metadata": { @@ -271,6 +302,8 @@ this value will be the same for all the single-platform subimages. ### `metadata.buildStartedOn` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildStartedOn) +Included with `mode=min`. + Timestamp when the build started. ``` @@ -279,6 +312,8 @@ Timestamp when the build started. ### `metadata.buildFinishedOn` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildFinishedOn) +Included with `mode=min`. + Timestamp when the build finished. ``` @@ -287,6 +322,8 @@ Timestamp when the build finished. ### `metadata.completeness` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.completeness) +Included with `mode=min`. + Defines if the provenance information is complete. `completeness.parameters` is true if all the build arguments are included in the `invocation.parameters` field. @@ -321,6 +358,8 @@ user with the `reproducible=true` attestation parameter. ### `metadata.https://mobyproject.org/buildkit@v1#hermetic` +Included with `mode=min`. + This extension field is set to true if the build was hermetic and did not access the network. In Dockerfiles, a build is hermetic if it does not use `RUN` commands or disables network with `--network=none` flag. @@ -333,24 +372,39 @@ network with `--network=none` flag. ### `metadata.https://mobyproject.org/buildkit@v1#metadata` +Partially included with `mode=min`. + This extension field defines BuildKit-specific additional metadata that is not part of the SLSA provenance spec. -`source` defines the source mapping of LLB build steps defined in `buildConfig.llbDefinition` to their -original source code (for example Dockerfile commands). `source.locations` contains the ranges of all the -Dockerfile commands that were executed by a LLB step. `source.infos` array contains the source code itself. -This mapping is present if the BuildKit frontend provided it when creating the LLB definition. +#### `source` -`layers` defines the layer mapping of LLB build step mounts defined in `buildConfig.llbDefinition` to the +Only included with `mode=max`. + +Defines a source mapping of LLB build steps, defined in the `buildConfig.llbDefinition` field, to their +original source code (for example, Dockerfile commands). The `source.locations` field contains the ranges +of all the Dockerfile commands that were executed in an LLB step. `source.infos` array contains the source +code itself. This mapping is present if the BuildKit frontend provided it when creating the LLB definition. + +#### `layers` + +Only included with `mode=max`. + +Defines the layer mapping of LLB build step mounts defined in `buildConfig.llbDefinition` to the OCI descriptors of equivalent layers. This mapping is present if the layer data was available, usually when attestation is for an image or if the build step pulled in image data as part of the build. -`vcs` defines the optional metadata for the version control system that was used for the build. If a build -uses a remote context from Git repository, BuildKit can extract the details of the version control system -automatically and present it in the `invocation.configSource` field. But if the build uses a source from a -local directory, the VCS information is lost even if the directory contained a Git repository. In this case, -the build client can send additional `vcs:source` and `vcs:revision` build options and BuildKit will add -them to the provenance attestations as extra metadata. Note that contrary to the `invocation.configSource` -field, these values were not verified by BuildKit and should not be trusted other than for a metadata hint. +#### `vcs` + +Included with both `mode=min` and `mode=max`. + +Defines optional metadata for the version control system used for the build. If a build uses a +remote context from Git repository, BuildKit extracts the details of the version control +system automatically and displays it in the `invocation.configSource` field. But if the build +uses a source from a local directory, the VCS information is lost even if the directory contained +a Git repository. In this case, the build client can send additional `vcs:source` and +`vcs:revision` build options and BuildKit will add them to the provenance attestations as extra +metadata. Note that, contrary to the `invocation.configSource` field, BuildKit doesn't verify the +`vcs` values, and as such they can't be trusted and should only be used as a metadata hint. ```bash buildctl build \ @@ -365,12 +419,12 @@ buildctl build \ ## 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). +image, you can use the `docker buildx imagetools` command to inspect the +image in a registry. Inspecting the attestation displays the format described +in the [attestation storage specification](./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: +For example, inspecting a simple Docker image based on `alpine:latest` results +in a provenance attestation similar to the following, for a `mode=min` build: ```json { From ea715c8fcadeb4525ab067545fa6fa66fa3e8f8b Mon Sep 17 00:00:00 2001 From: David Karlsson Date: Thu, 22 Dec 2022 11:08:20 +0100 Subject: [PATCH 06/10] docs: moved slsa definitions to a separate page Signed-off-by: David Karlsson --- docs/slsa-definitions.md | 552 +++++++++++++++++++++++++++++++++++++++ docs/slsa.md | 549 +------------------------------------- 2 files changed, 554 insertions(+), 547 deletions(-) create mode 100644 docs/slsa-definitions.md diff --git a/docs/slsa-definitions.md b/docs/slsa-definitions.md new file mode 100644 index 000000000000..b0b667fb190e --- /dev/null +++ b/docs/slsa-definitions.md @@ -0,0 +1,552 @@ +# SLSA definitions + +The provenance format generated by BuildKit is defined by the +[SLSA Provenance format](https://slsa.dev/provenance/v0.2). + +This page describes how BuildKit populate each field, and whether the field gets +included when you generate attestations `mode=min` and `mode=max`. + +## `builder.id` [(SLSA)](https://slsa.dev/provenance/v0.2#builder.id) + +Included with `mode=min`. + +The `builder.id` field is set to the URL of the build, if available. + +```json + "builder": { + "id": "https://github.com/docker/buildx/actions/runs/3709599520" + }, +``` + +This value can be set using the `builder-id` attestation parameter. + +## `buildType` [(SLSA)](https://slsa.dev/provenance/v0.2#buildType) + +Included with `mode=min`. + +The `buildType` field is set to `https://mobyproject.org/buildkit@v1` can be +used to determine the structure of the provenance content. + +``` + "buildType": "https://mobyproject.org/buildkit@v1", +``` + +## `invocation.configSource` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.configSource) + +Included with `mode=min`. + +Describes the config that initialized the build. + +```json + "invocation": { + "configSource": { + "uri": "https://github.com/moby/buildkit.git#refs/tags/v0.11.0-rc3", + "digest": { + "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0" + }, + "entryPoint": "Dockerfile" + }, +``` + +For builds initialized from a remote context, like a Git or HTTP URL, this +object defines to URL to the context and its immutable digest. For builds using +a local frontend, such as a Dockerfile, the `entryPoint` field defines the path +for the frontend file that initialized the build (`filename` frontend option). + +## `invocation.parameters` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.parameters) + +Partially included with `mode=min`. + +Describes build inputs passed to the build. + +```json + "invocation": { + ... + "parameters": { + "frontend": "gateway.v0", + "args": { + "build-arg:BUILDKIT_CONTEXT_KEEP_GIT_DIR": "1", + "label:FOO": "bar", + "source": "docker/dockerfile-upstream:master", + "target": "release" + }, + "secrets": [ + { + "id": "GIT_AUTH_HEADER", + "optional": true + } + ... + ], + "ssh": [], + "locals": [], +``` + +The following fields are included with both `mode=min` and `mode=max`: + +- `locals` lists any local sources used in the build, including the build + context and frontend file. +- `frontend` defines type of BuildKit frontend used for the build. Currently, + this can be `dockerfile.v0` or `gateway.v0`. +- `args` defines the build arguments passed to the BuildKit frontend. + + The keys inside the `args` object reflect the options as BuildKit receives + them. For example, `build-arg` and `label` prefixes are used for build + arguments and labels, and `target` key defines the target stage that was + built. The `source` key defines the source image for the Gateway frontend, if + used. + +The following fields are only included with `mode=max`: + +- `secrets` defines secrets used during the build. Note that actual secret + values are not included. +- `ssh` defines the ssh forwards used during the build. + +## `invocation.environment` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.environment) + +Included with `mode=min`. + +```json + "environment": { + "platform": "linux/amd64" + } +``` + +The only value BuildKit currently sets is the `platform` of the current build +machine. Note that this is not necessarily the platform of the build result that +can be determined from the `in-toto` subject field. + +## `materials` [(SLSA)](https://slsa.dev/provenance/v0.2#materials) + +Included with `mode=min`. + +Defines all the external artifacts that were part of the build. The value +depends on the type of artifact: + +- The URL of Git repositories containing source code for the image +- HTTP URLs if you are building from a remote tarball, or that was included + using an `ADD` command in Dockerfile +- Any Docker images used during the build + +The URLs to the Docker images will be in +[Package URL](https://github.com/package-url/purl-spec) format. + +All the build materials will include the immutable checksum of the artifact. +When building from a mutable tag, you can use the digest information to +determine if the artifact has been updated compared to when the build ran. + +```json + "materials": [ + { + "uri": "pkg:docker/alpine@3.17?platform=linux%2Famd64", + "digest": { + "sha256": "8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4" + } + }, + { + "uri": "https://github.com/moby/buildkit.git#refs/tags/v0.11.0", + "digest": { + "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0" + } + } + ... + ], +``` + +## `buildConfig` [(SLSA)](https://slsa.dev/provenance/v0.2#buildConfig) + +Only included with `mode=max`. + +Defines the build steps performed during the build. + +BuildKit internally uses LLB definition to execute the build steps. The LLB +definition of the build steps is defined in `buildConfig.llbDefinition` field. + +Each LLB step is the JSON definition of the +[LLB ProtoBuf API](https://github.com/moby/buildkit/blob/v0.10.0/solver/pb/ops.proto). +The dependencies for a vertex in the LLB graph can be found in the `inputs` +field for every step. + +```json + "buildConfig": { + "llbDefinition": [ + { + "id": "step0", + "op": { + "Op": { + "exec": { + "meta": { + "args": [ + "/bin/sh", + "-c", + "go build ." + ], + "env": [ + "PATH=/go/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", + "GOPATH=/go", + "GOFLAGS=-mod=vendor", + ], + "cwd": "/src", + }, + "mounts": [...] + } + }, + "platform": {...}, + }, + "inputs": [ + "step8:0", + "step2:0", + ] + }, + ... +``` + +## `metadata.buildInvocationId` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildIncocationId) + +Included with `mode=min`. + +Unique identifier for the build invocation. When building a multi-platform image +with a single build request, this value will be the shared by all the platform +versions of the image. + +```json + "metadata": { + "buildInvocationID": "rpv7a389uzil5lqmrgwhijwjz", +``` + +## `metadata.buildStartedOn` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildStartedOn) + +Included with `mode=min`. + +Timestamp when the build started. + +```json + "buildStartedOn": "2021-11-17T15:00:00Z", +``` + +## `metadata.buildFinishedOn` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildFinishedOn) + +Included with `mode=min`. + +Timestamp when the build finished. + +```json + "buildFinishedOn": "2021-11-17T15:01:00Z", +``` + +## `metadata.completeness` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.completeness) + +Included with `mode=min`. + +Defines if the provenance information is complete. + +`completeness.parameters` is true if all the build arguments are included in the +`invocation.parameters` field. When building with `min` mode, the build +arguments are not included in the provenance information and parameters are not +complete. Parameters are also not complete on direct LLB builds that did not use +a frontend. + +`completeness.environment` is always true for BuildKit builds. + +`completeness.materials` is true if `materials` field includes all the +dependencies of the build. When building from un-tracked source in a local +directory, the materials are not complete, while when building from a remote Git +repository all materials can be tracked by BuildKit and `completeness.materials` +is true. + +```json + "completeness": { + "parameters": true, + "environment": true, + "materials": true + } + } +``` + +## `metadata.reproducible` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.reproducible) + +Defines if the build result is supposed to be byte-by-byte reproducible. This +value can be set by the user with the `reproducible=true` attestation parameter. + +```json + "reproducible": false +``` + +## `metadata.https://mobyproject.org/buildkit@v1#hermetic` + +Included with `mode=min`. + +This extension field is set to true if the build was hermetic and did not access +the network. In Dockerfiles, a build is hermetic if it does not use `RUN` +commands or disables network with `--network=none` flag. + +```json + "metadata": { + "https://mobyproject.org/buildkit@v1#hermetic": true, + ... +``` + +## `metadata.https://mobyproject.org/buildkit@v1#metadata` + +Partially included with `mode=min`. + +This extension field defines BuildKit-specific additional metadata that is not +part of the SLSA provenance spec. + +### `source` + +Only included with `mode=max`. + +Defines a source mapping of LLB build steps, defined in the +`buildConfig.llbDefinition` field, to their original source code (for example, +Dockerfile commands). The `source.locations` field contains the ranges of all +the Dockerfile commands ran in an LLB step. `source.infos` array contains the +source code itself. This mapping is present if the BuildKit frontend provided it +when creating the LLB definition. + +### `layers` + +Only included with `mode=max`. + +Defines the layer mapping of LLB build step mounts defined in +`buildConfig.llbDefinition` to the OCI descriptors of equivalent layers. This +mapping is present if the layer data was available, usually when attestation is +for an image or if the build step pulled in image data as part of the build. + +### `vcs` + +Included with both `mode=min` and `mode=max`. + +Defines optional metadata for the version control system used for the build. If +a build uses a remote context from Git repository, BuildKit extracts the details +of the version control system automatically and displays it in the +`invocation.configSource` field. But if the build uses a source from a local +directory, the VCS information is lost even if the directory contained a Git +repository. In this case, the build client can send additional `vcs:source` and +`vcs:revision` build options and BuildKit will add them to the provenance +attestations as extra metadata. Note that, contrary to the +`invocation.configSource` field, BuildKit doesn't verify the `vcs` values, and +as such they can't be trusted and should only be used as a metadata hint. + +## Output + +To inspect the provenance that was generated and attached to a container image, +you can use the `docker buildx imagetools` command to inspect the image in a +registry. Inspecting the attestation displays the format described in the +[attestation storage specification](./attestation-storage.md). + +For example, inspecting a simple Docker image based on `alpine:latest` results +in a provenance attestation similar to the following, 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 + } + ] + ] + } + } + } + } +} +``` diff --git a/docs/slsa.md b/docs/slsa.md index 5f366ff27128..cab9d94db1b2 100644 --- a/docs/slsa.md +++ b/docs/slsa.md @@ -16,6 +16,8 @@ Provenance attestations created by BuildKit include details such as: 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). +For more information about how the attestation fields get generated, see [SLSA definitions](./slsa-definitions.md). + ## Build with provenance attestations To build an image with provenance attestations using `buildctl`, use the `attest:provenance` option: @@ -96,550 +98,3 @@ 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. - -## Definition - -The provenance format generated by BuildKit is defined by the [SLSA Provenance format](https://slsa.dev/provenance/v0.2). - -This section describes how BuildKit populate each field, and whether the -field gets included when you generate attestations `mode=min` and `mode=max`. - -### `builder.id` [(SLSA)](https://slsa.dev/provenance/v0.2#builder.id) - -Included with `mode=min`. - -The `builder.id` field is set to the URL of the build, if available. - -``` - "builder": { - "id": "https://github.com/docker/buildx/actions/runs/3709599520" - }, -``` - -This value can be set using the `builder-id` attestation parameter. - -### `buildType` [(SLSA)](https://slsa.dev/provenance/v0.2#buildType) - -Included with `mode=min`. - -The `buildType` field is set to "https://mobyproject.org/buildkit@v1" can be used to determine the structure of the provenance content. - -``` - "buildType": "https://mobyproject.org/buildkit@v1", -``` - -### `invocation.configSource` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.configSource) - -Included with `mode=min`. - -Describes the config that initialized the build. - -``` - "invocation": { - "configSource": { - "uri": "https://github.com/moby/buildkit.git#refs/tags/v0.11.0-rc3", - "digest": { - "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0" - }, - "entryPoint": "Dockerfile" - }, -``` - -For builds that were initialized from a remote context, like a Git or HTTP URL, this object -defines to URL to the context and its immutable digest. For builds using a local frontend, -such as a Dockerfile, the `entryPoint` field defines the path for the frontend file that -initialized the build (`filename` frontend option). - -### `invocation.parameters` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.parameters) - -Partially included with `mode=min`. - -Describes build inputs that were passed to the build. - -``` - "invocation": { - ... - "parameters": { - "frontend": "gateway.v0", - "args": { - "build-arg:BUILDKIT_CONTEXT_KEEP_GIT_DIR": "1", - "label:FOO": "bar", - "source": "docker/dockerfile-upstream:master", - "target": "release" - }, - "secrets": [ - { - "id": "GIT_AUTH_HEADER", - "optional": true - } - ... - ], - "ssh": [], - "locals": [], -``` - -The following properties are included with both `mode=min` and `mode=max`: - -- `locals` lists any local sources used in the build, including the build context and frontend file. -- `frontend` defines type of BuildKit frontend used for the build. Currently, this can be `dockerfile.v0` or `gateway.v0`. -- `args` defines the build arguments passed to the BuildKit frontend. This maps to the `--opt` flag in `buildctl`. - - The keys are specific to the frontend the build used. For example, in Dockerfile `build-arg:` and `label:` prefixes - are used for build arguments and labels, and `target` key defines the target stage that was built. The `source` key - defines the source image for the Gateway frontend, if used. - -The following properties are only included with `mode=max`: - -- `secrets` defines what secrets were used to the build. Note that actual secret values are not included. -- `ssh` defines the ssh forwards that were used to the build. - - -### `invocation.environment` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.environment) - -Included with `mode=min`. - -``` - "environment": { - "platform": "linux/amd64" - } -``` - -The only value BuildKit currently sets is the `platform` of the current build machine. Note that this is not -necessarily the platform of the build result that can be determined from the `in-toto` subject field. - - -### `materials` [(SLSA)](https://slsa.dev/provenance/v0.2#materials) - -Included with `mode=min`. - -Defines all the external artifacts that were part of the build. The value depends on the type of artifact: - -- The URL of Git repositories containing source code for the image -- HTTP URLs if you are building from a remote tarball, or that was included using an `ADD` command in Dockerfile -- Any Docker images that were used during the build - -The URLs to the Docker images will be in [Package URL](https://github.com/package-url/purl-spec) format. - -All the build materials will include the immutable checksum of the artifact. When building from a -mutable tag, you can use the digest information to determine if the artifact has been updated compared -to when the build ran. - -``` - "materials": [ - { - "uri": "pkg:docker/alpine@3.17?platform=linux%2Famd64", - "digest": { - "sha256": "8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4" - } - }, - { - "uri": "https://github.com/moby/buildkit.git#refs/tags/v0.11.0", - "digest": { - "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0" - } - } - ... - ], -``` - -### `buildConfig` [(SLSA)](https://slsa.dev/provenance/v0.2#buildConfig) - -Only included with `mode=max`. - -Defines the build steps performed during the build. - -BuildKit internally uses LLB definition to execute the build steps. The LLB definition of the build steps -is defined in `buildConfig.llbDefinition` field. - -Each LLB step is the JSON definition of the [LLB ProtoBuf API](https://github.com/moby/buildkit/blob/v0.10.0/solver/pb/ops.proto). -The dependencies for a vertex in the LLB graph can be found in the `inputs` field for every step. - -``` - "buildConfig": { - "llbDefinition": [ - { - "id": "step0", - "op": { - "Op": { - "exec": { - "meta": { - "args": [ - "/bin/sh", - "-c", - "go build ." - ], - "env": [ - "PATH=/go/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", - "GOPATH=/go", - "GOFLAGS=-mod=vendor", - ], - "cwd": "/src", - }, - "mounts": [...] - } - }, - "platform": {...}, - }, - "inputs": [ - "step8:0", - "step2:0", - ] - }, - ... -``` - -### `metadata.buildInvocationId` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildIncocationId) - -Included with `mode=min`. - -Unique identifier for the build invocation. When building a multi-platform image with a single build request, -this value will be the shared by all the platform versions of the image. - -``` - "metadata": { - "buildInvocationID": "rpv7a389uzil5lqmrgwhijwjz", -``` - -### `metadata.buildStartedOn` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildStartedOn) - -Included with `mode=min`. - -Timestamp when the build started. - -``` - "buildStartedOn": "2021-11-17T15:00:00Z", -``` - -### `metadata.buildFinishedOn` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildFinishedOn) - -Included with `mode=min`. - -Timestamp when the build finished. - -``` - "buildFinishedOn": "2021-11-17T15:01:00Z", -``` - -### `metadata.completeness` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.completeness) - -Included with `mode=min`. - -Defines if the provenance information is complete. - -`completeness.parameters` is true if all the build arguments are included in the `invocation.parameters` field. -When building with `min` mode, the build arguments are not included in the provenance information and parameters -are not complete. Parameters are also not complete on direct LLB builds that did not use a frontend. - -`completeness.environment` is always true for BuildKit builds. - -`completeness.materials` is true if `materials` field includes all the dependencies of the build. When building -from untracked source in a local directory, the materials are not complete, while when building from a remote -Git repository all materials can be tracked by BuildKit and `completeness.materials` is true. - - -``` - "completeness": { - "parameters": true, - "environment": true, - "materials": true - } - } -``` - -### `metadata.reproducible` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.reproducible) - -Defines if the build result is supposed to be byte-by-byte reproducible. This value can be set by the -user with the `reproducible=true` attestation parameter. - -``` - "reproducible": false -``` - - -### `metadata.https://mobyproject.org/buildkit@v1#hermetic` - -Included with `mode=min`. - -This extension field is set to true if the build was hermetic and did not access the network. -In Dockerfiles, a build is hermetic if it does not use `RUN` commands or disables -network with `--network=none` flag. - -``` - "metadata": { - "https://mobyproject.org/buildkit@v1#hermetic": true, - ... -``` - -### `metadata.https://mobyproject.org/buildkit@v1#metadata` - -Partially included with `mode=min`. - -This extension field defines BuildKit-specific additional metadata that is not part of the SLSA provenance spec. - -#### `source` - -Only included with `mode=max`. - -Defines a source mapping of LLB build steps, defined in the `buildConfig.llbDefinition` field, to their -original source code (for example, Dockerfile commands). The `source.locations` field contains the ranges -of all the Dockerfile commands that were executed in an LLB step. `source.infos` array contains the source -code itself. This mapping is present if the BuildKit frontend provided it when creating the LLB definition. - -#### `layers` - -Only included with `mode=max`. - -Defines the layer mapping of LLB build step mounts defined in `buildConfig.llbDefinition` to the -OCI descriptors of equivalent layers. This mapping is present if the layer data was available, usually -when attestation is for an image or if the build step pulled in image data as part of the build. - -#### `vcs` - -Included with both `mode=min` and `mode=max`. - -Defines optional metadata for the version control system used for the build. If a build uses a -remote context from Git repository, BuildKit extracts the details of the version control -system automatically and displays it in the `invocation.configSource` field. But if the build -uses a source from a local directory, the VCS information is lost even if the directory contained -a Git repository. In this case, the build client can send additional `vcs:source` and -`vcs:revision` build options and BuildKit will add them to the provenance attestations as extra -metadata. Note that, contrary to the `invocation.configSource` field, BuildKit doesn't verify the -`vcs` values, and as such they can't be trusted and should only be used as a metadata hint. - -```bash -buildctl build \ - --frontend=dockerfile.v0 \ - --local context=. \ - --local dockerfile=. \ - --opt attest:provenance= \ - --opt vcs:source=https://github.com/moby/buildkit \ - --opt vcs:revision=0c9b5aeb269c740650786ba77d882b0259415ec7 -``` - -## Output - -To inspect the provenance that was generated and attached to a container -image, you can use the `docker buildx imagetools` command to inspect the -image in a registry. Inspecting the attestation displays the format described -in the [attestation storage specification](./attestation-storage.md). - -For example, inspecting a simple Docker image based on `alpine:latest` results -in a provenance attestation similar to the following, 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 - } - ] - ] - } - } - } - } -} -``` From 4664605c4d7565a3eccfb313bc22b1fa2fec9778 Mon Sep 17 00:00:00 2001 From: David Karlsson Date: Tue, 3 Jan 2023 17:36:12 +0100 Subject: [PATCH 07/10] docs: slsa review updates Signed-off-by: David Karlsson --- docs/slsa-definitions.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/slsa-definitions.md b/docs/slsa-definitions.md index b0b667fb190e..9bd7995e6555 100644 --- a/docs/slsa-definitions.md +++ b/docs/slsa-definitions.md @@ -8,7 +8,7 @@ included when you generate attestations `mode=min` and `mode=max`. ## `builder.id` [(SLSA)](https://slsa.dev/provenance/v0.2#builder.id) -Included with `mode=min`. +Included with `mode=min` and `mode=max`. The `builder.id` field is set to the URL of the build, if available. @@ -22,7 +22,7 @@ This value can be set using the `builder-id` attestation parameter. ## `buildType` [(SLSA)](https://slsa.dev/provenance/v0.2#buildType) -Included with `mode=min`. +Included with `mode=min` and `mode=max`. The `buildType` field is set to `https://mobyproject.org/buildkit@v1` can be used to determine the structure of the provenance content. @@ -33,7 +33,7 @@ used to determine the structure of the provenance content. ## `invocation.configSource` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.configSource) -Included with `mode=min`. +Included with `mode=min` and `mode=max`. Describes the config that initialized the build. @@ -49,8 +49,8 @@ Describes the config that initialized the build. ``` For builds initialized from a remote context, like a Git or HTTP URL, this -object defines to URL to the context and its immutable digest. For builds using -a local frontend, such as a Dockerfile, the `entryPoint` field defines the path +object defines the context URL and its immutable digest in the `uri` and `digest` fields. +For builds using a local frontend, such as a Dockerfile, the `entryPoint` field defines the path for the frontend file that initialized the build (`filename` frontend option). ## `invocation.parameters` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.parameters) @@ -103,7 +103,7 @@ The following fields are only included with `mode=max`: ## `invocation.environment` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.environment) -Included with `mode=min`. +Included with `mode=min` and `mode=max`. ```json "environment": { @@ -117,7 +117,7 @@ can be determined from the `in-toto` subject field. ## `materials` [(SLSA)](https://slsa.dev/provenance/v0.2#materials) -Included with `mode=min`. +Included with `mode=min` and `mode=max`. Defines all the external artifacts that were part of the build. The value depends on the type of artifact: @@ -202,7 +202,7 @@ field for every step. ## `metadata.buildInvocationId` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildIncocationId) -Included with `mode=min`. +Included with `mode=min` and `mode=max`. Unique identifier for the build invocation. When building a multi-platform image with a single build request, this value will be the shared by all the platform @@ -215,7 +215,7 @@ versions of the image. ## `metadata.buildStartedOn` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildStartedOn) -Included with `mode=min`. +Included with `mode=min` and `mode=max`. Timestamp when the build started. @@ -225,7 +225,7 @@ Timestamp when the build started. ## `metadata.buildFinishedOn` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildFinishedOn) -Included with `mode=min`. +Included with `mode=min` and `mode=max`. Timestamp when the build finished. @@ -235,7 +235,7 @@ Timestamp when the build finished. ## `metadata.completeness` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.completeness) -Included with `mode=min`. +Included with `mode=min` and `mode=max`. Defines if the provenance information is complete. @@ -273,7 +273,7 @@ value can be set by the user with the `reproducible=true` attestation parameter. ## `metadata.https://mobyproject.org/buildkit@v1#hermetic` -Included with `mode=min`. +Included with `mode=min` and `mode=max`. This extension field is set to true if the build was hermetic and did not access the network. In Dockerfiles, a build is hermetic if it does not use `RUN` @@ -314,7 +314,7 @@ for an image or if the build step pulled in image data as part of the build. ### `vcs` -Included with both `mode=min` and `mode=max`. +Included with `mode=min` and `mode=max`. Defines optional metadata for the version control system used for the build. If a build uses a remote context from Git repository, BuildKit extracts the details From 065e6a5938294f3b5cf7368663cdd3ab4b1b9a7b Mon Sep 17 00:00:00 2001 From: Justin Chadwell Date: Thu, 5 Jan 2023 10:49:23 +0000 Subject: [PATCH 08/10] docs: add cross-linking between slsa pages Signed-off-by: Justin Chadwell --- docs/slsa-definitions.md | 3 +++ docs/slsa.md | 7 +++---- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/slsa-definitions.md b/docs/slsa-definitions.md index 9bd7995e6555..ee2fcce4fdff 100644 --- a/docs/slsa-definitions.md +++ b/docs/slsa-definitions.md @@ -1,5 +1,8 @@ # SLSA definitions +BuildKit supports the [creation of SLSA Provenance](./slsa.md) for builds that +it runs. + The provenance format generated by BuildKit is defined by the [SLSA Provenance format](https://slsa.dev/provenance/v0.2). diff --git a/docs/slsa.md b/docs/slsa.md index cab9d94db1b2..a1437e717027 100644 --- a/docs/slsa.md +++ b/docs/slsa.md @@ -1,9 +1,8 @@ # SLSA provenance -BuildKit supports automatic creation of [SLSA Provenance](https://slsa.dev/provenance) -attestations for the build process. Provenance attestations record information describing -how a build was created, and is important for tracking the security of your software -artifacts. +BuildKit supports automatic creation of provenance attestations for the build +process. Provenance attestations record information describing how a build was +created, and is important for tracking the security of your software artifacts. Provenance attestations created by BuildKit include details such as: From 618e8f219a043ec57c1a82f56a1675d537953911 Mon Sep 17 00:00:00 2001 From: Justin Chadwell Date: Thu, 5 Jan 2023 10:56:11 +0000 Subject: [PATCH 09/10] docs: tidy up json examples for slsa definitions Signed-off-by: Justin Chadwell --- docs/slsa-definitions.md | 108 +++++++++++++++++++++++++-------------- 1 file changed, 71 insertions(+), 37 deletions(-) diff --git a/docs/slsa-definitions.md b/docs/slsa-definitions.md index ee2fcce4fdff..e3bf0760783a 100644 --- a/docs/slsa-definitions.md +++ b/docs/slsa-definitions.md @@ -30,7 +30,7 @@ Included with `mode=min` and `mode=max`. The `buildType` field is set to `https://mobyproject.org/buildkit@v1` can be used to determine the structure of the provenance content. -``` +```json "buildType": "https://mobyproject.org/buildkit@v1", ``` @@ -49,6 +49,8 @@ Describes the config that initialized the build. }, "entryPoint": "Dockerfile" }, + ... + }, ``` For builds initialized from a remote context, like a Git or HTTP URL, this @@ -64,7 +66,6 @@ Describes build inputs passed to the build. ```json "invocation": { - ... "parameters": { "frontend": "gateway.v0", "args": { @@ -77,11 +78,14 @@ Describes build inputs passed to the build. { "id": "GIT_AUTH_HEADER", "optional": true - } + }, ... ], "ssh": [], - "locals": [], + "locals": [] + }, + ... + }, ``` The following fields are included with both `mode=min` and `mode=max`: @@ -109,9 +113,12 @@ The following fields are only included with `mode=max`: Included with `mode=min` and `mode=max`. ```json + "invocation": { "environment": { "platform": "linux/amd64" - } + }, + ... + }, ``` The only value BuildKit currently sets is the `platform` of the current build @@ -150,7 +157,7 @@ determine if the artifact has been updated compared to when the build ran. "digest": { "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0" } - } + }, ... ], ``` @@ -171,36 +178,38 @@ field for every step. ```json "buildConfig": { - "llbDefinition": [ - { - "id": "step0", - "op": { - "Op": { - "exec": { - "meta": { - "args": [ - "/bin/sh", - "-c", - "go build ." - ], - "env": [ - "PATH=/go/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", - "GOPATH=/go", - "GOFLAGS=-mod=vendor", - ], - "cwd": "/src", - }, - "mounts": [...] - } - }, - "platform": {...}, + "llbDefinition": [ + { + "id": "step0", + "op": { + "Op": { + "exec": { + "meta": { + "args": [ + "/bin/sh", + "-c", + "go build ." + ], + "env": [ + "PATH=/go/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", + "GOPATH=/go", + "GOFLAGS=-mod=vendor", + ], + "cwd": "/src", + }, + "mounts": [...] + } }, - "inputs": [ - "step8:0", - "step2:0", - ] + "platform": {...}, }, - ... + "inputs": [ + "step8:0", + "step2:0", + ] + }, + ... + ] + }, ``` ## `metadata.buildInvocationId` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildIncocationId) @@ -214,6 +223,8 @@ versions of the image. ```json "metadata": { "buildInvocationID": "rpv7a389uzil5lqmrgwhijwjz", + ... + }, ``` ## `metadata.buildStartedOn` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildStartedOn) @@ -223,7 +234,10 @@ Included with `mode=min` and `mode=max`. Timestamp when the build started. ```json + "metadata": { "buildStartedOn": "2021-11-17T15:00:00Z", + ... + }, ``` ## `metadata.buildFinishedOn` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildFinishedOn) @@ -233,7 +247,10 @@ Included with `mode=min` and `mode=max`. Timestamp when the build finished. ```json + "metadata": { "buildFinishedOn": "2021-11-17T15:01:00Z", + ... + }, ``` ## `metadata.completeness` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.completeness) @@ -257,12 +274,14 @@ repository all materials can be tracked by BuildKit and `completeness.materials` is true. ```json + "metadata": { "completeness": { "parameters": true, "environment": true, "materials": true - } - } + }, + ... + }, ``` ## `metadata.reproducible` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.reproducible) @@ -271,7 +290,10 @@ Defines if the build result is supposed to be byte-by-byte reproducible. This value can be set by the user with the `reproducible=true` attestation parameter. ```json - "reproducible": false + "metadata": { + "reproducible": false, + ... + }, ``` ## `metadata.https://mobyproject.org/buildkit@v1#hermetic` @@ -286,6 +308,7 @@ commands or disables network with `--network=none` flag. "metadata": { "https://mobyproject.org/buildkit@v1#hermetic": true, ... + }, ``` ## `metadata.https://mobyproject.org/buildkit@v1#metadata` @@ -295,6 +318,17 @@ Partially included with `mode=min`. This extension field defines BuildKit-specific additional metadata that is not part of the SLSA provenance spec. +```json + "metadata": { + "https://mobyproject.org/buildkit@v1#metadata": { + "source": {...}, + "layers": {...}, + "vcs": {...}, + }, + ... + }, +``` + ### `source` Only included with `mode=max`. From 5845707046668af551e0f1ee7227fed1e576f7b2 Mon Sep 17 00:00:00 2001 From: Justin Chadwell Date: Thu, 5 Jan 2023 12:37:30 +0000 Subject: [PATCH 10/10] docs: rename slsa.md to slsa-provenance.md Signed-off-by: Justin Chadwell --- docs/slsa-definitions.md | 2 +- docs/{slsa.md => slsa-provenance.md} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/{slsa.md => slsa-provenance.md} (100%) diff --git a/docs/slsa-definitions.md b/docs/slsa-definitions.md index e3bf0760783a..76f25d9847b9 100644 --- a/docs/slsa-definitions.md +++ b/docs/slsa-definitions.md @@ -1,6 +1,6 @@ # SLSA definitions -BuildKit supports the [creation of SLSA Provenance](./slsa.md) for builds that +BuildKit supports the [creation of SLSA Provenance](./slsa-provenance.md) for builds that it runs. The provenance format generated by BuildKit is defined by the diff --git a/docs/slsa.md b/docs/slsa-provenance.md similarity index 100% rename from docs/slsa.md rename to docs/slsa-provenance.md