cyclonedx-bom 是生成 python 项目 sbom 的最佳轻量工具，支持 pip freeze、poetry.lock 等多种依赖源，需注意虚拟环境激活和显式指定配置文件，输出符合 cyclonedx 1.4 标准，满足供应链安全与合规分析要求。
用 cyclonedx-bom 生成 Python 项目的 SBOM
Python 官方没有内置 SBOM 生成功能，cyclonedx-bom 是目前最轻量、兼容性最好、且能直接读取 pip freeze 和 poetry.lock 的命令行工具。它不依赖构建系统，也不需要修改项目结构，适合 CI 中快速插入。
常见错误是直接运行 cyclonedx-bom 却没激活对应虚拟环境，导致输出的组件列表和实际部署环境不一致；另一个坑是默认只扫描当前目录下的 requirements.txt，而忽略 pyproject.toml 或 Pipfile —— 它其实支持，但得显式指定参数。
- 用
cyclonedx-bom --format json --output bom.json生成标准 CycloneDX JSON 格式 - 若项目用 Poetry，加
--poetry参数，否则它不会解析poetry.lock - 若用 pip-tools，需配合
--requirements requirements.txt（注意路径要对） - 不推荐用
--include-dev除非明确需要开发依赖进 SBOM，否则会混入测试/构建工具，干扰供应链分析
为什么不能用 pip show 或 pip list 直接当 SBOM
pip list 输出的是已安装包的名称和版本，但 SBOM 要求包含组件来源（如 PyPI URL）、许可证、哈希值、依赖关系图谱 —— 这些 pip list 根本不提供。更关键的是，pip show requests 返回的 License 字段常为空或不规范（比如写成 “Apache 2.0” 而非 SPDX ID Apache-2.0），下游合规工具会直接拒绝解析。
典型误用场景：把 pip freeze > requirements.txt 当作 SBOM 提交到客户审计流程，结果被退回，因为缺少许可证声明和组件层级关系。
立即学习“Python免费学习笔记（深入）”；
-
pip freeze不体现包来源（PyPI / GitHub / local path），无法追溯供应链风险 - 不包含
direct-dependency标记，分不清哪些是显式声明、哪些是传递依赖 - 无校验和（
bom-ref和hashes字段），无法验证组件完整性
与 syft + grype 配合时的格式陷阱
如果后续要用 syft 扫描镜像、再用 grype 做漏洞匹配，必须确保 SBOM 是 CycloneDX 1.4+ 或 SPDX 2.3+ 格式。cyclonedx-bom 默认输出的就是 CycloneDX 1.4，但老版本 syft（grype 不认 —— 它只接受标准 CycloneDX 或 SPDX。
容易踩的坑是：在 CI 中先跑 syft -o cyclonedx-json，又手动跑 cyclonedx-bom，结果两个 SBOM 里同一包的 bom-ref 格式不一致（比如 pkg:pypi/requests@2.31.0 vs pkg:pypi/requests@2.31.0?extension=tar.gz），导致 grype 匹配失败，漏报漏洞。
- 统一用
cyclonedx-bom生成，避免混用工具链 - 检查输出 JSON 中的
$schema字段是否为https://cyclonedx.org/schema/bom-1.4.schema.json - 若集成进 GitHub Actions，别用
actions/setup-python自带的旧版cyclonedx-bom，显式pip install cyclonedx-bom==4.2.0
poetry export 导出的 requirements.txt 不够用
poetry export -f requirements.txt 确实能导出带哈希的依赖列表，但它仍是纯文本，没有结构化元数据，也没法表达可选依赖（extras）、环境标记（platform_system == "Linux"）或 VCS 依赖（如 git+https://...）。SBOM 工具需要把这些信息转成 components 数组里的 properties 和 externalReferences。
一个真实案例：某项目用了 django[argon2]，poetry export 会把 argon2-cffi 当作普通依赖输出，但 SBOM 必须标记它是通过 extras 引入的，否则策略引擎无法判断该组件是否属于“启用的安全模块”。
- 别把
poetry export结果当 SBOM，只可作为中间输入 - 用
cyclonedx-bom --poetry --include-optional才能正确展开extras - VCS 依赖（如
mylib @ git+https://github.com/x/y.git@v1.2）必须用--poetry模式，否则会被跳过
SBOM 不是“多生成一个文件”，而是让每个包的来源、许可、哈希、关系都可验证。工具链越短，字段越全，后续做合规或漏洞响应时越不容易卡在数据断层上。
