SLSA 定義

BuildKit 支援為其執行的構建建立 SLSA 出處。

BuildKit 生成的出處格式由 SLSA 出處格式定義（支援 v0.2 和 v1）。

本頁介紹 BuildKit 如何填充每個欄位，以及當您生成 `mode=min` 和 `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`

參考：https://slsa.dev/spec/v1.1/provenance#extension-fields
包含 `mode=min` 和 `mode=max`。

如果構建是密封的並且未訪問網路，則此擴充套件欄位設定為 true。在 Dockerfile 中，如果構建不使用 `RUN` 命令或使用 `--network=none` 標誌停用網路，則構建是密封的。

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

`runDetails.metadata.buildkit_completeness`

參考：https://slsa.dev/spec/v1.1/provenance#extension-fields
包含 `mode=min` 和 `mode=max`。

此擴充套件欄位定義出處資訊是否完整。它類似於 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`

參考：https://slsa.dev/spec/v1.1/provenance#extension-fields
包含 `mode=min` 和 `mode=max`。

此擴充套件欄位定義構建結果是否應該逐位元組可重現。它類似於 SLSA v0.2 中的 `metadata.reproducible` 欄位。使用者可以使用 `reproducible=true` 證明引數設定此值。

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

SLSA v0.2

`builder.id`

參考：https://slsa.dev/spec/v0.2/provenance#builder.id
包含 `mode=min` 和 `mode=max`。

該欄位設定為構建的 URL（如果可用）。

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

注意
此值可以使用 `builder-id` 證明引數進行設定。

`buildType`

參考：https://slsa.dev/spec/v0.2/provenance#buildType
包含 `mode=min` 和 `mode=max`。

`buildType` 欄位設定為 `https://mobyproject.org/buildkit@v1`，可用於確定出處內容的結構。

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

`invocation.configSource`

參考：https://slsa.dev/spec/v0.2/provenance#invocation.configSource
包含 `mode=min` 和 `mode=max`。

描述初始化構建的配置。

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

參考：https://slsa.dev/spec/v0.2/provenance#invocation.parameters
`mode=min` 部分包含。

描述傳遞給構建的構建輸入。

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

參考：https://slsa.dev/spec/v0.2/provenance#invocation.environment
包含 `mode=min` 和 `mode=max`。

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

BuildKit 目前設定的唯一值是當前構建機器的 `platform`。請注意，這不一定是構建結果的平臺，構建結果的平臺可以透過 `in-toto` 主題欄位確定。

`materials`

參考：https://slsa.dev/spec/v0.2/provenance#materials
包含 `mode=min` 和 `mode=max`。

定義構建中的所有外部工件。該值取決於工件型別

包含映象原始碼的 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`

參考：https://slsa.dev/spec/v0.2/provenance#buildConfig
僅包含在 `mode=max` 中。

定義構建期間執行的構建步驟。

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`

參考：https://slsa.dev/spec/v0.2/provenance#buildInvocationId
包含 `mode=min` 和 `mode=max`。

構建呼叫的唯一識別符號。當使用單個構建請求構建多平臺映象時，此值將由映象的所有平臺版本共享。

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

`metadata.buildStartedOn`

參考：https://slsa.dev/spec/v0.2/provenance#buildStartedOn
包含 `mode=min` 和 `mode=max`。

構建開始時間戳。

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

`metadata.buildFinishedOn`

參考：https://slsa.dev/spec/v0.2/provenance#buildFinishedOn
包含 `mode=min` 和 `mode=max`。

構建完成時間戳。

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

`metadata.completeness`

參考：https://slsa.dev/spec/v0.2/provenance#metadata.completeness
包含 `mode=min` 和 `mode=max`。

定義出處資訊是否完整。

如果所有構建引數都包含在 `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`

參考：https://slsa.dev/spec/v0.2/provenance#metadata.reproducible
包含 `mode=min` 和 `mode=max`。

定義構建結果是否應該逐位元組可重現。使用者可以使用 `reproducible=true` 證明引數設定此值。

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

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

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

    "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` 值，因此不能信任它們，只能將其用作元資料提示。

SLSA 定義

SLSA v1

`buildDefinition.buildType`

`buildDefinition.externalParameters.configSource`

`buildDefinition.externalParameters.request`

`buildDefinition.internalParameters.buildConfig`

`buildDefinition.internalParameters.builderPlatform`

`buildDefinition.resolvedDependencies`

`runDetails.builder.id`

`runDetails.metadata.invocationID`

`runDetails.metadata.startedOn`

`runDetails.metadata.finishedOn`

`runDetails.metadata.buildkit_metadata`

`source`

`層`

`vcs`

`runDetails.metadata.buildkit_hermetic`

`runDetails.metadata.buildkit_completeness`

`runDetails.metadata.buildkit_reproducible`

SLSA v0.2

`builder.id`

`buildType`

`invocation.configSource`

`invocation.parameters`

`invocation.environment`

`materials`

`buildConfig`

`metadata.buildInvocationId`

`metadata.buildStartedOn`

`metadata.buildFinishedOn`

`metadata.completeness`

`metadata.reproducible`

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

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

`source`

`層`

`vcs`