SLSA 定义

目录

BuildKit 支持为其运行的构建创建 SLSA 出处。

BuildKit 生成的出处格式由 SLSA 出处格式定义（支持 v0.2 和 v1）。

本页介绍 BuildKit 如何填充每个字段，以及当您生成 `mode=min` 和 `mode=max` 证明时，该字段是否包含在内。

SLSA v1

buildDefinition.buildType

`buildDefinition.buildType` 字段设置为 `https://github.com/moby/buildkit/blob/master/docs/attestations/slsa-definitions.md`，可用于确定出处内容的结构。

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

buildDefinition.externalParameters.configSource

描述初始化构建的配置。

    "buildDefinition": {
      "externalParameters": {
        "configSource": {
          "uri": "https://github.com/moby/buildkit.git#refs/tags/v0.11.0",
          "digest": {
            "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0"
          },
          "path": "Dockerfile"
        },
        ...
      },
    }

对于从远程上下文（如 Git 或 HTTP URL）初始化的构建，此对象在 `uri` 和 `digest` 字段中定义上下文 URL 及其不可变摘要。对于使用本地前端（如 Dockerfile）的构建，`path` 字段定义了初始化构建的前端文件的路径（`filename` 前端选项）。

buildDefinition.externalParameters.request

描述传递给构建的构建输入。

    "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": []
        },
        ...
      },
    }

以下字段包含在 `mode=min` 和 `mode=max` 中：

  • `locals` 列出构建中使用的所有本地源，包括构建上下文和前端文件。

  • `frontend` 定义用于构建的 BuildKit 前端类型。目前，这可以是 `dockerfile.v0` 或 `gateway.v0`。

  • `args` 定义传递给 BuildKit 前端的构建参数。

    `args` 对象中的键反映了 BuildKit 接收到的选项。例如，`build-arg` 和 `label` 前缀用于构建参数和标签，`target` 键定义了构建的目标阶段。如果使用了 Gateway 前端，`source` 键定义了源镜像。

以下字段仅包含在 `mode=max` 中

  • `secrets` 定义构建期间使用的秘密。请注意，不包括实际的秘密值。
  • `ssh` 定义构建期间使用的 ssh 转发。

buildDefinition.internalParameters.buildConfig

定义构建期间执行的构建步骤。

BuildKit 内部使用 LLB 定义来执行构建步骤。构建步骤的 LLB 定义在 `buildDefinition.internalParameters.buildConfig.llbDefinition` 字段中定义。

每个 LLB 步骤都是 LLB ProtoBuf API 的 JSON 定义。LLB 图中某个顶点的依赖项可以在每个步骤的 `inputs` 字段中找到。

    "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 设置构建机器的 `builderPlatform`。请注意，这不一定是构建结果的平台，构建结果的平台可以通过 `in-toto` 主题字段确定。

buildDefinition.resolvedDependencies

定义构建中的所有外部工件。该值取决于工件类型

  • 包含镜像源代码的 Git 仓库的 URL
  • 如果您从远程 tarball 构建，或者使用 Dockerfile 中的 `ADD` 命令包含的 HTTP URL
  • 构建期间使用的任何 Docker 镜像

Docker 镜像的 URL 将采用 Package URL 格式。

所有构建材料都将包含工件的不可变校验和。从可变标签构建时，您可以使用摘要信息来确定工件与构建运行时相比是否已更新。

    "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

该字段设置为构建的 URL（如果可用）。

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

此值可以使用 `builder-id` 证明参数进行设置。

runDetails.metadata.invocationID

构建调用的唯一标识符。当使用单个构建请求构建多平台镜像时，此值将由镜像的所有平台版本共享。

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

runDetails.metadata.startedOn

构建开始时间戳。

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

runDetails.metadata.finishedOn

构建完成时间戳。

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

runDetails.metadata.buildkit_metadata

此扩展字段定义了 BuildKit 特有的额外元数据，这些元数据不是 SLSA 出处规范的一部分。

    "runDetails": {
      "metadata": {
        "buildkit_metadata": {
          "source": {...},
          "layers": {...},
          "vcs": {...},
        },
        ...
      },
    }

source

仅包含在 `mode=max` 中。

定义 LLB 构建步骤（在 `buildDefinition.internalParameters.buildConfig.llbDefinition` 字段中定义）到其原始源代码（例如 Dockerfile 命令）的源映射。`source.locations` 字段包含在 LLB 步骤中运行的所有 Dockerfile 命令的范围。`source.infos` 数组包含源代码本身。如果 BuildKit 前端在创建 LLB 定义时提供了此映射，则此映射存在。

