From 1a2277ab69fd010bfc378886a753cd6847128bfb Mon Sep 17 00:00:00 2001 From: David Karlsson Date: Thu, 22 Dec 2022 11:08:20 +0100 Subject: [PATCH] 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 0000000000000..b0b667fb190e6 --- /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 5f366ff271281..6c2980dd537e0 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 - } - ] - ] - } - } - } - } -} -```