SBOM 證明 (軟體物料清單證明)
軟體物料清單 (SBOM) 證明描述映像檔包含哪些軟體構件，以及用於建立映像檔的構件。SBOM 中用於描述軟體構件的中繼資料可能包含：
- 構件名稱
- 版本
- 授權類型
- 作者
- 唯一套件識別碼
在建置期間索引映像檔內容比掃描最終映像檔更有益。當掃描作為建置的一部分進行時，您可以偵測到用於建置映像檔但可能不會顯示在最終映像檔中的軟體。
BuildKit 產生的 SBOM 遵循 SPDX 標準。SBOM 會以 JSON 編碼的 SPDX 文件形式附加到最終映像檔，並使用 in-toto SPDX 述詞定義的格式。
建立 SBOM 證明
要建立 SBOM 證明，請將 `--attest type=sbom` 選項傳遞給 `docker buildx build` 命令
$ docker buildx build --tag <namespace>/<image>:<version> \
--attest type=sbom --push .
或者，您可以使用簡寫 `--sbom=true` 選項來代替 `--attest type=sbom`。
有關如何使用 GitHub Actions 新增 SBOM 證明的範例，請參閱使用 GitHub Actions 新增證明。
驗證 SBOM 證明
在將映像檔推送至 registry 之前，請務必驗證為映像檔產生的 SBOM。
要進行驗證，您可以使用 `local` 匯出器建置映像檔。使用 `local` 匯出器建置會將建置結果儲存到您的本機檔案系統，而不是建立映像檔。證明會寫入到匯出根目錄中的 JSON 檔案。
$ docker buildx build \
--sbom=true \
--output type=local,dest=out .
SBOM 檔案會顯示在輸出根目錄中，名稱為 `sbom.spdx.json`
$ ls -1 ./out | grep sbom
sbom.spdx.json
參數
預設情況下，BuildKit 只會掃描映像檔的最後一個階段。產生的 SBOM 不包含安裝在先前階段或存在於建置上下文中的建置時相依性。這可能會導致您忽略這些相依性中的漏洞，而這些漏洞可能會影響最終建置構件的安全性。
例如，您可能會使用多階段建置，並在最後一個階段使用 `FROM scratch` 子句來縮小映像檔大小。
FROM alpine AS build
# build the software ...
FROM scratch
COPY --from=build /path/to/bin /bin
ENTRYPOINT [ "/bin" ]掃描使用此 Dockerfile 範例建置的結果映像檔將不會顯示在 `build` 階段中使用的建置時相依性。
要包含 Dockerfile 中的建置時相依性，您可以設定建置參數 `BUILDKIT_SBOM_SCAN_CONTEXT` 和 `BUILDKIT_SBOM_SCAN_STAGE`。這會擴展掃描範圍以包含建置上下文和其他階段。
您可以將這些參數設定為全域參數（在宣告 Dockerfile 語法指示詞之後，第一個 `FROM` 命令之前）或在每個階段中個別設定。如果全域設定，則值會傳播到 Dockerfile 中的每個階段。
`BUILDKIT_SBOM_SCAN_CONTEXT` 和 `BUILDKIT_SBOM_SCAN_STAGE` 建置參數是特殊值。您無法使用這些參數執行變數替換，也無法使用 Dockerfile 中的環境變數來設定它們。設定這些值的唯一方法是在 Dockerfile 中使用明確的 `ARG` 命令。
掃描建置上下文
要掃描建置上下文，請將 `BUILDKIT_SBOM_SCAN_CONTEXT` 設定為 `true`。
# syntax=docker/dockerfile:1
ARG BUILDKIT_SBOM_SCAN_CONTEXT=true
FROM alpine AS build
# ...您可以使用 `--build-arg` CLI 選項來覆蓋 Dockerfile 中指定的值。
$ docker buildx build --tag <image>:<version> \
--attest type=sbom \
--build-arg BUILDKIT_SBOM_SCAN_CONTEXT=false .
請注意，僅將選項作為 CLI 參數傳遞，而沒有在 Dockerfile 中使用 `ARG` 宣告它，將不會有任何效果。您必須在 Dockerfile 中指定 `ARG`，才能使用 `--build-arg` 覆蓋上下文掃描行為。
掃描階段
要掃描的階段不只是最後一個階段，請將 `BUILDKIT_SBOM_SCAN_STAGE` 參數設定為 true，可以全域設定或在您要掃描的特定階段中設定。下表說明了此參數的不同可能設定。
| 值 | 說明 |
|---|---|
BUILDKIT_SBOM_SCAN_STAGE=true | 啟用目前階段的掃描 |
BUILDKIT_SBOM_SCAN_STAGE=false | 停用目前階段的掃描 |
BUILDKIT_SBOM_SCAN_STAGE=base,bin | 啟用名為 `base` 和 `bin` 的階段的掃描 |
只會掃描已建置的階段。不是目標階段相依性的階段將不會建置或掃描。
以下 Dockerfile 範例使用多階段建置，透過 Hugo 來建置靜態網站。
# syntax=docker/dockerfile:1
FROM alpine as hugo
ARG BUILDKIT_SBOM_SCAN_STAGE=true
WORKDIR /src
COPY <<config.yml ./
title: My Hugo website
config.yml
RUN apk add --upgrade hugo && hugo
FROM scratch
COPY --from=hugo /src/public /在 hugo 階段設定 ARG BUILDKIT_SBOM_SCAN_STAGE=true 可確保最終的 SBOM 包含使用 Alpine Linux 和 Hugo 建立網站的資訊。
使用 local 匯出器建置此映像檔會建立兩個 JSON 檔案。
$ docker buildx build \
--sbom=true \
--output type=local,dest=out .
$ ls -1 out | grep sbom
sbom-hugo.spdx.json
sbom.spdx.json
檢查 SBOM
要探索透過 image 匯出器匯出的已建立 SBOM，您可以使用 imagetools inspect。
使用 --format 選項，您可以指定輸出的範本。所有與 SBOM 相關的資料都可在 .SBOM 屬性下取得。例如，要取得 SPDX 格式的 SBOM 原始內容：
$ docker buildx imagetools inspect <namespace>/<image>:<version> \
--format "{{ json .SBOM.SPDX }}"
{
"SPDXID": "SPDXRef-DOCUMENT",
...
}
小技巧
如果映像檔是多平台的，您可以使用
--format '{{ json (index .SBOM "linux/amd64").SPDX }}'檢查特定平台索引的 SBOM。
您也可以使用 Go 範本的完整功能建構更複雜的表達式。例如，您可以列出所有已安裝的套件及其版本識別碼：
$ docker buildx imagetools inspect <namespace>/<image>:<version> \
--format "{{ range .SBOM.SPDX.packages }}{{ .name }}@{{ .versionInfo }}{{ println }}{{ end }}"
adduser@3.118ubuntu2
apt@2.0.9
base-files@11ubuntu5.6
base-passwd@3.5.47
...
SBOM 產生器
BuildKit 使用掃描器插件產生 SBOM。預設情況下，它使用的是 BuildKit Syft 掃描器