diff --git a/_vendor/github.com/moby/buildkit/docs/attestations/attestation-storage.md b/_vendor/github.com/moby/buildkit/docs/attestations/attestation-storage.md deleted file mode 100644 index a42fab303a5e..000000000000 --- a/_vendor/github.com/moby/buildkit/docs/attestations/attestation-storage.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -title: Image attestation storage ---- - -Buildkit supports creating and attaching attestations to build artifacts. These -attestations can provide valuable information from the build process, -including, but not limited to: [SBOMs](https://en.wikipedia.org/wiki/Software_supply_chain), -[SLSA Provenance](https://slsa.dev/provenance), build logs, etc. - -This document describes the current custom format used to store attestations, -which is designed to be compatible with current registry implementations today. -In the future, we may support exporting attestations in additional formats. - -Attestations are stored as manifest objects in the image index, similar in -style to OCI artifacts. - -## Properties - -### Attestation Manifest - -Attestation manifests are attached to the root image index object, under a -separate [OCI image manifest](https://github.com/opencontainers/image-spec/blob/main/manifest.md). -Each attestation manifest can contain multiple [attestation blobs](#attestation-blob), -with all the of the attestations in a manifest applying to a single platform -manifest. All properties of standard OCI and Docker manifests continue to -apply. - -The image `config` descriptor will point to a valid [image config](https://github.com/opencontainers/image-spec/blob/main/config.md), -however, it will not contain attestation-specific details, and should be -ignored as it is only included for compatibility purposes. - -Each image layer in `layers` will contain a descriptor for a single -[attestation blob](#attestation-blob). The `mediaType` of each layer will be -set in accordance to its contents, one of: - -- `application/vnd.in-toto+json` (currently, the only supported option) - - Indicates an in-toto attestation blob - -Any unknown `mediaType`s should be ignored. - -To assist attestation traversal, the following annotations may be set on each -layer descriptor: - -- `in-toto.io/predicate-type` - - This annotation will be set if the enclosed attestation is an in-toto - attestation (currently, the only supported option). The annotation will - be set to contain the same value as the `predicateType` property present - inside the attestation. - - When present, this annotation may be used to find the specific attestation(s) - they are looking for to avoid pulling the contents of the others. - -### Attestation Blob - -The contents of each layer will be a blob dependent on its `mediaType`. - -- `application/vnd.in-toto+json` - - The blob contents will contain a full [in-toto attestation statement](https://github.com/in-toto/attestation/blob/main/spec/README.md#statement): - - ```json - { - "_type": "https://in-toto.io/Statement/v0.1", - "subject": [ - { - "name": "", - "digest": {"": ""} - }, - ... - ], - "predicateType": "", - "predicate": { ... } - } - ``` - - The subject of the attestation should be set to be the same digest as the - target manifest described in the [Attestation Manifest Descriptor](#attestation-manifest-descriptor), - or some object within. - -### Attestation Manifest Descriptor - -Attestation manifests are attached to the root [image index](https://github.com/opencontainers/image-spec/blob/main/image-index.md), -in the `manifests` key, after all the original runnable manifests. All -properties of standard OCI and Docker manifest descriptors continue to apply. - -To prevent container runtimes from accidentally pulling or running the image -described in the manifest, the `platform` property of the attestation manifest -will be set to `unknown/unknown`, as follows: - -```json -"platform": { - "architecture": "unknown", - "os": "unknown" -} -``` - -To assist index traversal, the following annotations will be set on the -manifest descriptor descriptor: - -- `vnd.docker.reference.type` - - This annotation describes the type of the artifact, and will be set - to `attestation-manifest`. If any other value is specified, the entire - manifest should be ignored. - -- `vnd.docker.reference.digest` - - This annotation will contain the digest of the object in the image index that - the attestation manifest refers to. - - When present, this annotation can be used to find the matching attestation - manifest for a selected image manifest. - -## Examples - -*Example showing an SBOM attestation attached to a `linux/amd64` image* - -#### Image index (`sha256:94acc2ca70c40f3f6291681f37ce9c767e3d251ce01c7e4e9b98ccf148c26260`): - -This image index defines two descriptors: an AMD64 image `sha256:23678f31..` and an attestation manifest `sha256:02cb9aa7..` for that image. - -```json -{ - "mediaType": "application/vnd.oci.image.index.v1+json", - "schemaVersion": 2, - "manifests": [ - { - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "digest": "sha256:23678f31b3b3586c4fb318aecfe64a96a1f0916ba8faf9b2be2abee63fa9e827", - "size": 1234, - "platform": { - "architecture": "amd64", - "os": "linux" - } - }, - { - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "digest": "sha256:02cb9aa7600e73fcf41ee9f0f19cc03122b2d8be43d41ce4b21335118f5dd943", - "size": 1234, - "annotations": { - "vnd.docker.reference.digest": "sha256:23678f31b3b3586c4fb318aecfe64a96a1f0916ba8faf9b2be2abee63fa9e827", - "vnd.docker.reference.type": "attestation-manifest" - }, - "platform": { - "architecture": "unknown", - "os": "unknown" - } - } - ] -} -``` - -#### Attestation manifest (`sha256:02cb9aa7600e73fcf41ee9f0f19cc03122b2d8be43d41ce4b21335118f5dd943`): - -This attestation manifest contains one attestation that is an in-toto attestation that contains a "https://spdx.dev/Document" predicate, signifying that it is defining a SBOM for the image. - -```json -{ - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "schemaVersion": 2, - "config": { - "mediaType": "application/vnd.oci.image.config.v1+json", - "digest": "sha256:a781560066f20ec9c28f2115a95a886e5e71c7c7aa9d8fd680678498b82f3ea3", - "size": 123 - }, - "layers": [ - { - "mediaType": "application/vnd.in-toto+json", - "digest": "sha256:133ae3f9bcc385295b66c2d83b28c25a9f294ce20954d5cf922dda860429734a", - "size": 1234, - "annotations": { - "in-toto.io/predicate-type": "https://spdx.dev/Document" - } - } - ] -} -``` - -#### Image config (`sha256:a781560066f20ec9c28f2115a95a886e5e71c7c7aa9d8fd680678498b82f3ea3`): - -```json -{ - "architecture": "unknown", - "os": "unknown", - "config": {}, - "rootfs": { - "type": "layers", - "diff_ids": [ - "sha256:133ae3f9bcc385295b66c2d83b28c25a9f294ce20954d5cf922dda860429734a" - ] - } -} -``` - -#### Layer content (`sha256:1ea07d5e55eb47ad0e6bbfa2ec180fb580974411e623814e519064c88f022f5c`): - -Attestation body containing the SBOM data listing the packages used during the build in SPDX format. - -```json -{ - "_type": "https://in-toto.io/Statement/v0.1", - "predicateType": "https://spdx.dev/Document", - "subject": [ - { - "name": "_", - "digest": { - "sha256": "23678f31b3b3586c4fb318aecfe64a96a1f0916ba8faf9b2be2abee63fa9e827" - } - } - ], - "predicate": { - "SPDXID": "SPDXRef-DOCUMENT", - "spdxVersion": "SPDX-2.2", - ... -``` diff --git a/_vendor/github.com/moby/buildkit/docs/attestations/slsa-definitions.md b/_vendor/github.com/moby/buildkit/docs/attestations/slsa-definitions.md deleted file mode 100644 index 0053e1e12d28..000000000000 --- a/_vendor/github.com/moby/buildkit/docs/attestations/slsa-definitions.md +++ /dev/null @@ -1,798 +0,0 @@ ---- -title: SLSA definitions ---- - -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 -SLSA Provenance format (supports both [v0.2](https://slsa.dev/spec/v0.2/provenance) -and [v1](https://slsa.dev/spec/v1.1/provenance)). - -This page describes how BuildKit populate each field, and whether the field gets -included when you generate attestations `mode=min` and `mode=max`. - -## SLSA v1 - -### `buildDefinition.buildType` - -* Ref: https://slsa.dev/spec/v1.1/provenance#buildType -* Included with `mode=min` and `mode=max`. - -The `buildDefinition.buildType` field is set to `https://github.com/moby/buildkit/blob/master/docs/attestations/slsa-definitions.md` -and can be used to determine the structure of the provenance content. - -```json - "buildDefinition": { - "buildType": "https://github.com/moby/buildkit/blob/master/docs/attestations/slsa-definitions.md", - ... - } -``` - -### `buildDefinition.externalParameters.configSource` - -* Ref: https://slsa.dev/spec/v1.1/provenance#externalParameters -* Included with `mode=min` and `mode=max`. - -Describes the config that initialized the build. - -```json - "buildDefinition": { - "externalParameters": { - "configSource": { - "uri": "https://github.com/moby/buildkit.git#refs/tags/v0.11.0", - "digest": { - "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0" - }, - "path": "Dockerfile" - }, - ... - }, - } -``` - -For builds initialized from a remote context, like a Git or HTTP URL, this -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 -`path` field defines the path for the frontend file that initialized the build -(`filename` frontend option). - -### `buildDefinition.externalParameters.request` - -* Ref: https://slsa.dev/spec/v1.1/provenance#externalParameters -* Partially included with `mode=min`. - -Describes build inputs passed to the build. - -```json - "buildDefinition": { - "externalParameters": { - "request": { - "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. - -### `buildDefinition.internalParameters.buildConfig` - -* Ref: https://slsa.dev/spec/v1.1/provenance#internalParameters -* 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 the -`buildDefinition.internalParameters.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 - "buildDefinition": { - "internalParameters": { - "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", - ] - }, - ... - ] - }, - } - } -``` - -### `buildDefinition.internalParameters.builderPlatform` - -* Ref: https://slsa.dev/spec/v1.1/provenance#internalParameters -* Included with `mode=min` and `mode=max`. - -```json - "buildDefinition": { - "internalParameters": { - "builderPlatform": "linux/amd64" - ... - }, - } -``` - -BuildKit sets the `builderPlatform` of the build machine. Note that this is not -necessarily the platform of the build result that can be determined from the -`in-toto` subject field. - -### `buildDefinition.resolvedDependencies` - -* Ref: https://slsa.dev/spec/v1.1/provenance#resolvedDependencies -* 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: - -- 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 - "buildDefinition": { - "resolvedDependencies": [ - { - "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" - } - }, - ... - ], - ... - } -``` - -### `runDetails.builder.id` - -* Ref: https://slsa.dev/spec/v1.1/provenance#builder.id -* Included with `mode=min` and `mode=max`. - -The field is set to the URL of the build, if available. - -```json - "runDetails": { - "builder": { - "id": "https://github.com/docker/buildx/actions/runs/3709599520" - ... - }, - ... - } -``` - -> [!NOTE] -> This value can be set using the `builder-id` attestation parameter. - -### `runDetails.metadata.invocationID` - -* Ref: https://slsa.dev/spec/v1.1/provenance#invocationId -* 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 -versions of the image. - -```json - "runDetails": { - "metadata": { - "invocationID": "rpv7a389uzil5lqmrgwhijwjz", - ... - }, - ... - } -``` - -### `runDetails.metadata.startedOn` - -* Ref: https://slsa.dev/spec/v1.1/provenance#startedOn -* Included with `mode=min` and `mode=max`. - -Timestamp when the build started. - -```json - "runDetails": { - "metadata": { - "startedOn": "2021-11-17T15:00:00Z", - ... - }, - ... - } -``` - -### `runDetails.metadata.finishedOn` - -* Ref: https://slsa.dev/spec/v1.1/provenance#finishedOn -* Included with `mode=min` and `mode=max`. - -Timestamp when the build finished. - -```json - "runDetails": { - "metadata": { - "finishedOn": "2021-11-17T15:01:00Z", - ... - }, - } -``` - -### `runDetails.metadata.buildkit_metadata` - -* Ref: https://slsa.dev/spec/v1.1/provenance#extension-fields -* Partially included with `mode=min`. - -This extension field defines BuildKit-specific additional metadata that is not -part of the SLSA provenance spec. - -```json - "runDetails": { - "metadata": { - "buildkit_metadata": { - "source": {...}, - "layers": {...}, - "vcs": {...}, - }, - ... - }, - } -``` - -#### `source` - -Only included with `mode=max`. - -Defines a source mapping of LLB build steps, defined in the -`buildDefinition.internalParameters.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 -`buildDefinition.internalParameters.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 `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 -`buildDefinition.externalParameters.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 `buildDefinition.externalParameters.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. - -### `runDetails.metadata.buildkit_hermetic` - -* Ref: https://slsa.dev/spec/v1.1/provenance#extension-fields -* 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` -commands or disables network with `--network=none` flag. - -```json - "runDetails": { - "metadata": { - "buildkit_hermetic": true, - ... - }, - } -``` - -### `runDetails.metadata.buildkit_completeness` - -* Ref: https://slsa.dev/spec/v1.1/provenance#extension-fields -* Included with `mode=min` and `mode=max`. - -This extension field defines if the provenance information is complete. It is -similar to `metadata.completeness` field in SLSA v0.2. - -`buildkit_completeness.request` is true if all the build arguments are included -in the `buildDefinition.externalParameters.request` field. When building with -`min` mode, the build arguments are not included in the provenance information -and request is not complete. Request is also not complete on direct LLB builds -that did not use a frontend. - -`buildkit_completeness.resolvedDependencies` is true if -`buildDefinition.resolvedDependencies` field includes all the dependencies of -the build. When building from un-tracked source in a local directory, the -dependencies are not complete, while when building from a remote Git repository -all dependencies can be tracked by BuildKit and -`buildkit_completeness.resolvedDependencies` is true. - -```json - "runDetails": { - "metadata": { - "buildkit_completeness": { - "request": true, - "resolvedDependencies": true - }, - ... - }, - } -``` - -### `runDetails.metadata.buildkit_reproducible` - -* Ref: https://slsa.dev/spec/v1.1/provenance#extension-fields -* Included with `mode=min` and `mode=max`. - -This extension field defines if the build result is supposed to be byte-by-byte -reproducible. It is similar to `metadata.reproducible` field in SLSA v0.2. This -value can be set by the user with the `reproducible=true` attestation parameter. - -```json - "runDetails": { - "metadata": { - "buildkit_reproducible": false, - ... - }, - } -``` - -## SLSA v0.2 - -### `builder.id` - -* Ref: https://slsa.dev/spec/v0.2/provenance#builder.id -* Included with `mode=min` and `mode=max`. - -The field is set to the URL of the build, if available. - -```json - "builder": { - "id": "https://github.com/docker/buildx/actions/runs/3709599520" - }, -``` - -> [!NOTE] -> This value can be set using the `builder-id` attestation parameter. - -### `buildType` - -* Ref: https://slsa.dev/spec/v0.2/provenance#buildType -* Included with `mode=min` and `mode=max`. - -The `buildType` field is set to `https://mobyproject.org/buildkit@v1` and can be -used to determine the structure of the provenance content. - -```json - "buildType": "https://mobyproject.org/buildkit@v1", -``` - -### `invocation.configSource` - -* Ref: https://slsa.dev/spec/v0.2/provenance#invocation.configSource -* Included with `mode=min` and `mode=max`. - -Describes the config that initialized the build. - -```json - "invocation": { - "configSource": { - "uri": "https://github.com/moby/buildkit.git#refs/tags/v0.11.0", - "digest": { - "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0" - }, - "entryPoint": "Dockerfile" - }, - ... - }, -``` - -For builds initialized from a remote context, like a Git or HTTP URL, this -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` - -* Ref: https://slsa.dev/spec/v0.2/provenance#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` - -* Ref: https://slsa.dev/spec/v0.2/provenance#invocation.environment -* 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 -machine. Note that this is not necessarily the platform of the build result that -can be determined from the `in-toto` subject field. - -### `materials` - -* Ref: https://slsa.dev/spec/v0.2/provenance#materials -* 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: - -- 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` - -* Ref: https://slsa.dev/spec/v0.2/provenance#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` - -* Ref: https://slsa.dev/spec/v0.2/provenance#buildInvocationId -* 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 -versions of the image. - -```json - "metadata": { - "buildInvocationID": "rpv7a389uzil5lqmrgwhijwjz", - ... - }, -``` - -### `metadata.buildStartedOn` - -* Ref: https://slsa.dev/spec/v0.2/provenance#buildStartedOn -* Included with `mode=min` and `mode=max`. - -Timestamp when the build started. - -```json - "metadata": { - "buildStartedOn": "2021-11-17T15:00:00Z", - ... - }, -``` - -### `metadata.buildFinishedOn` - -* Ref: https://slsa.dev/spec/v0.2/provenance#buildFinishedOn -* Included with `mode=min` and `mode=max`. - -Timestamp when the build finished. - -```json - "metadata": { - "buildFinishedOn": "2021-11-17T15:01:00Z", - ... - }, -``` - -### `metadata.completeness` - -* Ref: https://slsa.dev/spec/v0.2/provenance#metadata.completeness -* Included with `mode=min` and `mode=max`. - -Defines if the provenance information is complete. - -`completeness.parameters` is true if all the build arguments are included in the -`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 - "metadata": { - "completeness": { - "parameters": true, - "environment": true, - "materials": true - }, - ... - }, -``` - -### `metadata.reproducible` - -* Ref: https://slsa.dev/spec/v0.2/provenance#metadata.reproducible -* Included with `mode=min` and `mode=max`. - -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 - "metadata": { - "reproducible": false, - ... - }, -``` - -### `metadata.https://mobyproject.org/buildkit@v1#hermetic` - -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` -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. - -```json - "metadata": { - "https://mobyproject.org/buildkit@v1#metadata": { - "source": {...}, - "layers": {...}, - "vcs": {...}, - }, - ... - }, -``` - -#### `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 `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. diff --git a/_vendor/github.com/moby/buildkit/docs/buildkitd.toml.md b/_vendor/github.com/moby/buildkit/docs/buildkitd.toml.md deleted file mode 100644 index 00eef1ddbcb2..000000000000 --- a/_vendor/github.com/moby/buildkit/docs/buildkitd.toml.md +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: buildkitd.toml ---- - -The TOML file used to configure the buildkitd daemon settings has a short -list of global settings followed by a series of sections for specific areas -of daemon configuration. - -The file path is `/etc/buildkit/buildkitd.toml` for rootful mode, -`~/.config/buildkit/buildkitd.toml` for rootless mode. - -The following is a complete `buildkitd.toml` configuration example. -Note that some configuration options are only useful in edge cases. - -```toml -# debug enables additional debug logging -debug = true -# trace enables additional trace logging (very verbose, with potential performance impacts) -trace = true -# root is where all buildkit state is stored. -root = "/var/lib/buildkit" -# insecure-entitlements allows insecure entitlements, disabled by default. -insecure-entitlements = [ "network.host", "security.insecure", "device" ] -# provenanceEnvDir is the directory where extra config is loaded that is added -# to the provenance of builds: -# slsa v0.2: invocation.environment.* -# slsa v1: buildDefinition.internalParameters.* -provenanceEnvDir = "/etc/buildkit/provenance.d" - -[log] - # log formatter: json or text - format = "text" - -[dns] - nameservers=["1.1.1.1","8.8.8.8"] - options=["edns0"] - searchDomains=["example.com"] - -[grpc] - address = [ "tcp://0.0.0.0:1234" ] - # debugAddress is address for attaching go profiles and debuggers. - debugAddress = "0.0.0.0:6060" - uid = 0 - gid = 0 - [grpc.tls] - cert = "/etc/buildkit/tls.crt" - key = "/etc/buildkit/tls.key" - ca = "/etc/buildkit/tlsca.crt" - -[otel] - # OTEL collector trace socket path - socketPath = "/run/buildkit/otel-grpc.sock" - -[cdi] - # Disables support of the Container Device Interface (CDI). - disabled = true - # List of directories to scan for CDI spec files. For more details about CDI - # specification, please refer to https://github.com/cncf-tags/container-device-interface/blob/main/SPEC.md#cdi-json-specification - specDirs = ["/etc/cdi", "/var/run/cdi", "/etc/buildkit/cdi"] - -# config for build history API that stores information about completed build commands -[history] - # maxAge is the maximum age of history entries to keep, in seconds. - maxAge = 172800 - # maxEntries is the maximum number of history entries to keep. - maxEntries = 50 - -[worker.oci] - enabled = true - # platforms is manually configure platforms, detected automatically if unset. - platforms = [ "linux/amd64", "linux/arm64" ] - snapshotter = "auto" # overlayfs or native, default value is "auto". - rootless = false # see docs/rootless.md for the details on rootless mode. - # Whether run subprocesses in main pid namespace or not, this is useful for - # running rootless buildkit inside a container. - noProcessSandbox = false - # gc enables/disables garbage collection - gc = true - # reservedSpace is the minimum amount of disk space guaranteed to be - # retained by this buildkit worker - any usage below this threshold will not - # be reclaimed during garbage collection. - # all disk space parameters can be an integer number of bytes (e.g. - # 512000000), a string with a unit (e.g. "512MB"), or a string percentage - # of the total disk space (e.g. "10%") - reservedSpace = "30%" - # maxUsedSpace is the maximum amount of disk space that may be used by - # this buildkit worker - any usage above this threshold will be reclaimed - # during garbage collection. - maxUsedSpace = "60%" - # minFreeSpace is the target amount of free disk space that the garbage - # collector will attempt to leave - however, it will never be bought below - # reservedSpace. - minFreeSpace = "20GB" - # alternate OCI worker binary name(example 'crun'), by default either - # buildkit-runc or runc binary is used - binary = "" - # name of the apparmor profile that should be used to constrain build containers. - # the profile should already be loaded (by a higher level system) before creating a worker. - apparmor-profile = "" - # limit the number of parallel build steps that can run at the same time - max-parallelism = 4 - # maintain a pool of reusable CNI network namespaces to amortize the overhead - # of allocating and releasing the namespaces - cniPoolSize = 16 - - [worker.oci.labels] - "foo" = "bar" - - [[worker.oci.gcpolicy]] - # reservedSpace is the minimum amount of disk space guaranteed to be - # retained by this policy - any usage below this threshold will not be - # reclaimed during # garbage collection. - reservedSpace = "512MB" - # maxUsedSpace is the maximum amount of disk space that may be used by this - # policy - any usage above this threshold will be reclaimed during garbage - # collection. - maxUsedSpace = "1GB" - # minFreeSpace is the target amount of free disk space that the garbage - # collector will attempt to leave - however, it will never be bought below - # reservedSpace. - minFreeSpace = "10GB" - # keepDuration can be an integer number of seconds (e.g. 172800), or a - # string duration (e.g. "48h") - keepDuration = "48h" - filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout"] - [[worker.oci.gcpolicy]] - all = true - reservedSpace = 1024000000 - -[worker.containerd] - address = "/run/containerd/containerd.sock" - enabled = true - platforms = [ "linux/amd64", "linux/arm64" ] - namespace = "buildkit" - - # gc enables/disables garbage collection - gc = true - # reservedSpace is the minimum amount of disk space guaranteed to be - # retained by this buildkit worker - any usage below this threshold will not - # be reclaimed during garbage collection. - # all disk space parameters can be an integer number of bytes (e.g. - # 512000000), a string with a unit (e.g. "512MB"), or a string percentage - # of the total disk space (e.g. "10%") - reservedSpace = "30%" - # maxUsedSpace is the maximum amount of disk space that may be used by - # this buildkit worker - any usage above this threshold will be reclaimed - # during garbage collection. - maxUsedSpace = "60%" - # minFreeSpace is the target amount of free disk space that the garbage - # collector will attempt to leave - however, it will never be bought below - # reservedSpace. - minFreeSpace = "20GB" - # limit the number of parallel build steps that can run at the same time - max-parallelism = 4 - # maintain a pool of reusable CNI network namespaces to amortize the overhead - # of allocating and releasing the namespaces - cniPoolSize = 16 - # defaultCgroupParent sets the parent cgroup of all containers. - defaultCgroupParent = "buildkit" - - [worker.containerd.labels] - "foo" = "bar" - - # configure the containerd runtime - [worker.containerd.runtime] - name = "io.containerd.runc.v2" - path = "/path/to/containerd/runc/shim" - options = { BinaryName = "runc" } - - [[worker.containerd.gcpolicy]] - reservedSpace = 512000000 - keepDuration = 172800 - filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout"] - [[worker.containerd.gcpolicy]] - all = true - reservedSpace = 1024000000 - -# registry configures a new Docker register used for cache import or output. -[registry."docker.io"] - # mirror configuration to handle path in case a mirror registry requires a /project path rather than just a host:port - mirrors = ["yourmirror.local:5000", "core.harbor.domain/proxy.docker.io"] - # Use plain HTTP to connect to the mirrors. - http = true - # Use HTTPS with self-signed certificates. Do not enable this together with `http`. - insecure = true - # If you use token auth with self-signed certificates, - # then buildctl also needs to trust the token provider CA (for example, certificates that are configured for registry) - # because buildctl pulls tokens directly without daemon process - ca=["/etc/config/myca.pem"] - [[registry."docker.io".keypair]] - key="/etc/config/key.pem" - cert="/etc/config/cert.pem" - -# optionally mirror configuration can be done by defining it as a registry. -[registry."yourmirror.local:5000"] - http = true - -# Frontend control -[frontend."dockerfile.v0"] - enabled = true - -[frontend."gateway.v0"] - enabled = true - # If allowedRepositories is empty, all gateway sources are allowed. - # Otherwise, only the listed repositories are allowed as a gateway source. - # - # NOTE: Only the repository name (without tag) is compared. - # - # Example: - # allowedRepositories = [ "docker-registry.wikimedia.org/repos/releng/blubber/buildkit" ] - allowedRepositories = [] - -[system] - # how often buildkit scans for changes in the supported emulated platforms - platformsCacheMaxAge = "1h" - - -# optional signed cache configuration for GitHub Actions backend -[ghacache.sign] -# command that signs the payload in stdin and outputs the signature to stdout. Normally you want cosign to produce the signature bytes. -cmd = "" -[ghacache.verify] -required = false -[ghacache.verify.policy] -timestampThreshold = 1 -tlogThreshold = 1 -# cetificate properties that need to match. Simple wildcards (*) are supported. -certificateIssuer = "" -subjectAlternativeName = "" -buildSignerURI = "" -``` diff --git a/content/guides/azure-pipelines.md b/content/guides/azure-pipelines.md index 466638858e96..9abef3dd8634 100644 --- a/content/guides/azure-pipelines.md +++ b/content/guides/azure-pipelines.md @@ -56,9 +56,9 @@ pr: # Define variables for reuse across the pipeline variables: - imageName: 'docker.io/$(dockerUsername)/my-image' - buildTag: '$(Build.BuildId)' - latestTag: 'latest' + imageName: "docker.io/$(dockerUsername)/my-image" + buildTag: "$(Build.BuildId)" + latestTag: "latest" stages: - stage: BuildAndPush @@ -78,7 +78,7 @@ stages: displayName: Docker Login inputs: command: login - containerRegistry: 'my-docker-registry' # Service connection name + containerRegistry: "my-docker-registry" # Service connection name - task: Docker@2 displayName: Build Docker Image @@ -88,7 +88,7 @@ stages: tags: | $(buildTag) $(latestTag) - dockerfile: './Dockerfile' + dockerfile: "./Dockerfile" arguments: | --sbom=true --attest type=provenance @@ -122,10 +122,9 @@ This pipeline automates the Docker image build and deployment process for the ma - Pushes both buildId and latest tags to Docker Hub. - Logs out from Docker if running on a self-hosted Linux agent. - ## How the pipeline works -### Step 1: Define pipeline triggers +### Step 1: Define pipeline triggers ```yaml trigger: @@ -136,6 +135,7 @@ pr: ``` This pipeline is triggered automatically on: + - Commits pushed to the `main` branch - Pull requests targeting `main` main branch @@ -146,9 +146,9 @@ This pipeline is triggered automatically on: ```yaml variables: - imageName: 'docker.io/$(dockerUsername)/my-image' - buildTag: '$(Build.BuildId)' - latestTag: 'latest' + imageName: "docker.io/$(dockerUsername)/my-image" + buildTag: "$(Build.BuildId)" + latestTag: "latest" ``` These variables ensure consistent naming, versioning, and reuse throughout the pipeline steps: @@ -160,12 +160,13 @@ These variables ensure consistent naming, versioning, and reuse throughout the p > [!IMPORTANT] > > The variable `dockerUsername` is not set automatically. -> Set it securely in your Azure DevOps pipeline variables: -> 1. Go to **Pipelines > Edit > Variables** -> 2. Add `dockerUsername` with your Docker Hub username +> Set it securely in your Azure DevOps pipeline variables: +> +> 1. Go to **Pipelines > Edit > Variables** +> 2. Add `dockerUsername` with your Docker Hub username > > Learn more: [Define and use variables in Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/variables?view=azure-devops&tabs=yaml%2Cbatch) - + ### Step 3: Define pipeline stages and jobs ```yaml @@ -180,7 +181,6 @@ This stage executes only if the source branch is `main`. > > Learn more: [Stage conditions in Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/stages?view=azure-devops&tabs=yaml) - ### Step 4: Job configuration ```yaml @@ -220,7 +220,7 @@ This step pulls your repository code into the build agent, so the pipeline can a displayName: Docker Login inputs: command: login - containerRegistry: 'my-docker-registry' # Replace with your service connection name + containerRegistry: "my-docker-registry" # Replace with your service connection name ``` Uses a pre-configured Azure DevOps Docker registry service connection to authenticate securely without exposing credentials directly. @@ -259,9 +259,10 @@ This builds the image with: > [!TIP] > -> Learn more: +> Learn more: +> > - [Docker task for Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/docker-v2?view=azure-pipelines&tabs=yaml) -> - [Docker SBOM Attestations](/manuals/build/metadata/attestations/slsa-provenance.md) +> - [Docker SBOM Attestations](/manuals/build/metadata/provenance.md) #### Step 4.4: Push the Docker image @@ -270,20 +271,21 @@ This builds the image with: displayName: Push Docker Image condition: eq(variables['Build.SourceBranch'], 'refs/heads/main') inputs: - command: push - repository: $(imageName) - tags: | - $(buildTag) - $(latestTag) + command: push + repository: $(imageName) + tags: | + $(buildTag) + $(latestTag) ``` By applying this condition, the pipeline builds the Docker image on every run to ensure early detection of issues, but only pushes the image to the registry when changes are merged into the main branch—keeping your Docker Hub clean and focused This uploads both tags to Docker Hub: + - `$(buildTag)` ensures traceability per run. - `latest` is used for most recent image references. -#### Step 4.5 Logout of Docker (self-hosted agents) +#### Step 4.5 Logout of Docker (self-hosted agents) ```yaml - script: docker logout diff --git a/content/guides/bake/index.md b/content/guides/bake/index.md index 66090381425d..2c4aac7f6eaf 100644 --- a/content/guides/bake/index.md +++ b/content/guides/bake/index.md @@ -78,7 +78,7 @@ line. Here's a quick summary of the options for the `default` target: - `target`: The target build stage in the Dockerfile. - `tags`: Tags to assign to the image. -- `attest`: [Attestations](/manuals/build/metadata/attestations/_index.md) to attach to the image. +- `attest`: [Attestations](/manuals/build/metadata/_index.md) to attach to the image. > [!TIP] > The attestations provide metadata such as build provenance, which tracks diff --git a/content/guides/compose-bake/index.md b/content/guides/compose-bake/index.md index c6f4d312366c..4163aabb93a3 100644 --- a/content/guides/compose-bake/index.md +++ b/content/guides/compose-bake/index.md @@ -160,31 +160,26 @@ represents a single build. { "group": { "default": { - "targets": [ - "vote", - "result", - "worker", - "seed" - ] + "targets": ["vote", "result", "worker", "seed"] } }, "target": { "result": { "context": "result", - "dockerfile": "Dockerfile", + "dockerfile": "Dockerfile" }, "seed": { "context": "seed-data", - "dockerfile": "Dockerfile", + "dockerfile": "Dockerfile" }, "vote": { "context": "vote", "dockerfile": "Dockerfile", - "target": "dev", + "target": "dev" }, "worker": { "context": "worker", - "dockerfile": "Dockerfile", + "dockerfile": "Dockerfile" } } } @@ -323,7 +318,7 @@ are pushed to a registry, it's often a good idea to build for multiple platforms, arm64 and amd64 in particular. Attestations -: [Attestations](/manuals/build/metadata/attestations/_index.md) are manifests +: [Attestations](/manuals/build/metadata/_index.md) are manifests attached to the image that describe how the image was created and what components it contains. Attaching attestations to your images helps ensure that your images follow software supply chain best practices. diff --git a/content/guides/docker-scout/attestations.md b/content/guides/docker-scout/attestations.md index fb060e703363..a67b25d1525d 100644 --- a/content/guides/docker-scout/attestations.md +++ b/content/guides/docker-scout/attestations.md @@ -9,7 +9,7 @@ weight: 50 {{< youtube-embed qOzcycbTs4o >}} -[Build attestations](/manuals/build/metadata/attestations/_index.md) give you +[Build attestations](/manuals/build/metadata/_index.md) give you detailed information about how an image was built and what it contains. These attestations, generated by BuildKit during build-time, attach to the final image as metadata, allowing you to inspect an image to see its origin, creator, diff --git a/content/guides/gha.md b/content/guides/gha.md index 06862c4c328f..0935e6aa57cf 100644 --- a/content/guides/gha.md +++ b/content/guides/gha.md @@ -126,11 +126,11 @@ can push your built image to the registry. To authenticate with Docker Hub, add the following step to your workflow: ```yaml - - name: Log in to Docker Hub - uses: docker/login-action@{{% param "login_action_version" %}} - with: - username: ${{ vars.DOCKER_USERNAME }} - password: ${{ secrets.DOCKER_PASSWORD }} +- name: Log in to Docker Hub + uses: docker/login-action@{{% param "login_action_version" %}} + with: + username: ${{ vars.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_PASSWORD }} ``` This step uses the Docker credentials [configured in the repository settings](#configure-your-github-repository). @@ -141,12 +141,12 @@ Finally, build the final production image and push it to your registry. The following configuration builds the image and pushes it directly to a registry. ```yaml - - name: Build and push Docker image - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - push: ${{ github.event_name != 'pull_request' }} - tags: ${{ steps.meta.outputs.tags }} - annotations: ${{ steps.meta.outputs.annotations }} +- name: Build and push Docker image + uses: docker/build-push-action@{{% param "build_push_action_version" %}} + with: + push: ${{ github.event_name != 'pull_request' }} + tags: ${{ steps.meta.outputs.tags }} + annotations: ${{ steps.meta.outputs.annotations }} ``` In this configuration: @@ -181,21 +181,21 @@ workflow: Here's the updated snippet: ```yaml - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - - - name: Build and push Docker image - uses: docker/build-push-action@{{% param "build_push_action_version" %}} - with: - push: ${{ github.event_name != 'pull_request' }} - tags: ${{ steps.meta.outputs.tags }} - annotations: ${{ steps.meta.outputs.annotations }} - provenance: true - sbom: true +- name: Set up Docker Buildx + uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} + +- name: Build and push Docker image + uses: docker/build-push-action@{{% param "build_push_action_version" %}} + with: + push: ${{ github.event_name != 'pull_request' }} + tags: ${{ steps.meta.outputs.tags }} + annotations: ${{ steps.meta.outputs.annotations }} + provenance: true + sbom: true ``` For more details about attestations, refer to -[the documentation](/manuals/build/metadata/attestations/_index.md). +[the documentation](/manuals/build/metadata/_index.md). ## Conclusion @@ -232,7 +232,7 @@ jobs: - name: Set up Docker Buildx uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - + - name: Build and push Docker image uses: docker/build-push-action@{{% param "build_push_action_version" %}} with: diff --git a/content/guides/lab-attestation-basics.md b/content/guides/lab-attestation-basics.md index 4c3ef50d9b99..22ff324ee252 100644 --- a/content/guides/lab-attestation-basics.md +++ b/content/guides/lab-attestation-basics.md @@ -14,11 +14,11 @@ params: time: 45 minutes resource_links: - title: Build attestations - url: /build/metadata/attestations/ + url: /build/metadata/ - title: SBOM attestations - url: /build/metadata/attestations/sbom/ + url: /build/metadata/sbom/ - title: Provenance attestations - url: /build/metadata/attestations/slsa-provenance/ + url: /build/metadata/provenance/ - title: Labspace repository url: https://github.com/dockersamples/labspace-attestation-basics --- diff --git a/content/guides/lab-dhi-node.md b/content/guides/lab-dhi-node.md index 3e775b7e3a9d..2a269ea45290 100644 --- a/content/guides/lab-dhi-node.md +++ b/content/guides/lab-dhi-node.md @@ -19,7 +19,7 @@ params: - title: Docker Scout docs url: /scout/ - title: Build attestations - url: /build/metadata/attestations/ + url: /build/metadata/ - title: Labspace repository url: https://github.com/dockersamples/labspace-dhi-node --- diff --git a/content/manuals/build/building/variables.md b/content/manuals/build/building/variables.md index db41b830f035..0dc492450f64 100644 --- a/content/manuals/build/building/variables.md +++ b/content/manuals/build/building/variables.md @@ -5,9 +5,9 @@ weight: 20 description: Using build arguments and environment variables to configure builds keywords: build, args, variables, parameters, env, environment variables, config aliases: -- /build/buildkit/color-output-controls/ -- /build/building/env-vars/ -- /build/guide/build-args/ + - /build/buildkit/color-output-controls/ + - /build/building/env-vars/ + - /build/guide/build-args/ --- In Docker Build, build arguments (`ARG`) and environment variables (`ENV`) @@ -304,30 +304,30 @@ Note that these variables aren't used to configure the build container; they aren't available inside the build and they have no relation to the `ENV` instruction. They're used to configure the Buildx client, or the BuildKit daemon. -| Variable | Type | Description | -|-----------------------------------------------------------------------------|-------------------|------------------------------------------------------------------| -| [BUILDKIT_COLORS](#buildkit_colors) | String | Configure text color for the terminal output. | -| [BUILDKIT_HOST](#buildkit_host) | String | Specify host to use for remote builders. | -| [BUILDKIT_PROGRESS](#buildkit_progress) | String | Configure type of progress output. | -| [BUILDKIT_TTY_LOG_LINES](#buildkit_tty_log_lines) | String | Number of log lines (for active steps in TTY mode). | -| [BUILDX_BAKE_FILE](#buildx_bake_file) | String | Specify the build definition file(s) for `docker buildx bake`. | -| [BUILDX_BAKE_FILE_SEPARATOR](#buildx_bake_file_separator) | String | Specify the file-path separator for `BUILDX_BAKE_FILE`. | -| [BUILDX_BAKE_GIT_AUTH_HEADER](#buildx_bake_git_auth_header) | String | HTTP authentication scheme for remote Bake files. | -| [BUILDX_BAKE_GIT_AUTH_TOKEN](#buildx_bake_git_auth_token) | String | HTTP authentication token for remote Bake files. | -| [BUILDX_BAKE_GIT_SSH](#buildx_bake_git_ssh) | String | SSH authentication for remote Bake files. | -| [BUILDX_BUILDER](#buildx_builder) | String | Specify the builder instance to use. | -| [BUILDX_CONFIG](#buildx_config) | String | Specify location for configuration, state, and logs. | -| [BUILDX_CPU_PROFILE](#buildx_cpu_profile) | String | Generate a `pprof` CPU profile at the specified location. | -| [BUILDX_EXPERIMENTAL](#buildx_experimental) | Boolean | Turn on experimental features. | -| [BUILDX_GIT_CHECK_DIRTY](#buildx_git_check_dirty) | Boolean | Enable dirty Git checkout detection. | -| [BUILDX_GIT_INFO](#buildx_git_info) | Boolean | Remove Git information in provenance attestations. | -| [BUILDX_GIT_LABELS](#buildx_git_labels) | String \| Boolean | Add Git provenance labels to images. | -| [BUILDX_MEM_PROFILE](#buildx_mem_profile) | String | Generate a `pprof` memory profile at the specified location. | -| [BUILDX_METADATA_PROVENANCE](#buildx_metadata_provenance) | String \| Boolean | Customize provenance information included in the metadata file. | -| [BUILDX_METADATA_WARNINGS](#buildx_metadata_warnings) | String | Include build warnings in the metadata file. | -| [BUILDX_NO_DEFAULT_ATTESTATIONS](#buildx_no_default_attestations) | Boolean | Turn off default provenance attestations. | -| [BUILDX_NO_DEFAULT_LOAD](#buildx_no_default_load) | Boolean | Turn off loading images to image store by default. | -| [EXPERIMENTAL_BUILDKIT_SOURCE_POLICY](#experimental_buildkit_source_policy) | String | Specify a BuildKit source policy file. | +| Variable | Type | Description | +| --------------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------- | +| [BUILDKIT_COLORS](#buildkit_colors) | String | Configure text color for the terminal output. | +| [BUILDKIT_HOST](#buildkit_host) | String | Specify host to use for remote builders. | +| [BUILDKIT_PROGRESS](#buildkit_progress) | String | Configure type of progress output. | +| [BUILDKIT_TTY_LOG_LINES](#buildkit_tty_log_lines) | String | Number of log lines (for active steps in TTY mode). | +| [BUILDX_BAKE_FILE](#buildx_bake_file) | String | Specify the build definition file(s) for `docker buildx bake`. | +| [BUILDX_BAKE_FILE_SEPARATOR](#buildx_bake_file_separator) | String | Specify the file-path separator for `BUILDX_BAKE_FILE`. | +| [BUILDX_BAKE_GIT_AUTH_HEADER](#buildx_bake_git_auth_header) | String | HTTP authentication scheme for remote Bake files. | +| [BUILDX_BAKE_GIT_AUTH_TOKEN](#buildx_bake_git_auth_token) | String | HTTP authentication token for remote Bake files. | +| [BUILDX_BAKE_GIT_SSH](#buildx_bake_git_ssh) | String | SSH authentication for remote Bake files. | +| [BUILDX_BUILDER](#buildx_builder) | String | Specify the builder instance to use. | +| [BUILDX_CONFIG](#buildx_config) | String | Specify location for configuration, state, and logs. | +| [BUILDX_CPU_PROFILE](#buildx_cpu_profile) | String | Generate a `pprof` CPU profile at the specified location. | +| [BUILDX_EXPERIMENTAL](#buildx_experimental) | Boolean | Turn on experimental features. | +| [BUILDX_GIT_CHECK_DIRTY](#buildx_git_check_dirty) | Boolean | Enable dirty Git checkout detection. | +| [BUILDX_GIT_INFO](#buildx_git_info) | Boolean | Remove Git information in provenance attestations. | +| [BUILDX_GIT_LABELS](#buildx_git_labels) | String \| Boolean | Add Git provenance labels to images. | +| [BUILDX_MEM_PROFILE](#buildx_mem_profile) | String | Generate a `pprof` memory profile at the specified location. | +| [BUILDX_METADATA_PROVENANCE](#buildx_metadata_provenance) | String \| Boolean | Customize provenance information included in the metadata file. | +| [BUILDX_METADATA_WARNINGS](#buildx_metadata_warnings) | String | Include build warnings in the metadata file. | +| [BUILDX_NO_DEFAULT_ATTESTATIONS](#buildx_no_default_attestations) | Boolean | Turn off default provenance attestations. | +| [BUILDX_NO_DEFAULT_LOAD](#buildx_no_default_load) | Boolean | Turn off loading images to image store by default. | +| [EXPERIMENTAL_BUILDKIT_SOURCE_POLICY](#experimental_buildkit_source_policy) | String | Specify a BuildKit source policy file. | BuildKit also supports a few additional configuration parameters. Refer to [BuildKit built-in build args](/reference/dockerfile.md#buildkit-built-in-build-args). @@ -428,7 +428,9 @@ Example: "identifier": "https://raw.githubusercontent.com/moby/buildkit/v0.10.1/README.md" }, "updates": { - "attrs": {"http.checksum": "sha256:6e4b94fc270e708e1068be28bd3551dc6917a4fc5a61293d51bb36e6b75c4b53"} + "attrs": { + "http.checksum": "sha256:6e4b94fc270e708e1068be28bd3551dc6917a4fc5a61293d51bb36e6b75c4b53" + } } }, { @@ -445,7 +447,7 @@ Example: {{< summary-bar feature_name="Buildx bake file" >}} -Specify one or more build definition files for `docker buildx bake`. +Specify one or more build definition files for `docker buildx bake`. This environment variable provides an alternative to the `-f` / `--file` command-line flag. @@ -462,7 +464,7 @@ export BUILDX_BAKE_FILE_SEPARATOR=@ export BUILDX_BAKE_FILE=file1.hcl@file2.hcl ``` -If both `BUILDX_BAKE_FILE` and the `-f` flag are set, only the files provided via `-f` are used. +If both `BUILDX_BAKE_FILE` and the `-f` flag are set, only the files provided via `-f` are used. If a listed file does not exist or is invalid, bake returns an error. @@ -470,7 +472,7 @@ If a listed file does not exist or is invalid, bake returns an error. {{< summary-bar feature_name="Buildx bake file separator" >}} -Controls the separator used between file paths in the `BUILDX_BAKE_FILE` environment variable. +Controls the separator used between file paths in the `BUILDX_BAKE_FILE` environment variable. This is useful if your file paths contain the default separator character or if you want to standardize separators across different platforms. @@ -584,7 +586,7 @@ $ export BUILDX_EXPERIMENTAL=1 {{< summary-bar feature_name="Buildx Git check dirty" >}} When set to true, checks for dirty state in source control information for -[provenance attestations](/manuals/build/metadata/attestations/slsa-provenance.md). +[provenance attestations](/manuals/build/metadata/provenance.md). Usage: @@ -597,7 +599,7 @@ $ export BUILDX_GIT_CHECK_DIRTY=1 {{< summary-bar feature_name="Buildx Git info" >}} When set to false, removes source control information from -[provenance attestations](/manuals/build/metadata/attestations/slsa-provenance.md). +[provenance attestations](/manuals/build/metadata/provenance.md). Usage: @@ -659,9 +661,10 @@ By default, Buildx includes minimal provenance information in the metadata file through [`--metadata-file` flag](/reference/cli/docker/buildx/build/#metadata-file). This environment variable allows you to customize the provenance information included in the metadata file: -* `min` sets minimal provenance (default). -* `max` sets full provenance. -* `disabled`, `false` or `0` does not set any provenance. + +- `min` sets minimal provenance (default). +- `max` sets full provenance. +- `disabled`, `false` or `0` does not set any provenance. ### BUILDX_METADATA_WARNINGS @@ -676,7 +679,7 @@ You can set this environment variable to `1` or `true` to include them. {{< summary-bar feature_name="Buildx no default" >}} By default, BuildKit v0.11 and later adds -[provenance attestations](/manuals/build/metadata/attestations/slsa-provenance.md) to images you +[provenance attestations](/manuals/build/metadata/provenance.md) to images you build. Set `BUILDX_NO_DEFAULT_ATTESTATIONS=1` to disable the default provenance attestations. diff --git a/content/manuals/build/buildkit/configure.md b/content/manuals/build/buildkit/configure.md index c05b2b2dbd0c..00afc6229072 100644 --- a/content/manuals/build/buildkit/configure.md +++ b/content/manuals/build/buildkit/configure.md @@ -5,7 +5,7 @@ keywords: build, buildkit, configuration, buildx, network, cni, registry --- If you create a `docker-container` or `kubernetes` builder with Buildx, you can -apply a custom [BuildKit configuration](toml-configuration.md) by passing the +apply a custom [BuildKit configuration](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md) by passing the [`--buildkitd-config` flag](/reference/cli/docker/buildx/create/#buildkitd-config) to the `docker buildx create` command. @@ -182,7 +182,7 @@ $ docker buildx create --use --bootstrap \ ### Max parallelism You can limit the parallelism of the BuildKit solver, which is particularly useful -for low-powered machines, using a [BuildKit configuration](toml-configuration.md) +for low-powered machines, using a [BuildKit configuration](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md) while creating a builder with the [`--buildkitd-config` flag](/reference/cli/docker/buildx/create/#buildkitd-config). ```toml diff --git a/content/manuals/build/cache/garbage-collection.md b/content/manuals/build/cache/garbage-collection.md index 7609bab11a08..a76fdeb7bc29 100644 --- a/content/manuals/build/cache/garbage-collection.md +++ b/content/manuals/build/cache/garbage-collection.md @@ -171,7 +171,7 @@ following policies: > `==`: > > | `daemon.json` | `buildkitd.toml` | -> |---------------------|----------------------| +> | ------------------- | -------------------- | > | `type=source.local` | `type==source.local` | > | `private=true` | `private==true` | > | `shared=true` | `shared==true` | @@ -183,7 +183,7 @@ following policies: ### BuildKit configuration file For build drivers other than `docker`, GC is configured using a -[`buildkitd.toml`](../buildkit/toml-configuration.md) configuration file. This +[`buildkitd.toml`](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md) configuration file. This file uses the following high-level configuration options that you can use to tweak the thresholds for how much disk space BuildKit should use for cache: diff --git a/content/manuals/build/ci/github-actions/attestations.md b/content/manuals/build/ci/github-actions/attestations.md index 75a1c822b72e..c889c60c12f7 100644 --- a/content/manuals/build/ci/github-actions/attestations.md +++ b/content/manuals/build/ci/github-actions/attestations.md @@ -6,7 +6,7 @@ keywords: ci, github actions, gha, buildkit, buildx, attestations, sbom, provena --- Software Bill of Material (SBOM) and provenance -[attestations](../../metadata/attestations/_index.md) add metadata about the contents of +[attestations](../../metadata/_index.md) add metadata about the contents of your image, and how it was built. Attestations are supported with version 4 and later of the @@ -67,7 +67,7 @@ jobs: with: username: ${{ vars.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - + - name: Set up Docker Buildx uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} diff --git a/content/manuals/build/ci/github-actions/configure-builder.md b/content/manuals/build/ci/github-actions/configure-builder.md index 9ba29245364d..594970addeff 100644 --- a/content/manuals/build/ci/github-actions/configure-builder.md +++ b/content/manuals/build/ci/github-actions/configure-builder.md @@ -54,7 +54,7 @@ jobs: uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} with: buildkitd-flags: --debug - + - name: Build uses: docker/build-push-action@{{% param "build_push_action_version" %}} ``` @@ -65,7 +65,7 @@ Logs will be available at the end of a job: ## BuildKit Daemon configuration -You can provide a [BuildKit configuration](../../buildkit/toml-configuration.md) +You can provide a [BuildKit configuration](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md) to your builder if you're using the [`docker-container` driver](/manuals/build/builders/drivers/docker-container.md) (default) with the `config` or `buildkitd-config-inline` inputs: @@ -138,8 +138,8 @@ It takes input in the form of a YAML string document to remove limitations intrinsically linked to GitHub Actions: you can only use strings in the input fields: -| Name | Type | Description | -| ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Name | Type | Description | +| ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | String | [Name of the node](/reference/cli/docker/buildx/create/#node). If empty, it's the name of the builder it belongs to, with an index number suffix. This is useful to set it if you want to modify/remove a node in an underlying step of you workflow. | | `endpoint` | String | [Docker context or endpoint](/reference/cli/docker/buildx/create/#description) of the node to add to the builder | | `driver-opts` | List | List of additional [driver-specific options](/reference/cli/docker/buildx/create/#driver-opt) | @@ -207,7 +207,7 @@ jobs: host: graviton2 private-key: ${{ secrets.SSH_PRIVATE_KEY }} private-key-name: aws_graviton2 - + - name: Set up Docker Buildx uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} with: @@ -267,12 +267,12 @@ jobs: steps: - name: Checkout uses: actions/checkout@{{% param "checkout_action_version" %}} - + - name: Set up Docker Buildx uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} with: driver: kubernetes - + - name: Build run: | buildx build . @@ -305,17 +305,17 @@ jobs: - name: Set up builder1 uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} id: builder1 - + - name: Set up builder2 uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} id: builder2 - + - name: Build against builder1 uses: docker/build-push-action@{{% param "build_push_action_version" %}} with: builder: ${{ steps.builder1.outputs.name }} target: mytarget1 - + - name: Build against builder2 uses: docker/build-push-action@{{% param "build_push_action_version" %}} with: diff --git a/content/manuals/build/ci/github-actions/github-builder/_index.md b/content/manuals/build/ci/github-actions/github-builder/_index.md index 4322d7968805..f4b1e7d9bbdb 100644 --- a/content/manuals/build/ci/github-actions/github-builder/_index.md +++ b/content/manuals/build/ci/github-actions/github-builder/_index.md @@ -42,10 +42,10 @@ jobs: - name: Set up QEMU uses: docker/setup-qemu-action@{{% param "setup_qemu_action_version" %}} - + - name: Set up Docker Buildx uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}} - + - name: Docker meta uses: docker/metadata-action@{{% param "metadata_action_version" %}} id: meta @@ -85,7 +85,7 @@ jobs: This model gives you a build pipeline that is maintained in the Docker organization, uses a pinned [BuildKit](../../../buildkit/_index.md) environment, distributes [multi-platform builds](../../../building/multi-platform.md) across -runners when that helps, and emits signed [SLSA provenance](../../../metadata/attestations/slsa-provenance.md) +runners when that helps, and emits signed [SLSA provenance](../../../metadata/provenance.md) that records both the source commit and the builder identity. That tradeoff is intentional. You keep control of when the build runs and which @@ -100,7 +100,7 @@ overrides, and variables to stay as the source of truth. Both workflows support image output, local output, cache export to the [GitHub Actions cache backend](../../../cache/backends/gha.md), -[SBOM generation](../../../metadata/attestations/sbom.md), and signing. The +[SBOM generation](../../../metadata/sbom.md), and signing. The Bake workflow adds Bake definition validation and builds one target per workflow call. diff --git a/content/manuals/build/ci/github-actions/github-builder/bake.md b/content/manuals/build/ci/github-actions/github-builder/bake.md index 6934baec8c93..e904e03e7906 100644 --- a/content/manuals/build/ci/github-actions/github-builder/bake.md +++ b/content/manuals/build/ci/github-actions/github-builder/bake.md @@ -107,7 +107,7 @@ jobs: This form fits repositories that already use Bake groups, target inheritance, and variable expansion. The reusable workflow takes care of Buildx setup, [GitHub Actions cache export](../../../cache/backends/gha.md), -[Provenance defaults](../../../metadata/attestations/slsa-provenance.md), +[Provenance defaults](../../../metadata/provenance.md), signing behavior, and the final multi-platform manifest. Metadata labels and annotations can be merged into the Bake definition without adding a separate metadata step to your workflow. diff --git a/content/manuals/build/ci/github-actions/github-builder/build.md b/content/manuals/build/ci/github-actions/github-builder/build.md index 202739fb58c8..3e891d8e4d50 100644 --- a/content/manuals/build/ci/github-actions/github-builder/build.md +++ b/content/manuals/build/ci/github-actions/github-builder/build.md @@ -143,7 +143,7 @@ jobs: This is a Dockerfile build, so the inputs map closely to `docker/build-push-action`. The difference is that the reusable workflow owns Buildx setup, [BuildKit](../../../buildkit/_index.md) configuration, -[SLSA provenance](../../../metadata/attestations/slsa-provenance.md) mode, +[SLSA provenance](../../../metadata/provenance.md) mode, [GitHub Actions cache backend](../../../cache/backends/gha.md) wiring, signing, and manifest creation. If you need more background on metadata or platform distribution, see [Manage tags and labels](../manage-tags-labels.md) and diff --git a/content/manuals/build/exporters/image-registry.md b/content/manuals/build/exporters/image-registry.md index 159be14265fa..6c54f5fde77c 100644 --- a/content/manuals/build/exporters/image-registry.md +++ b/content/manuals/build/exporters/image-registry.md @@ -46,7 +46,7 @@ The following table describes the available parameters that you can pass to [2]: _index.md#oci-media-types [3]: #annotations [4]: https://github.com/moby/buildkit/blob/master/docs/build-repro.md -[5]: /manuals/build/metadata/attestations/_index.md#attestations-as-oci-artifacts +[5]: /manuals/build/metadata/_index.md#attestations-as-oci-artifacts ## Annotations diff --git a/content/manuals/build/metadata/_index.md b/content/manuals/build/metadata/_index.md index 05370d42ddb2..3d1ffcae59f6 100644 --- a/content/manuals/build/metadata/_index.md +++ b/content/manuals/build/metadata/_index.md @@ -1,6 +1,224 @@ --- -build: - render: never -title: Metadata +title: Build metadata +keywords: build, metadata, annotations, attestations, sbom, provenance +description: | + Attach metadata to images built with BuildKit, including annotations, SBOM + attestations, and provenance attestations. weight: 80 +aliases: + - /build/attestations/ + - /build/metadata/attestations/ --- + +BuildKit can attach metadata to images as part of the build. Build metadata +describes the image and how it was built, and lets downstream tools understand +its contents, origin, and intended use. + +Docker Build produces two kinds of metadata: + +- [Annotations](annotations.md): descriptive key-value metadata attached to OCI + image components, like manifests and indexes. Use annotations to record + arbitrary information about an image. +- Attestations: signed statements about the build, attached to the image as + manifests. BuildKit produces two types of build attestation: + - [SBOM attestations](sbom.md): describe the software artifacts an image + contains, and the artifacts used to build the image. + - [Provenance attestations](provenance.md): describe how the image was + built. + +For the concept of attestations — what they are and why they matter — see +[Attestations](/manuals/dhi/core-concepts/attestations.md) in the Docker +Hardened Images documentation. + +## Create attestations + +Provenance attestations at the `mode=min` level are added to images by +default. You can customize attestation behavior using the `--provenance` and +`--sbom` flags: + +```bash +# Opt in to SBOM attestations: +docker buildx build --sbom=true . +# Opt in to max-level provenance attestations: +docker buildx build --provenance=mode=max . +# Opt out of provenance attestations: +docker buildx build --provenance=false . +``` + +You can also disable default provenance attestations by setting the +[`BUILDX_NO_DEFAULT_ATTESTATIONS`](/manuals/build/building/variables.md#buildx_no_default_attestations) +environment variable. See [Provenance attestations](provenance.md) for +more details about provenance modes and options. + +## Storage + +BuildKit produces attestations in the [in-toto format](https://github.com/in-toto/attestation), +as defined by the [in-toto framework](https://in-toto.io/), +a standard supported by the Linux Foundation. + +Attestations attach to images as a manifest in the image index. The data records +of the attestations are stored as JSON blobs. + +Because attestations attach to images as a manifest, it means that you can +inspect the attestations for any image in a registry without having to pull the +whole image. + +All BuildKit exporters support attestations. The `local` and `tar` can't save +the attestations to an image manifest, since it's outputting a directory of +files or a tarball, not an image. Instead, these exporters write the +attestations to one or more JSON files in the root directory of the export. + +## Example + +The following example shows a truncated in-toto JSON representation of an SBOM +attestation. + +```json +{ + "_type": "https://in-toto.io/Statement/v0.1", + "predicateType": "https://spdx.dev/Document", + "subject": [ + { + "name": "pkg:docker//@?platform=", + "digest": { + "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862" + } + } + ], + "predicate": { + "SPDXID": "SPDXRef-DOCUMENT", + "creationInfo": { + "created": "2022-12-15T11:47:54.546747383Z", + "creators": ["Organization: Anchore, Inc", "Tool: syft-v0.60.3"], + "licenseListVersion": "3.18" + }, + "dataLicense": "CC0-1.0", + "documentNamespace": "https://anchore.com/syft/dir/run/src/core-da0f600b-7f0a-4de0-8432-f83703e6bc4f", + "name": "/run/src/core", + // list of files that the image contains, e.g.: + "files": [ + { + "SPDXID": "SPDXRef-1ac501c94e2f9f81", + "comment": "layerID: sha256:9b18e9b68314027565b90ff6189d65942c0f7986da80df008b8431276885218e", + "fileName": "/bin/busybox", + "licenseConcluded": "NOASSERTION" + } + ], + // list of packages that were identified for this image: + "packages": [ + { + "name": "busybox", + "originator": "Person: Sören Tempel ", + "sourceInfo": "acquired package info from APK DB: lib/apk/db/installed", + "versionInfo": "1.35.0-r17", + "SPDXID": "SPDXRef-980737451f148c56", + "description": "Size optimized toolbox of many common UNIX utilities", + "downloadLocation": "https://busybox.net/", + "licenseConcluded": "GPL-2.0-only", + "licenseDeclared": "GPL-2.0-only" + // ... + } + ], + // files-packages relationship + "relationships": [ + { + "relatedSpdxElement": "SPDXRef-1ac501c94e2f9f81", + "relationshipType": "CONTAINS", + "spdxElementId": "SPDXRef-980737451f148c56" + }, + ... + ], + "spdxVersion": "SPDX-2.2" + } +} +``` + +To deep-dive into the specifics about how attestations are stored, see +[Image Attestation Storage](https://github.com/moby/buildkit/blob/master/docs/attestations/attestation-storage.md) +in the BuildKit documentation. + +## Attestation manifest format + +Attestations are stored as manifests, referenced by the image's index. Each +_attestation manifest_ refers to a single _image manifest_ (one +platform-variant of the image). Attestation manifests contain a single layer, +the "value" of the attestation. + +The following example shows the structure of an attestation manifest: + +```json +{ + "schemaVersion": 2, + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "config": { + "mediaType": "application/vnd.oci.image.config.v1+json", + "size": 167, + "digest": "sha256:916d7437a36dd0e258e64d9c5a373ca5c9618eeb1555e79bd82066e593f9afae" + }, + "layers": [ + { + "mediaType": "application/vnd.in-toto+json", + "size": 1833349, + "digest": "sha256:3138024b98ed5aa8e3008285a458cd25a987202f2500ce1a9d07d8e1420f5491", + "annotations": { + "in-toto.io/predicate-type": "https://spdx.dev/Document" + } + } + ] +} +``` + +### Attestations as OCI artifacts + +You can configure the format of the attestation manifest using the +[`oci-artifact` option](/manuals/build/exporters/image-registry.md#synopsis) +for the `image` and `registry` exporters. If set to `true`, the structure of +the attestation manifest changes as follows: + +- An `artifactType` field is added to the attestation manifest, with a value of `application/vnd.docker.attestation.manifest.v1+json`. +- The `config` field is an [empty descriptor] instead of a "dummy" config. +- A `subject` field is also added, pointing to the image manifest that the attestation refers to. + +[empty descriptor]: https://github.com/opencontainers/image-spec/blob/main/manifest.md#guidance-for-an-empty-descriptor + +The following example shows an attestation with the OCI artifact format: + +```json +{ + "schemaVersion": 2, + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "artifactType": "application/vnd.docker.attestation.manifest.v1+json", + "config": { + "mediaType": "application/vnd.oci.empty.v1+json", + "size": 2, + "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a", + "data": "e30=" + }, + "layers": [ + { + "mediaType": "application/vnd.in-toto+json", + "size": 2208, + "digest": "sha256:6d2f2c714a6bee3cf9e4d3cb9a966b629efea2dd8556ed81f19bd597b3325286", + "annotations": { + "in-toto.io/predicate-type": "https://slsa.dev/provenance/v0.2" + } + } + ], + "subject": { + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "size": 1054, + "digest": "sha256:bc2046336420a2852ecf915786c20f73c4c1b50d7803aae1fd30c971a7d1cead", + "platform": { + "architecture": "amd64", + "os": "linux" + } + } +} +``` + +## What's next + +Learn more about the available attestation types and how to use them: + +- [Provenance attestations](provenance.md) +- [SBOM attestations](sbom.md) diff --git a/content/manuals/build/metadata/annotations.md b/content/manuals/build/metadata/annotations.md index ee1f44a488f0..a1d2b3879471 100644 --- a/content/manuals/build/metadata/annotations.md +++ b/content/manuals/build/metadata/annotations.md @@ -3,7 +3,7 @@ title: Annotations description: Annotations specify additional metadata about OCI images keywords: build, buildkit, annotations, metadata aliases: -- /build/building/annotations/ + - /build/building/annotations/ --- @@ -153,7 +153,7 @@ The following types are supported: - `manifest`: annotates manifests. - `index`: annotates the root index. - `manifest-descriptor`: annotates manifest descriptors in the index. -- `index-descriptor`: annotates the index descriptor in the image layout. +- `index-descriptor`: annotates the index descriptor in the image layout. For example, to build an image with the annotation `foo=bar` attached to the image index: @@ -211,7 +211,7 @@ Reference information: [specification]: https://github.com/opencontainers/image-spec/blob/main/annotations.md -[attestations]: /manuals/build/metadata/attestations/_index.md +[attestations]: /manuals/build/metadata/_index.md [config]: https://github.com/opencontainers/image-spec/blob/main/config.md [descriptors]: https://github.com/opencontainers/image-spec/blob/main/descriptor.md [indexes]: https://github.com/opencontainers/image-spec/blob/main/image-index.md diff --git a/content/manuals/build/metadata/attestations/_index.md b/content/manuals/build/metadata/attestations/_index.md deleted file mode 100644 index 2d7959f3543f..000000000000 --- a/content/manuals/build/metadata/attestations/_index.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: Build attestations -keywords: build, attestations, sbom, provenance, metadata -description: | - Introduction to SBOM and provenance attestations with Docker Build, - what they are, and why they exist -aliases: - - /build/attestations/ ---- - -{{< youtube-embed qOzcycbTs4o >}} - -Build attestations describe how an image was built, and what it contains. The -attestations are created at build-time by BuildKit, and become attached to the -final image as metadata. - -The purpose of attestations is to make it possible to inspect an image and see -where it comes from, who created it and how, and what it contains. This enables -you to make informed decisions about how an image impacts the supply chain security -of your application. It also enables the use of policy engines for validating -images based on policy rules you've defined. - -Two types of build attestations are available: - -- Software Bill of Material (SBOM): list of software artifacts that an image - contains, or that were used to build the image. -- Provenance: how an image was built. - -## Purpose of attestations - -The use of open source and third-party packages is more widespread than ever -before. Developers share and reuse code because it helps increase productivity, -allowing teams to create better products, faster. - -Importing and using code created elsewhere without vetting it introduces a -severe security risk. Even if you do review the software that you consume, new -zero-day vulnerabilities are frequently discovered, requiring development teams -take action to remediate them. - -Build attestations make it easier to see the contents of an image, and where it -comes from. Use attestations to analyze and decide whether to use an image, or -to see if images you are already using are exposed to vulnerabilities. - -## Creating attestations - -BuildKit generates the attestations when building the image. Provenance -attestations with the `mode=min` level are added to images by default. The -attestation records are wrapped in the in-toto JSON format and attached to the -image index in a manifest for the final image. - -You can customize attestation behavior using the `--provenance` and `--sbom` -flags: - -```bash -# Opt in to SBOM attestations: -docker buildx build --sbom=true . -# Opt in to max-level provenance attestations: -docker buildx build --provenance=mode=max . -# Opt out of provenance attestations: -docker buildx build --provenance=false . -``` - -You can also disable default provenance attestations by setting the -[`BUILDX_NO_DEFAULT_ATTESTATIONS`](/manuals/build/building/variables.md#buildx_no_default_attestations) -environment variable. See [Provenance attestation](./slsa-provenance.md) for -more details about provenance modes and options. - -## Storage - -BuildKit produces attestations in the [in-toto format](https://github.com/in-toto/attestation), -as defined by the [in-toto framework](https://in-toto.io/), -a standard supported by the Linux Foundation. - -Attestations attach to images as a manifest in the image index. The data records -of the attestations are stored as JSON blobs. - -Because attestations attach to images as a manifest, it means that you can -inspect the attestations for any image in a registry without having to pull the -whole image. - -All BuildKit exporters support attestations. The `local` and `tar` can't save -the attestations to an image manifest, since it's outputting a directory of -files or a tarball, not an image. Instead, these exporters write the -attestations to one or more JSON files in the root directory of the export. - -## Example - -The following example shows a truncated in-toto JSON representation of an SBOM -attestation. - -```json -{ - "_type": "https://in-toto.io/Statement/v0.1", - "predicateType": "https://spdx.dev/Document", - "subject": [ - { - "name": "pkg:docker//@?platform=", - "digest": { - "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862" - } - } - ], - "predicate": { - "SPDXID": "SPDXRef-DOCUMENT", - "creationInfo": { - "created": "2022-12-15T11:47:54.546747383Z", - "creators": ["Organization: Anchore, Inc", "Tool: syft-v0.60.3"], - "licenseListVersion": "3.18" - }, - "dataLicense": "CC0-1.0", - "documentNamespace": "https://anchore.com/syft/dir/run/src/core-da0f600b-7f0a-4de0-8432-f83703e6bc4f", - "name": "/run/src/core", - // list of files that the image contains, e.g.: - "files": [ - { - "SPDXID": "SPDXRef-1ac501c94e2f9f81", - "comment": "layerID: sha256:9b18e9b68314027565b90ff6189d65942c0f7986da80df008b8431276885218e", - "fileName": "/bin/busybox", - "licenseConcluded": "NOASSERTION" - } - ], - // list of packages that were identified for this image: - "packages": [ - { - "name": "busybox", - "originator": "Person: Sören Tempel ", - "sourceInfo": "acquired package info from APK DB: lib/apk/db/installed", - "versionInfo": "1.35.0-r17", - "SPDXID": "SPDXRef-980737451f148c56", - "description": "Size optimized toolbox of many common UNIX utilities", - "downloadLocation": "https://busybox.net/", - "licenseConcluded": "GPL-2.0-only", - "licenseDeclared": "GPL-2.0-only" - // ... - } - ], - // files-packages relationship - "relationships": [ - { - "relatedSpdxElement": "SPDXRef-1ac501c94e2f9f81", - "relationshipType": "CONTAINS", - "spdxElementId": "SPDXRef-980737451f148c56" - }, - ... - ], - "spdxVersion": "SPDX-2.2" - } -} -``` - -To deep-dive into the specifics about how attestations are stored, see -[Image Attestation Storage (BuildKit)](attestation-storage.md). - -## Attestation manifest format - -Attestations are stored as manifests, referenced by the image's index. Each -_attestation manifest_ refers to a single _image manifest_ (one -platform-variant of the image). Attestation manifests contain a single layer, -the "value" of the attestation. - -The following example shows the structure of an attestation manifest: - -```json -{ - "schemaVersion": 2, - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "config": { - "mediaType": "application/vnd.oci.image.config.v1+json", - "size": 167, - "digest": "sha256:916d7437a36dd0e258e64d9c5a373ca5c9618eeb1555e79bd82066e593f9afae" - }, - "layers": [ - { - "mediaType": "application/vnd.in-toto+json", - "size": 1833349, - "digest": "sha256:3138024b98ed5aa8e3008285a458cd25a987202f2500ce1a9d07d8e1420f5491", - "annotations": { - "in-toto.io/predicate-type": "https://spdx.dev/Document" - } - } - ] -} -``` - -### Attestations as OCI artifacts - -You can configure the format of the attestation manifest using the -[`oci-artifact` option](/manuals/build/exporters/image-registry.md#synopsis) -for the `image` and `registry` exporters. If set to `true`, the structure of -the attestation manifest changes as follows: - -- An `artifactType` field is added to the attestation manifest, with a value of `application/vnd.docker.attestation.manifest.v1+json`. -- The `config` field is an [empty descriptor] instead of a "dummy" config. -- A `subject` field is also added, pointing to the image manifest that the attestation refers to. - -[empty descriptor]: https://github.com/opencontainers/image-spec/blob/main/manifest.md#guidance-for-an-empty-descriptor - -The following example shows an attestation with the OCI artifact format: - -```json -{ - "schemaVersion": 2, - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "artifactType": "application/vnd.docker.attestation.manifest.v1+json", - "config": { - "mediaType": "application/vnd.oci.empty.v1+json", - "size": 2, - "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a", - "data": "e30=" - }, - "layers": [ - { - "mediaType": "application/vnd.in-toto+json", - "size": 2208, - "digest": "sha256:6d2f2c714a6bee3cf9e4d3cb9a966b629efea2dd8556ed81f19bd597b3325286", - "annotations": { - "in-toto.io/predicate-type": "https://slsa.dev/provenance/v0.2" - } - } - ], - "subject": { - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "size": 1054, - "digest": "sha256:bc2046336420a2852ecf915786c20f73c4c1b50d7803aae1fd30c971a7d1cead", - "platform": { - "architecture": "amd64", - "os": "linux" - } - } -} -``` - -## What's next - -Learn more about the available attestation types and how to use them: - -- [Provenance](slsa-provenance.md) -- [SBOM](sbom.md) diff --git a/content/manuals/build/metadata/attestations/slsa-provenance.md b/content/manuals/build/metadata/provenance.md similarity index 97% rename from content/manuals/build/metadata/attestations/slsa-provenance.md rename to content/manuals/build/metadata/provenance.md index 54e00c78933a..72dc3dc05921 100644 --- a/content/manuals/build/metadata/attestations/slsa-provenance.md +++ b/content/manuals/build/metadata/provenance.md @@ -5,6 +5,7 @@ description: > Provenance build attestations describe how and where your image was built. aliases: - /build/attestations/slsa-provenance/ + - /build/metadata/attestations/slsa-provenance/ --- The provenance attestations include facts about the build process, including @@ -22,7 +23,7 @@ You can optionally enable [SLSA Provenance v1](https://slsa.dev/spec/v1.1/proven using [the `version` parameter](#version). For more information about how BuildKit populates these provenance properties, refer to -[SLSA definitions](slsa-definitions.md). +[SLSA definitions](https://github.com/moby/buildkit/blob/master/docs/attestations/slsa-definitions.md). ## Create provenance attestations @@ -168,7 +169,7 @@ $ docker buildx build --tag /: \ For more information about SLSA Provenance v1, see the [SLSA specification](https://slsa.dev/spec/v1.1/provenance). To see the difference between SLSA v0.2 and v1 provenance attestations, refer to -[SLSA definitions](./slsa-definitions.md) +[SLSA definitions](https://github.com/moby/buildkit/blob/master/docs/attestations/slsa-definitions.md) ## Inspecting Provenance diff --git a/content/manuals/build/metadata/attestations/sbom.md b/content/manuals/build/metadata/sbom.md similarity index 99% rename from content/manuals/build/metadata/attestations/sbom.md rename to content/manuals/build/metadata/sbom.md index ee34dc895665..1847793768bd 100644 --- a/content/manuals/build/metadata/attestations/sbom.md +++ b/content/manuals/build/metadata/sbom.md @@ -5,6 +5,7 @@ description: | SBOM attestations describe what software artifacts an image contains and the artifacts used to create the image. aliases: - /build/attestations/sbom/ + - /build/metadata/attestations/sbom/ --- SBOM attestations help ensure [software supply chain transparency](/guides/docker-scout/s3c.md) by verifying the software artifacts an image contains and the artifacts used to create the image. Metadata included in an [SBOM](/guides/docker-scout/sbom.md) for describing software artifacts may include: diff --git a/content/manuals/build/policies/validate-images.md b/content/manuals/build/policies/validate-images.md index 3f4b4dd951a5..4b0db9f8fabf 100644 --- a/content/manuals/build/policies/validate-images.md +++ b/content/manuals/build/policies/validate-images.md @@ -310,10 +310,10 @@ The `labels` field is a map, so you access values with bracket notation. ## Require attestations and provenance -Modern images include [attestations](/build/metadata/attestations/): +Modern images include [attestations](/build/metadata/): machine-readable metadata about how the image was built. -[Provenance](/build/metadata/attestations/slsa-provenance/) attestations -describe the build process, and [SBOMs](/build/metadata/attestations/sbom/) +[Provenance](/build/metadata/provenance/) attestations +describe the build process, and [SBOMs](/build/metadata/sbom/) list the software inside. Require provenance: @@ -333,7 +333,7 @@ decision := {"allow": allow} ``` The `hasProvenance` field is `true` when the image has provenance or SBOM -[attestations](../metadata/attestations/_index.md). +[attestations](../metadata/_index.md). ## Verify GitHub Actions signatures diff --git a/content/manuals/desktop/use-desktop/builds.md b/content/manuals/desktop/use-desktop/builds.md index 5a47b1332bb4..f208c2b4ae13 100644 --- a/content/manuals/desktop/use-desktop/builds.md +++ b/content/manuals/desktop/use-desktop/builds.md @@ -38,7 +38,7 @@ Docker Desktop settings. The **Import builds** button lets you import build records for builds by other people, or builds in a CI environment. When you've imported a build record, it gives you full access to the logs, traces, and other data for that build, -directly in Docker Desktop. +directly in Docker Desktop. The [build summary](/manuals/build/ci/github-actions/build-summary.md) for the `docker/build-push-action` and `docker/bake-action` GitHub Actions @@ -82,8 +82,8 @@ operations are defined as follows: | HTTP | Remote artifact downloads using `ADD`. | | Git | Same as **HTTP** but for Git URLs. | | Result exports | Time spent exporting the build results. | -| SBOM | Time spent generating the [SBOM attestation](/manuals/build/metadata/attestations/sbom.md). | -| Idle | Idle time for build workers, which can happen if you have configured a [max parallelism limit](/manuals/build/buildkit/configure.md#max-parallelism). | +| SBOM | Time spent generating the [SBOM attestation](/manuals/build/metadata/sbom.md). | +| Idle | Idle time for build workers, which can happen if you have configured a [max parallelism limit](/manuals/build/buildkit/configure.md#max-parallelism). | ### Build dependencies @@ -112,7 +112,7 @@ including image manifest details, attestations, and build traces. Attestations are metadata records attached to a container image. The metadata describes something about the image, for example how it was built or what packages it contains. -For more information about attestations, see [Build attestations](/manuals/build/metadata/attestations/_index.md). +For more information about attestations, see [Build attestations](/manuals/build/metadata/_index.md). Build traces capture information about the build execution steps in Buildx and BuildKit. The traces are available in two formats: OTLP and Jaeger. You can diff --git a/content/manuals/dhi/core-concepts/attestations.md b/content/manuals/dhi/core-concepts/attestations.md index af72fd2e6661..ee5db61e10c7 100644 --- a/content/manuals/dhi/core-concepts/attestations.md +++ b/content/manuals/dhi/core-concepts/attestations.md @@ -4,10 +4,10 @@ description: Review the full set of signed attestations included with each Docke keywords: container image attestations, signed sbom, build provenance, slsa compliance, vex document --- -Docker Hardened Images (DHIs) and charts include comprehensive, signed security -attestations that verify the image's build process, contents, and security -posture. These attestations are a core part of secure software supply chain -practices and help users validate that an image is trustworthy and +Attestations are signed statements about an image or chart — verifiable +metadata that describes how it was built, what it contains, and what security +checks it has passed. Attestations are a core part of secure software supply +chain practices, and help you validate that an image is trustworthy and policy-compliant. ## What is an attestation? @@ -27,9 +27,9 @@ scan results, or custom provenance. Attestations provide critical visibility into the software supply chain by: -- Documenting *what* went into an image (e.g., SBOMs) -- Verifying *how* it was built (e.g., build provenance) -- Capturing *what security scans* it has passed or failed (e.g., CVE reports, +- Documenting _what_ went into an image (e.g., SBOMs) +- Verifying _how_ it was built (e.g., build provenance) +- Capturing _what security scans_ it has passed or failed (e.g., CVE reports, secrets scans, test results) - Helping organizations enforce compliance and security policies - Supporting runtime trust decisions and CI/CD policy gates @@ -50,7 +50,7 @@ to: - Review scan results to check for vulnerabilities or embedded secrets - Confirm the build and deployment history of each image -Attestations are automatically published and associated with each DHI +Attestations are automatically published and associated with each DHI and chart. They can be inspected using tools like [Docker Scout](../how-to/verify.md) or [Cosign](https://docs.sigstore.dev/cosign/overview), and are consumable by CI/CD @@ -71,24 +71,24 @@ $ docker scout attest list dhi.io/: For more details, see [Verify image attestations](../how-to/verify.md#verify-image-attestations). -| Attestation type | Description | -|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| CycloneDX SBOM | A software bill of materials in [CycloneDX](https://cyclonedx.org/) format, listing components, libraries, and versions. | -| STIG scan | Results of a STIG scan, with output in HTML and XCCDF formats. | -| CVEs (In-Toto format) | A list of known vulnerabilities (CVEs) affecting the image's components, based on package and distribution scanning. | -| VEX | A [Vulnerability Exploitability eXchange (VEX)](https://openvex.dev/) document that identifies vulnerabilities that do not apply to the image and explains why (e.g., not reachable or not present). | -| Scout health score | A signed attestation from Docker Scout that summarizes the overall security and quality posture of the image. | -| Scout provenance | Provenance metadata generated by Docker Scout, including the source Git commit, build parameters, and environment details. | -| Scout SBOM | An SBOM generated and signed by Docker Scout, including additional Docker-specific metadata. | -| Secrets scan | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys. | -| Tests | A record of automated tests run against the image, such as functional checks or validation scripts. | -| Virus scan | Results of antivirus scans performed on the image layers. For details, see [Malware scanning](../explore/malware-scanning.md). | -| CVEs (Scout format) | A vulnerability report generated by Docker Scout, listing known CVEs and severity data. | -| SLSA provenance | A standard [SLSA](https://slsa.dev/) provenance statement describing how the image was built, including build tool, parameters, and source. | -| SLSA verification summary | A summary attestation indicating the image's compliance with SLSA requirements. | -| SPDX SBOM | An SBOM in [SPDX](https://spdx.dev/) format, widely adopted in open-source ecosystems. | -| FIPS compliance | An attestation that verifies the image uses FIPS 140-validated cryptographic modules. | -| DHI Image Sources | Links to a corresponding source image containing all materials used to build the image, including package source code, Git repositories, and local files, ensuring compliance with open source license requirements. | +| Attestation type | Description | +| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CycloneDX SBOM | A software bill of materials in [CycloneDX](https://cyclonedx.org/) format, listing components, libraries, and versions. | +| STIG scan | Results of a STIG scan, with output in HTML and XCCDF formats. | +| CVEs (In-Toto format) | A list of known vulnerabilities (CVEs) affecting the image's components, based on package and distribution scanning. | +| VEX | A [Vulnerability Exploitability eXchange (VEX)](https://openvex.dev/) document that identifies vulnerabilities that do not apply to the image and explains why (e.g., not reachable or not present). | +| Scout health score | A signed attestation from Docker Scout that summarizes the overall security and quality posture of the image. | +| Scout provenance | Provenance metadata generated by Docker Scout, including the source Git commit, build parameters, and environment details. | +| Scout SBOM | An SBOM generated and signed by Docker Scout, including additional Docker-specific metadata. | +| Secrets scan | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys. | +| Tests | A record of automated tests run against the image, such as functional checks or validation scripts. | +| Virus scan | Results of antivirus scans performed on the image layers. For details, see [Malware scanning](../explore/malware-scanning.md). | +| CVEs (Scout format) | A vulnerability report generated by Docker Scout, listing known CVEs and severity data. | +| SLSA provenance | A standard [SLSA](https://slsa.dev/) provenance statement describing how the image was built, including build tool, parameters, and source. | +| SLSA verification summary | A summary attestation indicating the image's compliance with SLSA requirements. | +| SPDX SBOM | An SBOM in [SPDX](https://spdx.dev/) format, widely adopted in open-source ecosystems. | +| FIPS compliance | An attestation that verifies the image uses FIPS 140-validated cryptographic modules. | +| DHI Image Sources | Links to a corresponding source image containing all materials used to build the image, including package source code, Git repositories, and local files, ensuring compliance with open source license requirements. | ## Package attestations @@ -121,19 +121,19 @@ $ docker scout attest list dhi.io/: For more details, see [Verify Helm chart attestations](../how-to/verify.md#verify-helm-chart-attestations-with-docker-scout). -| Attestation type | Description | -|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| CycloneDX SBOM | A software bill of materials in [CycloneDX](https://cyclonedx.org/) format, listing the chart itself and all container images and tools referenced by the chart. | -| CVEs (In-Toto format) | A list of known vulnerabilities (CVEs) affecting the container images and components referenced by the chart. | -| Scout health score | A signed attestation from Docker Scout that summarizes the overall security and quality posture of the chart and its referenced images. | -| Scout provenance | Provenance metadata generated by Docker Scout, including the chart source repository, build images used, and build parameters. | -| Scout SBOM | An SBOM generated and signed by Docker Scout, including the chart and container images it references, with additional Docker-specific metadata. | -| Secrets scan | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys, in the chart package. | -| Tests | A record of automated tests run against the chart to validate functionality and compatibility with referenced images. | -| Virus scan | Results of antivirus scans performed on the chart package. For details, see [Malware scanning](../explore/malware-scanning.md). | -| CVEs (Scout format) | A vulnerability report generated by Docker Scout, listing known CVEs and severity data for the chart's referenced images. | -| SLSA provenance | A standard [SLSA](https://slsa.dev/) provenance statement describing how the chart was built, including build tool, source repository, referenced images, and build materials. | -| SPDX SBOM | An SBOM in [SPDX](https://spdx.dev/) format, listing the chart and all container images and tools it references. | +| Attestation type | Description | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| CycloneDX SBOM | A software bill of materials in [CycloneDX](https://cyclonedx.org/) format, listing the chart itself and all container images and tools referenced by the chart. | +| CVEs (In-Toto format) | A list of known vulnerabilities (CVEs) affecting the container images and components referenced by the chart. | +| Scout health score | A signed attestation from Docker Scout that summarizes the overall security and quality posture of the chart and its referenced images. | +| Scout provenance | Provenance metadata generated by Docker Scout, including the chart source repository, build images used, and build parameters. | +| Scout SBOM | An SBOM generated and signed by Docker Scout, including the chart and container images it references, with additional Docker-specific metadata. | +| Secrets scan | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys, in the chart package. | +| Tests | A record of automated tests run against the chart to validate functionality and compatibility with referenced images. | +| Virus scan | Results of antivirus scans performed on the chart package. For details, see [Malware scanning](../explore/malware-scanning.md). | +| CVEs (Scout format) | A vulnerability report generated by Docker Scout, listing known CVEs and severity data for the chart's referenced images. | +| SLSA provenance | A standard [SLSA](https://slsa.dev/) provenance statement describing how the chart was built, including build tool, source repository, referenced images, and build materials. | +| SPDX SBOM | An SBOM in [SPDX](https://spdx.dev/) format, listing the chart and all container images and tools it references. | ## View and verify attestations @@ -156,4 +156,4 @@ These attestations can then be verified downstream using tools like Cosign or Docker Scout. To learn how to attach custom attestations during the build process, see [Build -attestations](/manuals/build/metadata/attestations.md). +metadata](/manuals/build/metadata/_index.md). diff --git a/content/manuals/dhi/core-concepts/provenance.md b/content/manuals/dhi/core-concepts/provenance.md index 5c8adcb425e4..34fbc959fc62 100644 --- a/content/manuals/dhi/core-concepts/provenance.md +++ b/content/manuals/dhi/core-concepts/provenance.md @@ -66,6 +66,6 @@ With image signatures, you can: ## Additional resources -- [Provenance attestations](/build/metadata/attestations/slsa-provenance/) +- [Provenance attestations](/build/metadata/provenance/) - [Image signatures](./signatures.md) -- [Attestations overview](./attestations.md) \ No newline at end of file +- [Attestations overview](./attestations.md) diff --git a/content/manuals/dhi/core-concepts/sbom.md b/content/manuals/dhi/core-concepts/sbom.md index 06dc2b67a31d..670761f54909 100644 --- a/content/manuals/dhi/core-concepts/sbom.md +++ b/content/manuals/dhi/core-concepts/sbom.md @@ -30,7 +30,6 @@ vulnerabilities and complicate compliance efforts. SBOMs address these challenges by providing a detailed inventory of all components within an application. - The significance of SBOMs is underscored by several key factors: - Enhanced transparency: SBOMs offer a comprehensive view of all components that @@ -89,6 +88,6 @@ $ docker scout attest get dhi.io/node:20.19-debian12 \ ## Resources For more details about SBOM attestations and Docker Build, see [SBOM -attestations](/build/metadata/attestations/sbom/). +attestations](/build/metadata/sbom/). -To learn more about Docker Scout and working with SBOMs, see [Docker Scout SBOMs](../../scout/how-tos/view-create-sboms.md). \ No newline at end of file +To learn more about Docker Scout and working with SBOMs, see [Docker Scout SBOMs](../../scout/how-tos/view-create-sboms.md). diff --git a/content/manuals/dhi/core-concepts/slsa.md b/content/manuals/dhi/core-concepts/slsa.md index ad4b254bdab7..afce191309f8 100644 --- a/content/manuals/dhi/core-concepts/slsa.md +++ b/content/manuals/dhi/core-concepts/slsa.md @@ -101,5 +101,4 @@ $ docker scout attest get dhi.io/node:20.19-debian12 \ ## Resources -For more details about SLSA definitions and Docker Build, see [SLSA -definitions](/build/metadata/attestations/slsa-definitions/). \ No newline at end of file +For more details about SLSA definitions and Docker Build, see [Provenance attestations](/build/metadata/provenance/). diff --git a/content/manuals/dhi/how-to/use.md b/content/manuals/dhi/how-to/use.md index c618f4d4ab66..8a3917abec11 100644 --- a/content/manuals/dhi/how-to/use.md +++ b/content/manuals/dhi/how-to/use.md @@ -50,7 +50,7 @@ Docker Hardened Images use different image references depending on your subscription: | Subscription | Image reference | Authentication | -|---------------------|----------------------------|-----------------------| +| ------------------- | -------------------------- | --------------------- | | Community | `dhi.io/:` | `docker login dhi.io` | | Select & Enterprise | `/:` | `docker login` | @@ -73,6 +73,7 @@ CMD ["python", "/app/main.py"] ``` For multi-stage builds: + - Use a `-dev` tag for build stages that need a shell or package manager. See [Use dev variants for framework-based applications](#use-dev-variants-for-framework-based-applications). @@ -100,7 +101,7 @@ verify its integrity, and enable downstream validation and policy enforcement using tools like Docker Scout. To learn how to attach attestations during the build process, see [Docker Build -Attestations](/manuals/build/metadata/attestations.md). +Attestations](/manuals/build/metadata/_index.md). ### Discover attestations with ORAS @@ -135,9 +136,9 @@ To discover attestations with ORAS: > reading from files with restricted permissions, environment files loaded > at runtime, or secret management tools. - ```console - $ oras login dhi.io -u - ``` + ```console + $ oras login dhi.io -u + ``` Or non-interactively in a CI/CD pipeline, set your organization name and token: @@ -200,6 +201,7 @@ switch to a smaller runtime variant to reduce the attack surface and image size. For detailed multi-stage Dockerfile examples using dev variants, see the migration examples: + - [Go](../migration/examples/go.md) - [Python](../migration/examples/python.md) - [Node.js](../migration/examples/node.md) @@ -234,6 +236,7 @@ your own third-party registry. You can create an image pull secret using either an access token or Docker Desktop credentials. For the `--docker-server` value: + - Use `dhi.io` for community images pulled directly from Docker Hardened Images - Use `docker.io` for mirrored repositories on Docker Hub - Use your registry's hostname for third-party registries diff --git a/content/manuals/scout/deep-dive/data-handling.md b/content/manuals/scout/deep-dive/data-handling.md index 92ae3d4af8b3..539daa7b34e7 100644 --- a/content/manuals/scout/deep-dive/data-handling.md +++ b/content/manuals/scout/deep-dive/data-handling.md @@ -5,8 +5,7 @@ keywords: | materials, config, ports, labels, os, registry, timestamp, digest, layers, architecture, license, dependencies, base image title: Data collection and storage in Docker Scout -aliases: - /scout/data-handling/ +aliases: /scout/data-handling/ --- Docker Scout's image analysis works by collecting metadata from the container @@ -85,7 +84,7 @@ Docker Scout platform; it's only used to run the analysis. ### Provenance -For images with [provenance attestations](/manuals/build/metadata/attestations/slsa-provenance.md), +For images with [provenance attestations](/manuals/build/metadata/provenance.md), Docker Scout stores the following data in addition to the SBOM: - Materials diff --git a/content/manuals/scout/explore/analysis.md b/content/manuals/scout/explore/analysis.md index 655eb1022bc9..637338a2ff2d 100644 --- a/content/manuals/scout/explore/analysis.md +++ b/content/manuals/scout/explore/analysis.md @@ -72,7 +72,7 @@ analysis is activated. ``` Building with the `--provenance=true` and `--sbom=true` flags attaches - [build attestations](/manuals/build/metadata/attestations/_index.md) to the image. Docker + [build attestations](/manuals/build/metadata/_index.md) to the image. Docker Scout uses attestations to provide more fine-grained analysis results. > [!NOTE] @@ -228,5 +228,5 @@ Image analysis on the Docker Scout platform, and analysis triggered by backgroun indexing in Docker Desktop, has an image file size limit of 10 GB (uncompressed). To analyze images larger than that: -- Attach an [SBOM attestation](/manuals/build/metadata/attestations/sbom.md) at build-time. When an image includes an SBOM attestation, Docker Scout uses it instead of generating one, so the 10 GB limit doesn’t apply. +- Attach an [SBOM attestation](/manuals/build/metadata/sbom.md) at build-time. When an image includes an SBOM attestation, Docker Scout uses it instead of generating one, so the 10 GB limit doesn’t apply. - Alternatively, you can use the [CLI](#cli) to analyze the image locally. The 10 GB limit doesn’t apply when using the CLI. If the image includes an SBOM attestation, the CLI uses it to complete the analysis faster. diff --git a/content/manuals/scout/how-tos/view-create-sboms.md b/content/manuals/scout/how-tos/view-create-sboms.md index 16b45ed8aa28..af49837204e0 100644 --- a/content/manuals/scout/how-tos/view-create-sboms.md +++ b/content/manuals/scout/how-tos/view-create-sboms.md @@ -3,8 +3,8 @@ title: Docker Scout SBOMs description: Use Docker Scout to extract the SBOM for your project. keywords: scout, supply chain, sbom, software bill of material, spdx, cli, attestations, file aliases: -- /engine/sbom/ -- /scout/sbom/ + - /engine/sbom/ + - /scout/sbom/ --- [Image analysis](/manuals/scout/explore/analysis.md) uses image SBOMs to understand what packages and versions an image contains. @@ -62,7 +62,7 @@ reference](/reference/cli/docker/scout/sbom/). ## Attach as build attestation {#attest} You can generate the SBOM and attach it to the image at build-time as an -[attestation](/manuals/build/metadata/attestations/_index.md). BuildKit provides a default +[attestation](/manuals/build/metadata/_index.md). BuildKit provides a default SBOM generator which is different from what Docker Scout uses. You can configure BuildKit to use the Docker Scout SBOM generator using the `--attest` flag for the `docker build` command. diff --git a/content/manuals/scout/integrations/code-quality/sonarqube.md b/content/manuals/scout/integrations/code-quality/sonarqube.md index ba1b552ba41b..15d6e35fec7f 100644 --- a/content/manuals/scout/integrations/code-quality/sonarqube.md +++ b/content/manuals/scout/integrations/code-quality/sonarqube.md @@ -35,7 +35,7 @@ Both self-managed SonarQube instances and SonarCloud are supported. To integrate Docker Scout with SonarQube, ensure that: - Your image repository is [integrated with Docker Scout](../_index.md#container-registries). -- Your images are built with [provenance attestations](/manuals/build/metadata/attestations/slsa-provenance.md), +- Your images are built with [provenance attestations](/manuals/build/metadata/provenance.md), or the `org.opencontainers.image.revision` annotation, containing information about the Git repository. diff --git a/content/manuals/scout/integrations/source-code-management/github.md b/content/manuals/scout/integrations/source-code-management/github.md index cb9350ec2d22..5e8efa4853bc 100644 --- a/content/manuals/scout/integrations/source-code-management/github.md +++ b/content/manuals/scout/integrations/source-code-management/github.md @@ -18,7 +18,7 @@ When you enable the GitHub integration, Docker Scout can make a direct link between the image analysis results and the source. When analyzing your image, Docker Scout checks for [provenance -attestations](/manuals/build/metadata/attestations/slsa-provenance.md) to detect the +attestations](/manuals/build/metadata/provenance.md) to detect the location of the source code repository for the image. If the source location is found, and you've enabled the GitHub app, Docker Scout parses the Dockerfile used to create the image. diff --git a/content/manuals/scout/policy/_index.md b/content/manuals/scout/policy/_index.md index 63b6e4fccc19..d98188066a74 100644 --- a/content/manuals/scout/policy/_index.md +++ b/content/manuals/scout/policy/_index.md @@ -48,7 +48,7 @@ image up-to-dateness. ## Policy types -In Docker Scout, a *policy* is derived from a *policy type*. Policy types are +In Docker Scout, a _policy_ is derived from a _policy type_. Policy types are templates that define the core parameters of a policy. You can compare policy types to classes in object-oriented programming, with each policy acting as an instance created from its corresponding policy type. @@ -104,6 +104,7 @@ The following policy parameters are configurable in a custom version: fail until you've had a chance to address them. + - **Severities**: Severity levels to consider (default: `Critical, High`) @@ -180,11 +181,11 @@ For more information on policy configuration, see [Configure policies](./configu ### Supply Chain Attestations The **Supply Chain Attestations** policy type checks whether your images have -[SBOM](/manuals/build/metadata/attestations/sbom.md) and -[provenance](/manuals/build/metadata/attestations/slsa-provenance.md) attestations. +[SBOM](/manuals/build/metadata/sbom.md) and +[provenance](/manuals/build/metadata/provenance.md) attestations. Images are considered non-compliant if they lack either an SBOM attestation or -a provenance attestation with *max mode* provenance. To ensure compliance, +a provenance attestation with _max mode_ provenance. To ensure compliance, update your build command to attach these attestations at build-time: ```console @@ -192,7 +193,7 @@ $ docker buildx build --provenance=true --sbom=true -t --push . ``` For more information about building with attestations, see -[Attestations](/manuals/build/metadata/attestations/_index.md). +[Attestations](/manuals/build/metadata/_index.md). If you're using GitHub Actions to build and push your images, learn how you can [configure the action](/manuals/build/ci/github-actions/attestations.md) @@ -345,7 +346,7 @@ SonarQube evaluates your source code against the quality gates you've defined in SonarQube. Docker Scout surfaces the SonarQube assessment as a Docker Scout policy. -Docker Scout uses [provenance](/manuals/build/metadata/attestations/slsa-provenance.md) +Docker Scout uses [provenance](/manuals/build/metadata/provenance.md) attestations or the `org.opencontainers.image.revision` OCI annotation to link SonarQube analysis results with container images. In addition to enabling the SonarQube integration, you must also make sure that your images have either the @@ -397,6 +398,6 @@ This "no data" state occurs when: of date To make sure that Docker Scout always knows about your base image, you can -attach [provenance attestations](/manuals/build/metadata/attestations/slsa-provenance.md) +attach [provenance attestations](/manuals/build/metadata/provenance.md) at build-time. Docker Scout uses provenance attestations to find out the base image version. diff --git a/content/manuals/scout/policy/remediation.md b/content/manuals/scout/policy/remediation.md index 48701160381f..ff07469b8393 100644 --- a/content/manuals/scout/policy/remediation.md +++ b/content/manuals/scout/policy/remediation.md @@ -19,6 +19,7 @@ following policy types: - [Supply Chain Attestations](#supply-chain-attestations-remediation) + > [!NOTE] > Guided remediation is not supported for custom policies. @@ -75,7 +76,7 @@ information available about the image. ### No provenance attestations For Docker Scout to be able to evaluate this policy, you must add [provenance -attestations](/manuals/build/metadata/attestations/slsa-provenance.md) to your image. If +attestations](/manuals/build/metadata/provenance.md) to your image. If your image doesn't have provenance attestations, compliance is undeterminable.