pip-audit 的 SBOM 输出实测:下游拿不到的五样东西
TL;DR:pip-audit -f cyclonedx-json 产出的 JSON 能通过 1.4 / 1.5 / 1.6 / 1.7 四版官方 schema 校验,零报错;但 35 个组件里 purl 是 0 个、哈希 0 个、许可证 0 个,dependencies 35 条全是空壳、依赖边 0 条,metadata 里只有一个时间戳。它能当漏洞报告的附件用,不能当资产清单交给下游。要清单,同一环境用 cyclonedx-py 能拿到 35 个 purl 和 39 条依赖边。
先说结论:这份文件是漏洞报告的附件,不是资产清单
2026-11-09 我写过 pip-audit 2.10.1 的扫描结果怎么读,当时明确写了一句「没碰 SBOM 和 CycloneDX 输出」。这一篇就补上那一块:不再讲漏洞怎么读,而是讲把文件交出去之后,下游到底能拿它做什么。
结论先说死:pip-audit 的 CycloneDX 输出是一份格式合法但语义稀薄的文件。它不是坏文件——schema 能过、工具能读、字段名都对;它是空文件,每一个下游真正需要的字段都恰好是可选字段,于是全都空着。
下面每一条都是我在本机跑出来的,命令和输出原文都贴了。
实测环境与两条命令
- Windows 11,CPython 3.13.12
- pip-audit 2.10.1(PyPI 当前版本)
- cyclonedx-python-lib 11.12.0(pip-audit 的 CycloneDX 依赖)
- 对照工具 cyclonedx-py 8.0.1(CycloneDX 官方 Python 实现,即 cyclonedx-bom 包)
- 校验器 jsonschema 4.26.0,schema 取自 cyclonedx-python-lib 11.12.0 自带的四份官方文件
被测环境是一个干净的 venv,装了 flask==3.1.3 与 requests==2.34.2,再加上 pip-audit 自己:
python -m pip_audit --format cyclonedx-json -o base.json --progress-spinner off
第二组环境刻意装了老版本(requests 2.19.0 / Jinja2 2.11.2 / urllib3 1.23 / idna 2.7 / chardet 3.0.4),好让 vulnerabilities 数组里真的有东西。
空白一:35 个组件,0 个 purl
第一份 BOM 有 35 个组件,每个组件的全部字段就是这四个:
{"bom-ref": "BomRef.10813865932059208.4858470511441134",
"name": "CacheControl", "type": "library", "version": "0.14.4"}
purl 数量 0/35,hashes 0/35,licenses 0/35,externalReferences 0/35。
为什么 purl 重要,CycloneDX 官方文档在 purl 字段下写得很直白:"Asserts the identity of the component using package-url (purl)" —— 它断言的是「这个组件是谁」,不是「它叫什么」。少了这个断言,下游只能自己按名字猜。
猜的代价在这个文件里立刻可见:同一个 BOM 里同时出现 CacheControl、pip_api、boolean.py 三种写法。用 purl 归一化之后它们分别是 pkg:pypi/cachecontrol、pkg:pypi/pip-api、pkg:pypi/boolean.py——大小写要不要压、下划线要不要变连字符、点号保不保留,全得你自己实现一遍 PEP 503 归一化。实现错了不会报错,只会匹配不上,然后漏洞库里那一条就这么静默漏过去。
空白二:35 个组件,0 条依赖边
这一条比 purl 更致命。文件里有 dependencies 数组,长度正好 35,看起来像是图建好了:
"dependencies": [
{"ref": "BomRef.004782033393651575.9086783281722834"},
{"ref": "BomRef.005548436256527678.8461533511536604"}
]
35 条记录,没有一条带 dependsOn,边数 0。这份图是 35 个孤点。
CycloneDX 官方规格页对依赖图的定义是「capable of representing both direct and transitive relationships」,直接与传递关系都要能表达。孤点图一层都表达不了。
后果很具体:拿到这份 BOM,你答不出「urllib3 是被谁拉进来的」。而这个问题恰恰是处置漏洞时要问的第一个——是直接依赖,还是 Flask 或 requests 的传递依赖?决定你改 requirements 还是等上游。同一台机器、同一个环境换 cyclonedx-py 8.0.1 生成对照文件,dependencies 里 35 条记录带 39 条 dependsOn,Flask 那一条明确写出 Jinja2 / MarkupSafe / Werkzeug / blinker / click / itsdangerous 六条边。数据一直都在,只是 pip-audit 没往外写。
空白三:metadata 里没有 tools,也没有 component
metadata 的全部内容是:
{"timestamp": "2026-11-10T22:14:12.494737+00:00"}
一个键。
官方规格页对 BOM metadata 的定义是两部分:「the target component for which the BOM describes」和「the tools used to create the BOM」。这两样在这份文件里都没有。
没有 tools,收到文件的人无法回答「这份 SBOM 是谁、哪个版本生成的」——半年后审计追溯时,这一条就是断链。没有 metadata.component,文件里没有任何一处说明「这是哪个项目的 BOM」,它只是一袋包。
顺便说句公道话:cyclonedx-py 8.0.1 的 metadata.tools 有,metadata.component 也是 null。所以「缺 BOM 主体」不是 pip-audit 独有的问题,cyclonedx-py environment 模式同样不写;但 tools 这一项两边一个有一个没有,差距是真实的。
空白四:vulnerabilities 只有四个字段,aliases 对它无效
含漏洞那份 BOM 有 38 条 vulnerabilities,每条的全部字段是:id、description、recommendation、affects、bom-ref。就这样。
- 没有
ratings:38 条里 0 条有 CVSS 分数或 severity 分级。下游按严重度排序,全部落在「未评级」。 - 没有
source:PYSEC-2018-28这种号出自 OSV 体系,但文件里没写它来自哪个库。下游想回源核对,只能猜。 - 没有
analysis:可修复性、处置状态一个都没有。 - 没有 aliases:而 pip-audit 的
--aliases默认是auto。我显式加--aliases on再跑一次,产出文件里"aliases"字段出现 0 次,CVE-字样只在 6 处出现在 description 的自然语言里(38 条中)。
这不是 bug,是写在帮助文本里的设计。pip-audit --help 原文:--desc 与 --aliases 都是「This flag has no effect on the cyclonedx-json or cyclonedx-xml formats」。所以想按 CVE 号查这份 SBOM,只能靠描述文本里恰好提到——38 条里只有 6 处。
recommendation 则一律硬编码成 Upgrade,没有目标版本。对比 11-09 那篇讲过的 JSON 格式:那边每条漏洞都带 fix_versions(哪一版能修)。同一份数据,JSON 里有、SBOM 里没有。
空白五:本地包被静默丢出 BOM
这条最容易被当成「没问题」。我在 requirements 里写一行本地目录:
./localpkg
-f json 的输出老老实实告诉你它跳过了:
{"name": "localdemo", "skip_reason": "Dependency not found on PyPI and could not be audited: localdemo (0.1.0)"}
换成 -f cyclonedx-json,产出文件是:metadata、serialNumber、version、$schema、bomFormat、specVersion 六个键,components 键根本不存在。控制台打印「No known vulnerabilities found」,退出码 0。
源码里就一行:if dep.is_skipped(): continue。跳过的依赖被直接跳过,连个空组件都不留。
这意味着:你的项目自己那一层代码(本地包、可编辑安装的内部库)在 SBOM 里完全不存在,而文件表面上依然合法、依然能上传、依然能通过校验。一份宣称描述你的应用、却把你的应用丢掉的清单,这是我认为最该警惕的一种「通过」。
四版 schema 全过,这才是最危险的地方
我把含漏洞那份文件分别喂给 1.4 / 1.5 / 1.6 / 1.7 四份官方 schema:
--- 1.4: 0 errors
--- 1.5: 0 errors
--- 1.6: 0 errors
--- 1.7: 0 errors
四版全绿。原因不复杂:上面说的每一个字段——purl、hashes、licenses、dependsOn、metadata.component、ratings、source、analysis——在 schema 里都是可选。必填项只有 bomFormat 和 specVersion 两个。
所以「SBOM 校验通过」这句话的信息量约等于零。它只证明文件能被解析器读,不证明文件里有内容。如果你的 CI 里唯一门禁是 cyclonedx validate,那这个门禁对这份文件恒真,等于没装。
同一环境,三个数字对不上:49 / 38 / 25
这是我这轮最没料到的一处。老版本环境下:
- 控制台:
Found 49 known vulnerabilities in 5 packages - JSON 格式:49 行漏洞记录
- CycloneDX 格式:38 条
vulnerabilities
差 11 条。逐条对拍后原因是:JSON 里同一包的同一公告重复出现了两次,两行逐字节相同(同 id、同 aliases、同 description),而 CycloneDX 侧把漏洞存成有序集合,去重键里含 id、description、affects,完全相同的行被合并了。
但合并不彻底:38 条里只有 25 个唯一公告号,另外 13 条是「同号但描述不同」——一条是 OSV 原始描述,一条是 GHSA advisories 风格的描述。去重键里含 description,于是两条都留下了。
结果是同一台机器、同一个环境、同一次审计,三个官方口径给出三个数字:49、38、25。你在周报里写哪个都能被质疑。我的做法是报唯一公告号(25),另外两个数只用来对拍工具是否换了行为。
specVersion 固定 1.4:一行源码与三个版本的差距
文件里写的是:
"$schema": "http://cyclonedx.org/schema/bom-1.4.schema.json", "specVersion": "1.4"
CycloneDX 官方规格页现在写的是 1.7,发布日期 2025-10-21,已作为 ECMA-424 发布。pip-audit 用的是 1.4,差三个大版本。
这不是环境问题,是硬编码。pip-audit 源码 pip_audit/_format/cyclonedx.py 里那句:
schema_version=output.SchemaVersion.V1_4
而它依赖的 cyclonedx-python-lib 11.12.0 自己支持到 1.7(SchemaVersion 枚举里 V1_7 到 V1_0 八个值都在)。工具链能产 1.7,调用方钉死在 1.4。
差距有多大,直接比 schema 定义:1.7 的 vulnerability 定义比 1.4 多三个字段(workaround、proofOfConcept、rejected),component 定义多十个(authors、manufacturer、swhid、omniborId、modelCard 等)。也就是说「这个漏洞有没有缓解办法」「这个组件是谁制造的」这类问题的字段位,1.4 里根本不存在。
对照:同一环境交给 cyclonedx-py 会得到什么
同一个 venv、同样 35 个组件,两个工具的产出逐项对比:
| 项目 | pip-audit 2.10.1 | cyclonedx-py 8.0.1 |
|---|---|---|
| specVersion | 1.4 | 1.6 |
| 组件数 | 35 | 35 |
| 有 purl | 0 | 35 |
| 有 licenses | 0 | 35 |
| 有 externalReferences | 0 | 35 |
| 有 hashes | 0 | 0 |
| 依赖边 dependsOn | 0 | 39 |
| metadata.tools | 无 | 有 |
| metadata.component | 无 | 无(null) |
| bom-ref 形态 | BomRef 加随机数 | CacheControl==0.14.4 |
| vulnerabilities | 有(4 字段) | 无(environment 模式不含) |
两个工具的分工在这张表里很清楚:pip-audit 给漏洞,cyclonedx-py 给清单。想让一份文件同时干两件事,得自己拼。
顺带一个细节值得记:cyclonedx-py 的 bom-ref 是 CacheControl==0.14.4,稳定且可读;pip-audit 的是 BomRef.10813865932059208.4858470511441134,每次运行都变。我连跑两次同一环境:serialNumber 不同,8 个组件的 bom-ref 0/8 相同,25 个漏洞的 bom-ref 0/25 相同。
如果你的 CI 里做「SBOM 与本季度基线 diff,有变化就告警」,这份文件每次都会 100% 变化。告警会响,但你查不出任何东西。
--fix 与 CycloneDX 互斥:修好了,文件里没痕迹
这条是我原本没打算测、顺手撞上的。命令:
python -m pip_audit --path 环境路径 --fix -f cyclonedx-json -o fix.json
控制台:
Found 49 known vulnerabilities in 5 packages and fixed 49 vulnerabilities in 5 packages
WARNING:pip_audit._format.cyclonedx:--fix output is unsupported by CycloneDX formats
漏洞真修了 49 条,包真的升级了;但 SBOM 里没有任何修复痕迹——没有升级前版本、没有升级后版本、没有 fix_versions,recommendation 还是那三个字 Upgrade。
源码里对应的是那一句 logger.warning("--fix output is unsupported by CycloneDX formats"),也就是「不支持」只以一条 WARNING 表达。如果你的脚本只检查退出码(这次是 0),你会以为「修完的 SBOM 已经归档」。
交付前必须补的四件事
1. 别用 pip-audit 的 SBOM 当资产清单。要清单跑 cyclonedx-py environment venv 里的 python 路径,要漏洞跑 pip-audit,两份文件用组件数对拍(我这里是 35 对 35,一致)。
2. 自己加三道完整性断言,不要只跑 schema 校验:每个组件有 purl 吗(比例应为 100%)?sum(len(dep.get("dependsOn", []))) 大于 0 吗?metadata.component 指向你的项目吗?这三问任一为否,文件就不该进制品库。
3. diff 之前先归一化。把 serialNumber 和所有 bom-ref 剥掉再比,否则每次都是全量变化。
4. 别把 --fix 和 CycloneDX 混用。要么分两步(先用 pip-audit --fix 改环境,再重新生成 SBOM),要么用 JSON 格式拿 fix_versions。
Troubleshooting:四个原样报错
报错一:格式名写错,退出码 2
pip-audit: error: argument -f/--format: invalid OutputFormatChoice value: 'cyclonedx'
合法值只有 columns、json、cyclonedx-json、cyclonedx-xml、markdown 五个(pip-audit --help 原文)。写 cyclonedx 是最常见的手误,注意它是两个值不是一族。
报错二:--require-hashes 撞上没写哈希的 requirements
ERROR:pip_audit._virtual_env:internal pip failure: ERROR: Hashes are required in --require-hashes mode,
but they are missing from some requirements.
这行以 internal pip failure 开头,很容易被当成 pip-audit 自己的 bug。实际是 pip 在临时虚拟环境里装依赖时拒绝了——你要么补 --hash=sha256:...,要么去掉 --require-hashes。注意 pip 已经把该写的哈希值打印出来了,直接抄。
报错三:requirements 路径不存在
ERROR:pip_audit._cli:invalid requirements input: nope.txt
只一行 ERROR,没有栈,退出码 1。在 CI 里如果不打印 stderr,这条看起来就像「审计无结果」。
报错四:-o 的目录不存在,审计白跑
Found 37 known vulnerabilities in 3 packages
Traceback (most recent call last):
...
FileNotFoundError: [Errno 2] No such file or directory: 'nodir\\x.json'
注意顺序:先打印「找到 37 条」,再崩在写文件上。审计已经跑完、网络和时间都花了,结果在落盘那一刻丢掉,退出码 1。pip-audit 不会替你创建输出目录。
另外还有一个不算报错但更阴的:-f cyclonedx-xml -o xml-out.json 会把 XML 原样写进一个 .json 文件名,退出码 1(因为有漏洞)、零报错。CycloneDX 官方约定的文件名是 bom.json / bom.xml,或后缀 *.cdx.json / *.cdx.xml;下游很多工具按扩展名选解析器,名字写错就解析失败。
本文的边界
说清楚没测的部分,比多写三条结论更有用:
- 没有把 BOM 上传到 Dependency-Track 或任何商业 SCA 平台。所以「下游到底怎么处理没有 purl 的组件」我只写了推断(按 name+version 匹配、需要自己做归一化),没有实测。
- 没有测 1.7 的新字段能不能被下游消费,只比对了 schema 定义。
- 没有测 Syft、cdxgen 等其它生成器,对照只做了 cyclonedx-py 一个。
hashes两边都是 0,我没有进一步追查是 pip 元数据里没有、还是两个工具都没取。这一条存疑。
写这篇的过程中我反复回到一个判断上:格式合法与信息可用是两件事,而所有自动化门禁默认只检查前者。我实际测试了四版 schema,全部零报错;而文件里五个下游最需要的字段,五个全空。
本文不含任何联盟推广链接。想按同一层往前追,可以看 11-09 那篇扫描结果怎么读,或者往上游一整层看版本钉死的语法边界;如果你更关心「包装进来之后会不会写到目录外」,那是解压执行层的问题。
FAQ
Q:pip-audit 的 SBOM 能直接上传到 SCA 平台吗?
能上传,多数平台也能解析。但组件没有 purl,平台只能按 name+version 去匹配,CacheControl 与 cachecontrol 这类写法差异要靠平台自己的归一化兜。建议把 cyclonedx-py 的产出当资产清单,pip-audit 的产出只当漏洞附件。
Q:specVersion 只有 1.4,会不会不兼容?
不会。1.4 是向后兼容最好的版本,老平台都认。代价是拿不到 1.5 之后新增的字段(workaround、proofOfConcept、rejected 等)。如果你的流程需要「缓解办法」这类信息,1.4 的容器里没地方放。
Q:我只要漏洞报告,还需要 SBOM 吗?
要,但两者回答的问题不同。漏洞报告答「有什么洞」,SBOM 答「这个洞是谁引进来的、影响哪几个服务」。前者决定修不修,后者决定改哪个文件、通知哪个团队。
Q:为什么本地包会从 SBOM 里消失?
pip-audit 对无法在 PyPI 上解析的依赖会标记为 skipped。JSON 格式会把 skip_reason 写出来,CycloneDX 格式在源码里直接跳过,不留任何痕迹,退出码仍是 0。可编辑安装与内部私有包最容易踩这一条。
Q:两次生成的 BOM 完全不一样,正常吗?
正常。serialNumber 每次新生成,bom-ref 是随机串。要比内容,先把这两个字段剥掉,再按 name 加 version 建索引比对。
👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务
👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速
📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测
🔗 精选推荐工具
使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):
作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。