Python SBOM 生成工具使用详解

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 提交到客户审计流程，结果被退回，因为缺少许可证声明和组件层级关系。

• 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（<1.0）默认输出 Syft JSON，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 不是“多生成一个文件”，而是让每个包的来源、许可、哈希、关系都可验证。工具链越短，字段越全，后续做合规或漏洞响应时越不容易卡在数据断层上。