层

仅包含在 `mode=max` 中。

定义 `buildDefinition.internalParameters.buildConfig.llbDefinition` 中定义的 LLB 构建步骤挂载到等效层的 OCI 描述符的层映射。如果层数据可用，通常在证明是针对镜像时或如果构建步骤将镜像数据拉入构建中时，此映射存在。

vcs

包含 `mode=min` 和 `mode=max`。

定义构建使用的版本控制系统的可选元数据。如果构建使用 Git 仓库的远程上下文，BuildKit 会自动提取版本控制系统的详细信息并将其显示在 `buildDefinition.externalParameters.configSource` 字段中。但如果构建使用本地目录中的源代码，即使该目录包含 Git 仓库，VCS 信息也会丢失。在这种情况下，构建客户端可以发送额外的 `vcs:source` 和 `vcs:revision` 构建选项，BuildKit 会将它们作为额外元数据添加到出处证明中。请注意，与 `buildDefinition.externalParameters.configSource` 字段相反，BuildKit 不验证 `vcs` 值，因此不能信任它们，只能将其用作元数据提示。

runDetails.metadata.buildkit_hermetic

如果构建是密封的并且未访问网络，则此扩展字段设置为 true。在 Dockerfile 中，如果构建不使用 `RUN` 命令或使用 `--network=none` 标志禁用网络，则构建是密封的。

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

runDetails.metadata.buildkit_completeness

此扩展字段定义出处信息是否完整。它类似于 SLSA v0.2 中的 `metadata.completeness` 字段。

如果所有构建参数都包含在 `buildDefinition.externalParameters.request` 字段中，则 `buildkit_completeness.request` 为 true。当以 `min` 模式构建时，构建参数不包含在出处信息中，请求不完整。在未使用前端的直接 LLB 构建中，请求也不完整。

如果 `buildDefinition.resolvedDependencies` 字段包含构建的所有依赖项，则 `buildkit_completeness.resolvedDependencies` 为 true。当从本地目录中未跟踪的源构建时，依赖项不完整，而当从远程 Git 仓库构建时，所有依赖项都可以由 BuildKit 跟踪，并且 `buildkit_completeness.resolvedDependencies` 为 true。

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

runDetails.metadata.buildkit_reproducible

此扩展字段定义构建结果是否应该逐字节可重现。它类似于 SLSA v0.2 中的 `metadata.reproducible` 字段。用户可以使用 `reproducible=true` 证明参数设置此值。

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

SLSA v0.2

builder.id

该字段设置为构建的 URL（如果可用）。

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

此值可以使用 `builder-id` 证明参数进行设置。

buildType

`buildType` 字段设置为 `https://mobyproject.org/buildkit@v1`，可用于确定出处内容的结构。

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

invocation.configSource

描述初始化构建的配置。

    "invocation": {
      "configSource": {
        "uri": "https://github.com/moby/buildkit.git#refs/tags/v0.11.0",
        "digest": {
          "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0"
        },
        "entryPoint": "Dockerfile"
      },
      ...
    },

对于从远程上下文（如 Git 或 HTTP URL）初始化的构建，此对象在 `uri` 和 `digest` 字段中定义上下文 URL 及其不可变摘要。对于使用本地前端（如 Dockerfile）的构建，`entryPoint` 字段定义了初始化构建的前端文件的路径（`filename` 前端选项）。

invocation.parameters

描述传递给构建的构建输入。

    "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": []
      },
      ...
    },

以下字段包含在 `mode=min` 和 `mode=max` 中：

  • `locals` 列出构建中使用的所有本地源，包括构建上下文和前端文件。

  • `frontend` 定义用于构建的 BuildKit 前端类型。目前，这可以是 `dockerfile.v0` 或 `gateway.v0`。

  • `args` 定义传递给 BuildKit 前端的构建参数。

    `args` 对象中的键反映了 BuildKit 接收到的选项。例如，`build-arg` 和 `label` 前缀用于构建参数和标签，`target` 键定义了构建的目标阶段。如果使用了 Gateway 前端，`source` 键定义了源镜像。

以下字段仅包含在 `mode=max` 中

  • `secrets` 定义构建期间使用的秘密。请注意，不包括实际的秘密值。
  • `ssh` 定义构建期间使用的 ssh 转发。

invocation.environment

    "invocation": {
      "environment": {
        "platform": "linux/amd64"
      },
      ...
    },

