软件物料清单 SBOM怎样把依赖清单绑定到构建产物为什么结果为空或不符合预期

SBOM 结果为空，很多时候不是“没有依赖”，而是依赖清单没有和读者正在查询的那个构建产物建立同一个身份。最容易踩坑的组合是：构建阶段扫描了源码目录，发布阶段却去查询最终镜像；或者 SBOM 绑定在某个 tag 上，读取时 tag 已经指向了另一份镜像。

这类问题的核心做法很简单：先拿到最终构建产物的不可变摘要，再对这个产物生成 SBOM，并把 SBOM 作为 attestation 绑定到同一个摘要。文件名、上传时间和可变 tag 都只能当辅助信息，不能替代产物身份。

如果你希望 SBOM 能回答“这个正在部署的产物包含什么”，扫描输入必须是正在部署的产物，绑定和读取也必须使用同一个 digest、同一个 attestation 类型以及仓库实际支持的存储关系。

先分清你要描述的是哪一个产物

同一个项目通常至少会出现三份看起来相似的依赖清单：

标题中的“绑定到构建产物”，通常指第三行。它不要求把所有信息塞进一个 JSON 文件，而是要求在发布系统里保留一条可追溯关系：SBOM 文档描述了什么，最终产物的 digest 是什么，两者通过 attestation 或等价的 subject 关系连接起来。

先固定最终产物的不可变身份

不要在流水线开头就把 latest 当成绑定对象。构建和推送完成后，先把真正要部署的镜像解析成 digest；如果对象不是容器镜像，也要为发布包或二进制保存内容摘要。下面的命令只展示流水线的关系，不代表在本文环境中执行过。

# 用最终发布镜像的不可变摘要作为后续操作的唯一身份
IMAGE="registry.example.com/shop/api@sha256:替换为最终镜像摘要"

# 对部署对象本身生成 SPDX SBOM，而不是只扫描源码目录
syft "$IMAGE" -o spdx-json=sbom.spdx.json

# 将 SBOM 作为 attestation 绑定到同一个镜像摘要
cosign attest --yes \
  --predicate sbom.spdx.json \
  --type https://spdx.dev/Document \
  "$IMAGE"

这里有三个必须保持一致的值：扫描输入对应的产物、attestation 的 subject 对应的产物，以及之后查询时使用的产物。Syft 官方项目说明支持从镜像和文件系统等输入生成 SPDX、CycloneDX 等格式；Sigstore 的示例则展示了把 SPDX 文件作为 predicate 附加到镜像的方式。

为什么“生成了 SBOM”却看不到绑定

只生成 sbom.spdx.json 并不会自动建立产物关系。它只是一个文档文件，除非发布系统把它作为产物附件、attestation 或受支持的引用关系保存，否则消费端没有稳定的入口知道它属于哪个镜像。

另外，IMAGE 里的 digest 不是装饰性的字符串。相同仓库中的两个 tag 可能先后指向不同 manifest；如果生成时使用 digest-A，读取时却按后来移动到 digest-B 的 tag 查询，出现空结果或依赖数量变化都很自然。

按四个边界排查空结果

一、扫描输入边界

先问“扫描器实际读到了什么”。扫描源码目录得到的是开发侧依赖，扫描最终镜像得到的是部署侧内容；扫描构建镜像又是另一份集合。如果流水线把扫描命令放在镜像构建之前，生成的清单自然不会包含后续复制进镜像的运行时文件。

二、产物身份边界

把构建日志中的镜像 digest、SBOM 生成记录和部署清单并排保存。若三者不相同，先修正流水线变量，而不是给 SBOM 增加更多包。常见原因包括重新推送覆盖 tag、矩阵构建没有把架构写进产物名，以及上传后又重新压缩或重打包。

三、类型与格式边界

生成端使用 SPDX，查询端却只筛选 CycloneDX，或者 attestation 的 predicate type 与读取端过滤的类型不一致，都会表现成“没有结果”。读取逻辑至少要记录三项：subject digest、predicate type、SBOM 格式。不要只记录一个模糊的“上传成功”。

四、仓库与消费端边界

SBOM 可能已经被上传，但消费端使用的仓库接口不提供同样的 referrer/attestation 查询方式，或者查询权限看不到附件。此时要分别确认“生成成功”“绑定请求成功”“仓库保存成功”和“当前身份可以读取”，不要把四个状态合并成一个绿色步骤。

用一张记录表避免版本串线

发布流水线不需要保存一堆难以检索的日志，只要为每个最终产物写一条结构化记录。严格 JSON 不支持注释，字段含义放在表格中说明：

{
  "artifact_digest": "sha256:...",
  "sbom_file": "sbom.spdx.json",
  "sbom_format": "spdx-json",
  "predicate_type": "https://spdx.dev/Document",
  "source_stage": "final-image",
  "repository": "registry.example.com/shop/api",
  "build_id": "build-2026-11-09-001"
}

artifact_digest 是查询和绑定的主键；source_stage 用来提醒团队这份 SBOM 是源码、构建环境还是最终产物；predicate_type 让消费端能准确筛选类型。不要把访问令牌、私钥或含敏感路径的构建变量写入这条记录。

什么时候空结果其实是正确的

空结果不一定表示工具坏了。一个只包含静态链接二进制的极简运行时镜像，可能和带包管理器缓存的构建镜像拥有完全不同的组件集合；查询某个不在部署层的开发依赖，结果为空反而符合扫描范围。正确做法是回到“这份清单要回答谁”的问题，换成相匹配的 subject，而不是把多个阶段的 SBOM 强行合并成一份。

同样，镜像是多架构 manifest 时，平台级 digest 与具体架构 manifest 不是同一个对象。若工具在一个层级生成 attestation、在另一个层级查询，必须确认两边是否支持同样的关联语义；否则应把平台选择和摘要记录写得更明确。

最后只保留四个复查动作

1. 确认 SBOM 的扫描输入就是待部署的最终构建产物，而不是相邻阶段目录。
2. 从构建产物记录中复制不可变 digest，生成、绑定、读取全程不改成可变 tag。
3. 核对 SBOM 格式与 predicate type，确保消费端过滤条件和生成端一致。
4. 分别记录生成、绑定、仓库存储和读取权限四个状态，定位空结果落在哪一层。

相关问题

SBOM 文件放进镜像里就算绑定了吗？

不算。放进镜像可以让文件随镜像分发，但消费端仍需要知道文件描述的是哪个对象；以不可变 digest 为 subject 的 attestation 或等价关系更适合做机器读取和追溯。

为什么同一个 tag 查到的 SBOM 会变化？

tag 是可移动引用。镜像重新推送后，tag 可能指向新的 digest；要复查历史构建，应保存并使用当次构建的 digest。

应该只生成一份 SBOM 吗？

不一定。源码、构建环境和最终部署产物回答不同问题，可以分别生成；关键是给每份清单标明扫描阶段和对应 subject，不要让读者误以为它们描述的是同一对象。

总结

SBOM 绑定构建产物的关键不是把 JSON 文件上传到某个目录，而是建立可重复的身份关系：扫描最终对象，使用不可变摘要，明确 SBOM 格式与 predicate type，再由消费端按同一个 subject 读取。遇到空结果时，沿着扫描输入、产物身份、类型格式、仓库读取四个边界逐层判断，通常比继续重跑生成命令更快找到原因。