TomTonic/extract-sbom

# 提取 SBOM extract-sbom 对软件交付物执行标准化的进料检验。 给定一个输入文件，它会生成： - 一份整合的 CycloneDX SBOM - 一份审计报告（人类可读的 Markdown、机器可读的 JSON，或两者兼有） 它会递归处理嵌套的容器和归档格式，应用安全 限制，记录提取/扫描决策，并通过 `extract-sbom:delivery-path` 元数据保持可追溯性。 具体的扫描策略，包括确定性和信任边界， 在 [SCAN_APPROACH.md](SCAN_APPROACH.md) 中进行了解释。 ## 为什么存在这个项目 软件采购团队定期从外部供应商接收交付物 —— ZIP 归档文件、MSI 安装程序、安装可执行文件 —— 并且必须验证这些交付物 在被接受和部署之前没有已知的漏洞 (CVE)。 这相当于软件的进料检验：在供应链至关重要的 环境中，任何东西在检查之前都不会被部署。相关的风险不仅 存在于顶层包中，而且贯穿于整个软件供应链 —— 传递依赖项、捆绑库以及隐藏在嵌套 安装程序格式中的组件。 现有的 SBOM 工具很好地覆盖了供应链的开发和构建阶段， 但没有一个能解决已打包的、不透明的供应商交付物的检查问题： - **[Syft](https://github.com/anchore/syft)** 从容器镜像、 源目录和简单的归档格式生成 SBOM。它不会递归解压 深层嵌套的归档文件或安装程序格式（MSI、CAB、InstallShield），不生成 可审计报告，也不为不受信任的输入提供沙箱。extract-sbom 在内部 使用 Syft 作为组件编目引擎，但单独的 Syft 无法处理 交付物检查工作流。 - **[cyclonedx-cli](https://github.com/CycloneDX/cyclonedx-cli)** 是一个 BOM 操作工具，用于转换、合并、比对、验证和签名现有的 SBOM 文档。它不具备从软件制品生成 SBOM 的能力，也没有 提取能力。 - **[microsoft/sbom-tool](https://github.com/microsoft/sbom-tool)** 从构建放置路径或源代码树生成 SPDX SBOM。它专为软件*生产者*设计，以便在 CI/CD 期间描述其 自己的产品 —— 而不是供*消费者*对外部供应商提供的 不透明二进制文件或安装程序进行进料检验。 - **[jimmykarily/sbom-extractor](https://github.com/jimmykarily/sbom-extractor)** 提取 先前作为 OCI 证明附加到容器镜像的 SBOM。它 专门在容器注册表镜像上运行，无法检查本地 接收的文件。它也完全依赖于供应商已将 SBOM 附加到镜像 —— 无法进行独立验证。 extract-sbom 填补了这一空白，将供应商交付文件作为检查 单元：一个文件输入，一个整合的 CycloneDX SBOM 和一份可审计的报告输出。 ### 功能对比 | 功能 | extract-sbom | Syft | cyclonedx-cli | microsoft/sbom-tool | jimmykarily/sbom-extractor | |---|:---:|:---:|:---:|:---:|:---:| | 专为进料检验设计 | ✓ | ✗ | ✗ | ✗ | ✗ | | 递归嵌套归档文件提取 | ✓ | ✗ | ✗ | ✗ | ✗ | | MSI / CAB / InstallShield 支持 | ✓ | ✗ | ✗ | ✗ | ✗ | | 单个交付文件输入 → 整合 SBOM 输出 | ✓ | ✗ | ✗ | ✗ | ✗ | | 可审计的提取报告 (Markdown / JSON) | ✓ | ✗ | ✗ | ✗ | ✗ | | SBOM 元数据中的交付路径可追溯性 | ✓ | ✗ | ✗ | ✗ | ✗ | | 针对不受信任供应商输入的沙箱执行 | ✓ | ✗ | ✗ | ✗ | ✗ | | 策略控制的提取（深度/大小限制） | ✓ | ✗ | ✗ | ✗ | ✗ | | 确定/可复现的输出 | ✓ | ✗ | ✗ | ✗ | ✗ | | 跨打包生态系统的组件编目 | ✓ (通过 Syft) | ✓ | ✗ | ✓ | ✗ | | CycloneDX 输出 | ✓ | ✓ | ✓ | ✗ | ~ | | 独立于容器注册表 / OCI | ✓ | ✓ | ✓ | ✓ | ✗ | | SBOM 操作（合并、比对、验证、签名） | ✗ | ✗ | ✓ | ✗ | ✗ | ## 它的作用 - 识别归档/容器格式（ZIP、TAR 变体、CAB、MSI、7z、RAR、InstallShield CAB） - 在策略和资源限制下递归提取 - 检测加密的 ZIP 条目，并自动将这些归档重新路由至 7-Zip - 对于由外部提取器处理的受密码保护格式，按顺序尝试配置的密码 - 在库模式下使用 Syft 进行组件编目 - 组装一个确定性的 CycloneDX 1.6 SBOM - 生成英文或德文的可审计报告 ## 加密归档文件与密码来源 对于加密归档文件，extract-sbom 支持从以下来源按顺序尝试密码： - `--password` (可重复) - `EXTRACT_SBOM_PASSWORDS` (逗号分隔) - `--password-file` (每行一个密码，允许使用 `#` 注释) 密码尝试按来源优先级排序： 1. 命令行参数 (`--password`) 2. 环境变量 (`EXTRACT_SBOM_PASSWORDS`) 3. 密码文件 (`--password-file`) 在提取过程中，extract-sbom 首先尝试不使用密码，然后按 顺序尝试每个已配置的密码。密码绝对不会打印在日志或报告中。 ## 可选的漏洞丰富化 (`--grype`) 如果启用了 `--grype`，extract-sbom 将针对生成的 SBOM 运行 Grype， 并在不改变 SBOM 结构或提取/扫描决策的情况下丰富审计报告。 - 摘要视图：受 grype 启发的漏洞表，包含 `Name`、已安装/已修复版本、 漏洞 ID、严重性（包括可用的 CVSS 评分）、EPSS、风险和 KEV。 - 详情视图：按包分组的出现索引，包含每次出现的漏洞状态 （`found`、`none`、`not-assessable`），包括类型、修复数据、CVSS 版本/评分/向量、 描述、EPSS 和可用的来源参考。 - 运行时诊断：Grype 版本/数据库元数据和显式的丰富状态 （`completed`、`completed-with-errors`、`unavailable`、`not-requested`）。 - 失败行为：如果缺少 Grype 或返回了无效/不可用的输出，SBOM 和报告 仍将生成；报告将记录丰富状态为不可用/不完整。 ## 快速开始 安装预构建的发布二进制文件（参见 [INSTALL.md](INSTALL.md)) 或 从源代码构建（参见 [BUILD.md](BUILD.md))。 运行（在 Linux 上使用 `bwrap` 的沙箱模式）： ``` mkdir -p out extract-sbom \ --output-dir out \ sample-delivery.zip ``` 运行（非沙箱模式，例如 macOS 或受信任的 CI）： ``` mkdir -p out extract-sbom \ --unsafe \ --output-dir out \ sample-delivery.zip ``` `out/` 中的典型输出（基本名称派生自输入文件）： - `sample-delivery.cdx.json` - `sample-delivery.report.md` (或 `.report.json`，取决于 `--report`) ## 文档 - [INSTALL.md](INSTALL.md)：安装和依赖故障排除 - [BUILD.md](BUILD.md)：从源代码构建和发布工具 - [USAGE.md](USAGE.md)：基于场景的用法、参数和输出 - [SCAN_APPROACH.md](SCAN_APPROACH.md)：面向操作员的扫描工作原理及结果可信度说明 - [DESIGN.md](DESIGN.md)：功能与安全设计 - [MODULE_GUIDE.md](MODULE_GUIDE.md)：模块架构与决策 ## CI 中的项目状态 核心 CI 目前检查构建、测试、竞态条件、覆盖率、代码检查， 外加用于模糊测试和发布候选验证的专用工作流。

标签：CycloneDX, DevSecOps, EVTX分析, JSON, Markdown, meg, SBOM提取, URL发现, WebSocket, 上游代理, 供应链审计, 依赖分析, 信任边界, 信息安全, 制品分析, 可追溯性, 安全合规, 安全检测, 对称加密, 日志审计, 网络代理, 自动化审计, 跌倒检测, 软件供应链安全, 软件物料清单, 远程方法调用, 递归解压