SLSA definitions

もくじ

BuildKit supports the creation of SLSA Provenance for builds that it runs.

The provenance format generated by BuildKit is defined by the SLSA Provenance format (supports both v0.2 and v1).

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

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.

    "buildDefinition": {
      "buildType": "https://github.com/moby/buildkit/blob/master/docs/attestations/slsa-definitions.md",
      ...
    }

buildDefinition.externalParameters.configSource

Describes the config that initialized the build.

    "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

Describes build inputs passed to the build.

    "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

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. The dependencies for a vertex in the LLB graph can be found in the inputs field for every step.

    "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

    "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

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 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.

    "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

The field is set to the URL of the build, if available.

    "runDetails": {
      "builder": {
        "id": "https://github.com/docker/buildx/actions/runs/3709599520"
        ...
      },
      ...
    }
メモ

This value can be set using the builder-id attestation parameter.

runDetails.metadata.invocationID

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.

    "runDetails": {
      "metadata": {
        "invocationID": "rpv7a389uzil5lqmrgwhijwjz",
        ...
      },
      ...
    }

runDetails.metadata.startedOn

Timestamp when the build started.

    "runDetails": {
      "metadata": {
        "startedOn": "2021-11-17T15:00:00Z",
        ...
      },
      ...
    }

runDetails.metadata.finishedOn

Timestamp when the build finished.

    "runDetails": {
      "metadata": {
        "finishedOn": "2021-11-17T15:01:00Z",
        ...
      },
    }

runDetails.metadata.buildkit_metadata

This extension field defines BuildKit-specific additional metadata that is not part of the SLSA provenance spec.

    "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

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.

    "runDetails": {
      "metadata": {
        "buildkit_hermetic": true,
        ...
      },
    }

runDetails.metadata.buildkit_completeness

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.

    "runDetails": {
      "metadata": {
        "buildkit_completeness": {
          "request": true,
          "resolvedDependencies": true
        },
        ...
      },
    }

runDetails.metadata.buildkit_reproducible

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.

    "runDetails": {
      "metadata": {
        "buildkit_reproducible": false,
        ...
      },
    }

SLSA v0.2

builder.id

The field is set to the URL of the build, if available.

    "builder": {
      "id": "https://github.com/docker/buildx/actions/runs/3709599520"
    },
メモ

This value can be set using the builder-id attestation parameter.

buildType

The buildType field is set to https://mobyproject.org/buildkit@v1 and can be used to determine the structure of the provenance content.

    "buildType": "https://mobyproject.org/buildkit@v1",

invocation.configSource

Describes the config that initialized the build.

    "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

Describes build inputs passed to the build.

    "invocation": {
      "parameters": {
        "frontend": "gateway.v0",
        "args": {
          "build-arg:BUILDKIT_CONTEXT_KEEP_GIT_DIR": "1",
          "label:FOO": "bar",
          "source": "docker/dockerfile-upstream:master",
          "target": "release"
        },
        "secrets": [
          {
            "id": "GIT_AUTH_HEADER",
            "optional": true
          },
          ...
        ],
        "ssh": [],
        "locals": []
      },
      ...
    },

The following 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

    "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

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 format.

All the build materials will include the immutable checksum of the artifact. When building from a mutable tag, you can use the digest information to determine if the artifact has been updated compared to when the build ran.

    "materials": [
      {
        "uri": "pkg:docker/alpine@3.17?platform=linux%2Famd64",
        "digest": {
          "sha256": "8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4"
        }
      },
      {
        "uri": "https://github.com/moby/buildkit.git#refs/tags/v0.11.0",
        "digest": {
          "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0"
        }
      },
      ...
    ],

buildConfig

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. The dependencies for a vertex in the LLB graph can be found in the inputs field for every step.

  "buildConfig": {
    "llbDefinition": [
      {
        "id": "step0",
        "op": {
          "Op": {
            "exec": {
              "meta": {
                "args": [
                  "/bin/sh",
                  "-c",
                  "go build ."
                ],
                "env": [
                  "PATH=/go/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
                  "GOPATH=/go",
                  "GOFLAGS=-mod=vendor",
                ],
                "cwd": "/src",
              },
              "mounts": [...]
            }
          },
          "platform": {...},
        },
        "inputs": [
          "step8:0",
          "step2:0",
        ]
      },
      ...
    ]
  },

metadata.buildInvocationId

Unique identifier for the build invocation. When building a multi-platform image with a single build request, this value will be the shared by all the platform versions of the image.

    "metadata": {
      "buildInvocationID": "rpv7a389uzil5lqmrgwhijwjz",
      ...
    },

metadata.buildStartedOn

Timestamp when the build started.

    "metadata": {
      "buildStartedOn": "2021-11-17T15:00:00Z",
      ...
    },

metadata.buildFinishedOn

Timestamp when the build finished.

    "metadata": {
      "buildFinishedOn": "2021-11-17T15:01:00Z",
      ...
    },

metadata.completeness

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.

    "metadata": {
      "completeness": {
        "parameters": true,
        "environment": true,
        "materials": true
      },
      ...
    },

metadata.reproducible

Defines if the build result is supposed to be byte-by-byte reproducible. This value can be set by the user with the reproducible=true attestation parameter.

    "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.

    "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.

    "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.