SLSA definitions

Table of contents

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.

This page describes how BuildKit populate each field, and whether the field gets included when you generate attestations mode=min and mode=max.

`builder.id`

Corresponds to SLSA builder.id.

Included with mode=min and mode=max.

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

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

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

`buildType`

Corresponds to SLSA buildType.

Included with mode=min and mode=max.

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

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

`invocation.configSource`

Corresponds to SLSA invocation.configSource.

Included with mode=min and mode=max.

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`

Corresponds to SLSA invocation.parameters.

Partially included with mode=min.

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`

Corresponds to SLSA invocation.environment.

Included with mode=min and mode=max.

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

Corresponds to SLSA 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 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`

Corresponds to SLSA 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. 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`

Corresponds to SLSA metadata.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.

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

`metadata.buildStartedOn`

Corresponds to SLSA metadata.buildStartedOn.

Included with mode=min and mode=max.

Timestamp when the build started.

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

`metadata.buildFinishedOn`

Corresponds to SLSA metadata.buildFinishedOn.

Included with mode=min and mode=max.

Timestamp when the build finished.

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

`metadata.completeness`

Corresponds to SLSA 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 invocation.parameters field. When building with min mode, the build arguments are not included in the provenance information and parameters are not complete. Parameters are also not complete on direct LLB builds that did not use a frontend.

completeness.environment is always true for BuildKit builds.

completeness.materials is true if materials field includes all the dependencies of the build. When building from un-tracked source in a local directory, the materials are not complete, while when building from a remote Git repository all materials can be tracked by BuildKit and completeness.materials is true.

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

`metadata.reproducible`

Corresponds to SLSA 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.

Output

To inspect the provenance that was generated and attached to a container image, you can use the docker buildx imagetools command to inspect the image in a registry. Inspecting the attestation displays the format described in the attestation storage specification.

For example, inspecting a simple Docker image based on alpine:latest results in a provenance attestation similar to the following, for a mode=min build:

{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://slsa.dev/provenance/v0.2",
  "subject": [
    {
      "name": "pkg:docker/<registry>/<image>@<tag/digest>?platform=<platform>",
      "digest": {
        "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862"
      }
    }
  ],
  "predicate": {
    "builder": {
      "id": ""
    },
    "buildType": "https://mobyproject.org/buildkit@v1",
    "materials": [
      {
        "uri": "pkg:docker/alpine@latest?platform=linux%2Famd64",
        "digest": {
          "sha256": "8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4"
        }
      }
    ],
    "invocation": {
      "configSource": {
        "entryPoint": "Dockerfile"
      },
      "parameters": {
        "frontend": "dockerfile.v0",
        "args": {},
        "locals": [
          {
            "name": "context"
          },
          {
            "name": "dockerfile"
          }
        ]
      },
      "environment": {
        "platform": "linux/amd64"
      }
    },
    "metadata": {
      "buildInvocationID": "yirbp1aosi1vqjmi3z6bc75nb",
      "buildStartedOn": "2022-12-08T11:48:59.466513707Z",
      "buildFinishedOn": "2022-12-08T11:49:01.256820297Z",
      "reproducible": false,
      "completeness": {
        "parameters": true,
        "environment": true,
        "materials": false
      },
      "https://mobyproject.org/buildkit@v1#metadata": {}
    }
  }
}

For a similar build, but with mode=max:

{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://slsa.dev/provenance/v0.2",
  "subject": [
    {
      "name": "pkg:docker/<registry>/<image>@<tag/digest>?platform=<platform>",
      "digest": {
        "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862"
      }
    }
  ],
  "predicate": {
    "builder": {
      "id": ""
    },
    "buildType": "https://mobyproject.org/buildkit@v1",
    "materials": [
      {
        "uri": "pkg:docker/alpine@latest?platform=linux%2Famd64",
        "digest": {
          "sha256": "8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4"
        }
      }
    ],
    "invocation": {
      "configSource": {
        "entryPoint": "Dockerfile"
      },
      "parameters": {
        "frontend": "dockerfile.v0",
        "args": {},
        "locals": [
          {
            "name": "context"
          },
          {
            "name": "dockerfile"
          }
        ]
      },
      "environment": {
        "platform": "linux/amd64"
      }
    },
    "buildConfig": {
      "llbDefinition": [
        {
          "id": "step0",
          "op": {
            "Op": {
              "source": {
                "identifier": "docker-image://docker.io/library/alpine:latest@sha256:8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4"
              }
            },
            "platform": {
              "Architecture": "amd64",
              "OS": "linux"
            },
            "constraints": {}
          }
        },
        {
          "id": "step1",
          "op": {
            "Op": null
          },
          "inputs": ["step0:0"]
        }
      ]
    },
    "metadata": {
      "buildInvocationID": "46ue2x93k3xj5l463dektwldw",
      "buildStartedOn": "2022-12-08T11:50:54.953375437Z",
      "buildFinishedOn": "2022-12-08T11:50:55.447841328Z",
      "reproducible": false,
      "completeness": {
        "parameters": true,
        "environment": true,
        "materials": false
      },
      "https://mobyproject.org/buildkit@v1#metadata": {
        "source": {
          "locations": {
            "step0": {
              "locations": [
                {
                  "ranges": [
                    {
                      "start": {
                        "line": 1
                      },
                      "end": {
                        "line": 1
                      }
                    }
                  ]
                }
              ]
            }
          },
          "infos": [
            {
              "filename": "Dockerfile",
              "data": "RlJPTSBhbHBpbmU6bGF0ZXN0Cg==",
              "llbDefinition": [
                {
                  "id": "step0",
                  "op": {
                    "Op": {
                      "source": {
                        "identifier": "local://dockerfile",
                        "attrs": {
                          "local.differ": "none",
                          "local.followpaths": "[\"Dockerfile\",\"Dockerfile.dockerignore\",\"dockerfile\"]",
                          "local.session": "q2jnwdkas0i0iu4knchd92jaz",
                          "local.sharedkeyhint": "dockerfile"
                        }
                      }
                    },
                    "constraints": {}
                  }
                },
                {
                  "id": "step1",
                  "op": {
                    "Op": null
                  },
                  "inputs": ["step0:0"]
                }
              ]
            }
          ]
        },
        "layers": {
          "step0:0": [
            [
              {
                "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
                "digest": "sha256:c158987b05517b6f2c5913f3acef1f2182a32345a304fe357e3ace5fadcad715",
                "size": 3370706
              }
            ]
          ]
        }
      }
    }
  }
}