前言¶
在供应链安全语境里，SBOM（软件物料清单）常被要求随产物交付：美国行政令 14028、NTIA《SBOM Minimum Elements》等文件都强调组件、标识符、时间戳等最低要素。团队里常见做法是跑 cyclonedx-npm、syft 或 spdx-sbom-generator 导出 bom.json，或把清单挂在 CI 里临时生成。问题在于：仓库里「有一份叫 SBOM 的文件」和「有一份下游能消费、能对照依赖的清单」往往不是一回事——空壳 JSON、把 npm ls 改名的文件、缺 bomFormat 的 XML、一年没更新的 CycloneDX，都会在审计或交付环节被追问。
DeepSeek Harness（DSH）把能力拆成插件。@deepwhale-cn/dsh-sbom（GitHub：feely0208/dsh-sbom，维护者 feely0208，分类：工作流）只做一件事：检查项目里已有的 SBOM 文件，不生成清单、不扫 CVE、不下合规结论。下面介绍它查什么、怎么装、怎么用，以及和 dsh-dep-audit 的分工。
这是什么¶
一句话：别的工具负责写清单，它负责查清单。
- 是：检查 SBOM 有没有、全不全、新不新、格式对不对；每条发现会给出文件路径、证据、依据与处理建议。
- 不是：SBOM 生成器、漏洞扫描器、许可证合规判定器；也不输出「合规 / 不合规」的终审结论，只描述事实。
与同属深鲸网安守护系列、侧重依赖树漏洞与许可证的 dsh-dep-audit 对比：
dsh-dep-audit = 查【依赖树】里的漏洞与许可证
dsh-sbom = 查【物料清单】本身有没有、全不全、新不新
npm 包名 @deepwhale-cn/dsh-sbom，当前版本 0.1.0，许可证 MIT。运行环境要求 Node.js >= 18，DSH >=0.1.0-rc.6 <0.3.0。
它查什么¶
内置五条规则，级别分为 high（🔴 在 CLI 输出里对应严重项）、medium（🟡）、low（🔵）：
| 规则 ID | 查什么 | 级别 |
|---|---|---|
SBOM-NO-LIST |
有 lockfile，却找不到任何 SBOM 文件 | high |
SBOM-EMPTY-SHELL |
SBOM 存在，但没有任何组件条目（空壳） | high |
SBOM-NOT-STANDARD |
缺少 bomFormat / spdxVersion，非标准格式 |
high |
SBOM-STALE |
SBOM 超过 180 天未更新（以文件修改时间为准） | medium |
SBOM-NO-IDENTIFIER |
组件仅有名字和版本，缺少 purl / CPE |
low |
判据出处包括：行政令 14028 第 4(e) 条、NTIA《SBOM Minimum Elements》、CycloneDX / SPDX 官方规范。可用 dsh-sbom --list-rules 查看内置说明与引用。
认哪些文件名（可位于任意子目录）：sbom.json、bom.json、*.cdx.json、*.spdx.json、*.sbom.json、cyclonedx.json、bom.xml、sbom.xml、*.cdx.xml、*.spdx。
认哪些格式：CycloneDX（JSON / XML）、SPDX（JSON / tag-value）。
默认会跳过 dist/、build/、node_modules/ 等目录；若清单只放在这些路径或使用了未列出的文件名，可能被报成「找不到」。
安装与启用¶
在已安装 DSH 的环境中，按官方 README 安装到 web profile：
dsh plugin --profile web add @deepwhale-cn/dsh-sbom
插件以当前 dsh 进程权限扫描指定目录下的文件。安装前建议自行查看 GitHub 仓库 源码与 MIT 许可证，确认符合团队策略。
典型用法¶
检查当前工作目录下的项目：
dsh-sbom
检查指定根目录：
dsh-sbom --root /path/to/project
查看内置样本（模拟「有 lockfile、清单却各种残缺」的 demo 项目）：
dsh-sbom --demo
生成 HTML 报告便于存档或截图：
dsh-sbom --root /path/to/project --html sbom.html
接入 CI：在 --quiet 模式下，若存在 high 级别命中，进程退出码为 1：
dsh-sbom --root . --quiet
README 中的 demo 样本同时存在于 tests/fixtures/fail/demo-project/：仓库里有四份「清单」文件，工具会分别报空壳、非标准格式、超过 180 天未更新、组件无唯一标识等；而 tests/fixtures/absent/minimal/ 则演示「有 lockfile、没有任何 SBOM 文件」时的 SBOM-NO-LIST。
合规样本见 tests/fixtures/pass/clean-project/（CycloneDX JSON+XML、SPDX JSON 三种格式）。维护者可用 bash tests/run.sh 做正例全报、反例零命中的双向验证。
适用场景与边界¶
适合：需要在交付或内审前快速确认「清单是否在仓库里、能否被标准工具消费、是否明显过期或缺标识」的团队；与生成类工具（cyclonedx-npm / syft / spdx-sbom-generator）和 dsh-dep-audit 搭配，覆盖「写清单 → 查清单 → 查依赖风险」的不同环节。
务必注意：
- 不生成清单——只读已有文件；生成仍依赖专用 SBOM 工具。
- 只看清单文件本身——不读产物二进制、不递归解析完整依赖树、不查 CVE。
- 不判定合规——例如清单仅在发布流水线临时生成、不入库，在许多团队是正常做法；工具仍会按规则提示，是否可接受由你方说明。
SBOM-STALE依赖文件 mtime——重新 checkout 或拷贝目录可能重置修改时间，导致过期项不报或误报；本地复现测试时 README 给出了对 demo 文件touch的示例。