BuildKit 目前设置的唯一值是当前构建机器的 `platform`。请注意，这不一定是构建结果的平台，构建结果的平台可以通过 `in-toto` 主题字段确定。

materials

定义构建中的所有外部工件。该值取决于工件类型

  • 包含镜像源代码的 Git 仓库的 URL
  • 如果您从远程 tarball 构建，或者使用 Dockerfile 中的 `ADD` 命令包含的 HTTP URL
  • 构建期间使用的任何 Docker 镜像

Docker 镜像的 URL 将采用 Package URL 格式。

所有构建材料都将包含工件的不可变校验和。从可变标签构建时，您可以使用摘要信息来确定工件与构建运行时相比是否已更新。

    "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

定义构建期间执行的构建步骤。

BuildKit 内部使用 LLB 定义来执行构建步骤。构建步骤的 LLB 定义在 `buildConfig.llbDefinition` 字段中定义。

每个 LLB 步骤都是 LLB ProtoBuf API 的 JSON 定义。LLB 图中某个顶点的依赖项可以在每个步骤的 `inputs` 字段中找到。

  "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

构建调用的唯一标识符。当使用单个构建请求构建多平台镜像时，此值将由镜像的所有平台版本共享。

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

metadata.buildStartedOn

构建开始时间戳。

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

metadata.buildFinishedOn

构建完成时间戳。

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

metadata.completeness

定义出处信息是否完整。

如果所有构建参数都包含在 `parameters` 字段中，则 `completeness.parameters` 为 true。当以 `min` 模式构建时，构建参数不包含在出处信息中，参数不完整。在未使用前端的直接 LLB 构建中，参数也不完整。

`completeness.environment` 对于 BuildKit 构建始终为 true。

如果 `materials` 字段包含构建的所有依赖项，则 `completeness.materials` 为 true。当从本地目录中未跟踪的源构建时，材料不完整，而当从远程 Git 仓库构建时，所有材料都可以由 BuildKit 跟踪，并且 `completeness.materials` 为 true。

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

metadata.reproducible

定义构建结果是否应该逐字节可重现。用户可以使用 `reproducible=true` 证明参数设置此值。

    "metadata": {
      "reproducible": false,
      ...
    },

metadata.https://mobyproject.org/buildkit@v1#hermetic

包含 `mode=min` 和 `mode=max`。

如果构建是密封的并且未访问网络，则此扩展字段设置为 true。在 Dockerfile 中，如果构建不使用 `RUN` 命令或使用 `--network=none` 标志禁用网络，则构建是密封的。

    "metadata": {
      "https://mobyproject.org/buildkit@v1#hermetic": true,
      ...
    },

metadata.https://mobyproject.org/buildkit@v1#metadata

`mode=min` 部分包含。

此扩展字段定义了 BuildKit 特有的额外元数据，这些元数据不是 SLSA 出处规范的一部分。

    "metadata": {
      "https://mobyproject.org/buildkit@v1#metadata": {
        "source": {...},
        "layers": {...},
        "vcs": {...},
      },
      ...
    },

source

仅包含在 `mode=max` 中。

定义 LLB 构建步骤（在 `buildConfig.llbDefinition` 字段中定义）到其原始源代码（例如 Dockerfile 命令）的源映射。`source.locations` 字段包含在 LLB 步骤中运行的所有 Dockerfile 命令的范围。`source.infos` 数组包含源代码本身。如果 BuildKit 前端在创建 LLB 定义时提供了此映射，则此映射存在。

层

仅包含在 `mode=max` 中。

定义 `buildConfig.llbDefinition` 中定义的 LLB 构建步骤挂载到等效层的 OCI 描述符的层映射。如果层数据可用，通常在证明是针对镜像时或如果构建步骤将镜像数据拉入构建中时，此映射存在。

vcs

包含 `mode=min` 和 `mode=max`。

定义构建使用的版本控制系统的可选元数据。如果构建使用 Git 仓库的远程上下文，BuildKit 会自动提取版本控制系统的详细信息并将其显示在 `invocation.configSource` 字段中。但如果构建使用本地目录中的源代码，即使该目录包含 Git 仓库，VCS 信息也会丢失。在这种情况下，构建客户端可以发送额外的 `vcs:source` 和 `vcs:revision` 构建选项，BuildKit 会将它们作为额外元数据添加到出处证明中。请注意，与 `invocation.configSource` 字段相反，BuildKit 不验证 `vcs` 值，因此不能信任它们，只能将其用作元数据提示。

© . This site is unofficial and not affiliated with Kubernetes or Docker Inc.