Docker Buildx 怎么给镜像同时生成 SBOM 和来源证明

Docker Buildx 同时生成 SBOM 和来源证明，关键不是把两个文件放到镜像目录里，而是在构建时打开两类 attestation，并把结果以 image index 的形式推送到仓库。最小命令是 --sbom=true --provenance=mode=max --push；其中 --push 让仓库保留构建元数据，不能用 --load 代替后再期待本地 classic image store 保存它们。

官方地址：https://docs.docker.com/build/metadata/attestations/

步骤一：先选能保存 attestations 的构建入口

先打开 Docker Desktop，沿着 Settings > General 找到 containerd image store。如果当前环境没有这个开关，或者团队不准备切换默认镜像存储，就改用 docker-container driver。Docker 官方说明，classic image store 不能保存 image index；而 docker-container、kubernetes 和 remote driver 可以生成 attestations。

这一项不是界面偏好，而是结果能否留下来的前置条件。构建器页面里应能看到 attest-builder、driver 为 docker-container、节点状态为 running。看到这个状态后再进入下一步。

步骤二：在项目目录创建专用 Buildx builder

在项目目录打开命令入口，依次执行下面的命令。第一条创建隔离的 BuildKit 节点，第二条把当前项目切换到它，第三条确认节点可用：

# 创建支持 image index 的隔离构建节点
docker buildx create --name attest-builder --driver docker-container --use

# 启动并检查当前 builder 的节点状态
docker buildx inspect --bootstrap
docker buildx ls

结果中应有当前 builder 的名称和 docker-container driver，节点状态为 running。如果团队已经有共享 builder，不必重复创建，只要确认它不是只把结果加载到 classic image store 的本地路径。

步骤三：一次构建同时打开 SBOM、provenance 并推送

把下面的占位仓库替换为你有权限推送的地址。mode=max 会比默认的最小 provenance 记录更完整的构建信息；--sbom=true 使用 BuildKit 的 SBOM attestation；--push 将最终 image index 直接发到 registry。

# 同时生成 SBOM 和完整 provenance，并把带附件的 image index 推送到仓库
docker buildx build \
  --builder attest-builder \
  --tag registry.example.com/team/demo:1.0 \
  --sbom=true \
  --provenance=mode=max \
  --push \
  .

界面或构建输出出现 pushing manifest list、exporting attestation、naming to 等完成信号时，先记下镜像标签。不要把 --load 加在同一条命令里当作验收方式：它把结果加载到本地 daemon，是否能保留附件取决于 image store。

步骤四：检查镜像索引里的两类附件

回到 Docker Desktop 的 Builds/Images 结果入口，选择刚才的镜像标签，查看 Inspect manifest 或附件区域。应能看到 SBOM attestation 和 Provenance attestation 两个条目。如果需要命令行检查，可以输出 manifest JSON：

# 读取远端镜像索引及其附件，不拉取整个镜像文件系统
docker buildx imagetools inspect \
  --format '{{json .}}' \
  registry.example.com/team/demo:1.0

这里的判断标准是“远端镜像索引存在两类附件”，不是只看构建日志有没有成功。若检查不到，按顺序排查 builder driver、是否误用了 --load、registry 是否保留 OCI image index，以及构建命令是否真的包含两个开关。

常见问题

只写 --sbom=true 能得到来源证明吗？

不能。SBOM 是组件清单，provenance 是构建来源记录，两者是不同类型的 attestation；要同时生成就把两个选项都写进构建命令。

为什么构建成功但本地镜像里没有附件？

最常见是使用了 --load 或 classic image store。改用支持 image index 的 builder 并直接 --push，再检查 registry 端的 manifest。

provenance 会不会把密码写进去？

不要用 build args 传递账号、令牌或密码。来源证明会记录构建过程相关信息，秘密应使用 Docker 的 secret 机制，并在流水线中限制可见范围。

把构建器、存储方式、两个 attestation 开关和远端 manifest 四处对齐，就能稳定完成一次同时生成 SBOM 与来源证明的 Buildx 构建。SBOM 解决“镜像里有什么”，provenance 解决“镜像怎么来的”，两者都存在时才适合继续接入扫描或供应链审计。