sbom-tool/sbom-tools
GitHub: sbom-tool/sbom-tools
基于Rust的语义化SBOM差异分析与TUI工具，支持CycloneDX和SPDX格式，用于追踪组件变更、漏洞与合规性。
Stars: 76 | Forks: 4
sbom-tools
准确了解您的软件供应链中发生了什么变化。
语义化 SBOM 差异与分析工具。支持跨 CycloneDX 和 SPDX 格式进行 SBOM 的比较、验证和质量评估。
## 功能特性
- **语义化差异比对** — 组件级别的变更检测（新增、移除、修改）、依赖图差异比对、漏洞追踪以及许可证变更分析
- **多格式支持** — 支持 CycloneDX (1.4–1.6) 和 SPDX (2.2–2.3)，格式包括 JSON、XML、tag-value 和 RDF/XML，并支持自动格式检测
- **流式解析器** — 针对超大 SBOM（>512MB）的内存高效解析，并提供进度报告
- **模糊匹配** — 多层匹配引擎，利用精确 PURL 匹配、别名查找、生态系统特定的标准化、以及带有自适应阈值和 LSH 索引的字符串相似度进行匹配
- **漏洞增强** — 集成 OSV 和 KEV 数据库以追踪新增和已解决的漏洞（受功能门控限制）
- **EOL 检测** — 通过 endoflife.date API 检测组件的终止支持状态，提供 TUI 可视化和合规性集成（受功能门控限制）
- **质量评估** — 根据合规标准对 SBOM 进行评分，包括 NTIA、FDA、CRA (网络弹性法案)、NIST SSDF 和 EO 14028
- **集群比较** — 1:N 基线比较、跨版本时间线分析以及 NxN 矩阵分析
- **增量差异比对** — 跨 SBOM 版本跟踪变更，包含漂移检测和偏差分析
- **多种输出格式** — JSON、SARIF、HTML、Markdown、CSV、表格、并排视图、摘要以及交互式 TUI
- **生态系统感知** — 可配置的按生态系统标准化规则、typosquat 检测以及跨生态系统包关联
## 安装
### 从 crates.io 安装
```
cargo install sbom-tools
```
### 从源码构建
需要 Rust 1.86+。
```
# 发布版本 build（默认包含漏洞 enrichment）
cargo build --release
# 无 enrichment（轻量级 build）
cargo build --release --no-default-features
```
二进制文件位于 `target/release/sbom-tools`。
## 使用方法
```
# 比较两个 SBOM
sbom-tools diff old-sbom.json new-sbom.json
# 交互式查看 SBOM 内容
sbom-tools view sbom.json
# 跨 SBOM 搜索组件
sbom-tools query "log4j" --version "<2.17.0" fleet/*.json
# 验证合规性
sbom-tools validate sbom.json --standard ntia
# 评估质量
sbom-tools quality sbom.json --profile security --recommendations
```
### Diff (差异比对)
```
sbom-tools diff old-sbom.json new-sbom.json
```
比较两个 SBOM，报告新增、移除和修改的组件，以及版本差异、漏洞变更和许可证变化。
Diff 选项
| 标志 | 描述 |
|------|-------------|
| `--fail-on-change` | 如果检测到变更，则以代码 1 退出 |
| `--fail-on-vuln` | 如果引入了新漏洞，则以代码 2 退出 |
| `--graph-diff` | 启用依赖图结构差异比对 |
| `--ecosystem-rules ` | 加载自定义的按生态系统标准化规则 |
| `--fuzzy-preset ` | 匹配预设：`strict` (严格)、`balanced` (均衡，默认)、`permissive` (宽松) |
| `--enrich-vulns` | 查询 OSV/KEV 数据库获取漏洞数据 |
| `--enrich-eol` | 通过 endoflife.date API 检测终止支持状态 |
| `--detect-typosquats` | 标记看起来像是已知包 typosquat 的组件 |
| `--explain-matches` | 显示每对组件被匹配的原因 |
示例输出
```
sbom-tools diff old-sbom.json new-sbom.json --enrich-vulns
SBOM Diff: old-sbom.json → new-sbom.json
Components: 142 → 145 (+5 added, -2 removed, ~3 modified)
+ pkg:npm/express@4.19.2 (added)
+ pkg:npm/zod@3.23.8 (added)
+ pkg:npm/opentelemetry-api@1.9.0 (added)
+ pkg:npm/ws@8.18.0 (added)
+ pkg:npm/pino@9.3.2 (added)
- pkg:npm/body-parser@1.20.2 (removed)
- pkg:npm/winston@3.11.0 (removed)
~ pkg:npm/lodash@4.17.20 → 4.17.21 (version bump)
~ pkg:npm/axios@1.6.0 → 1.7.4 (version bump)
~ pkg:npm/semver@7.5.4 → 7.6.3 (version bump)
Vulnerabilities:
✗ CVE-2024-29041 (HIGH) — express <4.19.2 [resolved by upgrade]
✗ CVE-2024-4068 (HIGH) — braces <3.0.3 [new, in transitive dep]
License changes: none
```
### View (查看)
```
sbom-tools view sbom.json
```
启动交互式 TUI，包含组件树、漏洞详情、许可证分类和依赖图。
View 选项
| 标志 | 描述 |
|------|-------------|
| `--severity ` | 按最低漏洞严重程度过滤 (`critical`, `high`, `medium`, `low`) |
| `--vulnerable-only` | 仅显示具有已知漏洞的组件 |
| `--ecosystem ` | 按生态系统过滤组件 (例如：`npm`, `cargo`, `pypi`) |
| `--enrich-eol` | 通过 endoflife.date API 检测终止支持状态 |
| `--validate-ntia` | 根据 NTIA 最低要素进行验证 |
### Validate (验证)
```
sbom-tools validate sbom.json --standard ntia
sbom-tools validate sbom.json --standard cra -o sarif -O results.sarif
```
根据合规标准检查 SBOM，并报告缺失的字段或未通过的要求。
Validate 选项
| 标志 | 描述 |
|------|-------------|
| `--standard ` | 要验证的标准：`ntia` (默认)、`fda`、`cra`、`ssdf`、`eo14028`（逗号分隔以支持多个） |
| `-o, --output ` | 输出格式 (默认：`json`；支持 `sarif` 用于 CI 集成) |
### Quality (质量)
```
sbom-tools quality sbom.json --profile security --recommendations
```
使用加权配置文件对 SBOM 进行 0-100 评分。使用 `--min-score` 可在质量低于阈值时使 CI 失败。
Quality 选项
| 标志 | 描述 |
|------|-------------|
| `--profile ` | 评分配置：`minimal`、`standard` (默认)、`security`、`license-compliance`、`cra`、`comprehensive` |
| `--min-score ` | 如果质量分数低于阈值 (0–100) 则失败 |
| `--recommendations` | 显示详细的改进建议 |
| `--metrics` | 显示详细的评分指标 |
### Query (查询)
```
sbom-tools query "log4j" sbom1.json sbom2.json sbom3.json
```
按名称、版本、生态系统、许可证、供应商或漏洞 ID 跨多个 SBOM 搜索组件。回答您整个 SBOM 集群中的“Log4j 在哪里？”这类问题。
Query 选项
| 标志 | 描述 |
|------|-------------|
| `--name ` | 按组件名称过滤 (子串) |
| `--version ` | 按版本过滤 — 精确匹配或 semver 范围 (例如：`<2.17.0`) |
| `--ecosystem ` | 按生态系统过滤 (例如：`npm`, `maven`, `pypi`) |
| `--license ` | 按许可证过滤 (子串) |
| `--purl ` | 按 PURL 过滤 (子串) |
| `--supplier ` | 按供应商名称过滤 (子串) |
| `--affected-by ` | 按漏洞 ID 过滤 (例如：`CVE-2021-44228`) |
| `--enrich-vulns` | 查询 OSV 数据库获取漏洞数据 |
| `--enrich-eol` | 通过 endoflife.date API 检测终止支持状态 |
| `--limit ` | 最大结果数 |
| `--group-by-sbom` | 按 SBOM 源对输出进行分组 |
示例输出
```
$ sbom-tools query "log4j" --version "<2.17.0" fleet/*.cdx.json
Query: "log4j" AND version=<2.17.0 across 5 SBOMs (1247 total components)
COMPONENT VERSION ECOSYSTEM LICENSE VULNS FOUND IN
log4j 2.14.0 maven Apache-2.0 1 firmware-v1, device-a
log4j 2.14.1 maven Apache-2.0 1 gateway
2 components found across 5 SBOMs
$ sbom-tools query --ecosystem pypi *.json --group-by-sbom
Query: ecosystem=pypi across 2 SBOMs (33 total components)
── backend-v3 (4 matches / 18 components) ──
django 4.2.11 (pypi)
flask 3.0.2 (pypi)
celery 5.3.6 (pypi)
numpy 1.26.4 (pypi)
── backend-v2 (4 matches / 15 components) ──
django 3.2.23 (pypi)
flask 2.2.5 (pypi)
celery 5.3.4 (pypi)
numpy 1.24.4 (pypi)
8 components found across 2 SBOMs
```
### 集群比较
比较项目组合中的多个 SBOM：
```
# 将基线与多个目标进行比较 (1:N)
sbom-tools diff-multi baseline.json target1.json target2.json target3.json
# 跟踪演变过程（按时间顺序提供 SBOM）
sbom-tools timeline v1.json v2.json v3.json
# 全对比较矩阵 (NxN)
sbom-tools matrix sbom1.json sbom2.json sbom3.json
```
### Shell 补全
```
sbom-tools completions bash > ~/.local/share/bash-completion/completions/sbom-tools
sbom-tools completions zsh > ~/.zfunc/_sbom-tools
sbom-tools completions fish > ~/.config/fish/completions/sbom-tools.fish
```
### 全局标志
| 标志 | 描述 |
|------|-------------|
| `-o, --output
` | 输出格式 (见 [输出格式](#output-formats)) |
| `-v, --verbose` | 启用调试输出 |
| `-q, --quiet` | 抑制非必要输出 |
| `--no-color` | 禁用彩色输出 (同时也遵循 `NO_COLOR` 环境变量) |
## 交互式 TUI
当连接到 TTY 时，`diff` 和 `view` 命令默认会启动交互式终端 UI。
### Diff 模式
在 9 个标签页中通过语义变更检测比较两个 SBOM。
**Summary (摘要)** — 总体变更评分，以及组件、漏洞和合规性的细分概览。
**Components (组件)** — 每个新增、移除和修改的组件，带有版本差异和生态系统标签。
更多 diff 截图
**Side-by-Side (并排)** — 对齐的双面板比较，支持同步滚动。
**Source (源码)** — 同步双面板树形视图中的原始 SBOM JSON。按 `s` 锁定面板间的导航。
**Compliance (合规性)** — CRA、NTIA、FDA、NIST SSDF 和 EO 14028 就绪检查，显示每项要求的通过/失败详情。
### View 模式
在 8 个标签页中交互式探索单个 SBOM。
**Overview (概览)** — SBOM 元数据、组件统计和漏洞摘要。
**Components (组件)** — 按生态系统分组的可展开组件树。
更多 view 截图
**Vulnerabilities (漏洞)** — CVE 表格，包含严重程度、CVSS 评分和受影响组件。
**Quality (质量)** — 加权质量评分，包含类别细分和改进建议。
### 导航
| 按键 | 动作 |
|-----|--------|
| `1`–`0` / `Tab` | 切换标签页 |
| `↑↓` / `jk` | 导航项目 |
| `Enter` / `Space` | 展开 / 折叠 |
| `/` | 搜索 |
| `f` | 过滤面板 |
| `s` | 同步面板 / 排序 |
| `w` | 切换焦点 |
| `v` | 树形 / 原始切换 |
| `e` | 导出 |
| `T` | 切换主题 |
| `q` | 退出 |
## 输出格式
使用 `-o` / `--output` 选择：
| 格式 | 标志 | 用例 |
|--------|------|----------|
| Auto | `auto` | 默认 — 如果是 TTY 则为 TUI，否则为摘要 |
| TUI | `tui` | 交互式探索 |
| JSON | `json` | 程序化集成 |
| SARIF | `sarif` | CI/CD 安全仪表板 (SARIF 2.1.0) |
| Markdown | `markdown` | 文档、PR 评论 |
| HTML | `html` | 利益相关者报告 |
| CSV | `csv` | 电子表格分析 |
| Summary | `summary` | 终端快速概览 |
| Table | `table` | 对齐、彩色的终端输出 |
| Side-by-side | `side-by-side` | 终端差异比较 |
## CI/CD 集成
在 CI 流水线中使用 sbom-tools，根据 SBOM 变更、新漏洞或质量退化来控制部署。
```
# 如果有任何组件变更则失败
sbom-tools diff old.json new.json --fail-on-change -o summary
# 如果有新漏洞引入则失败，为 dashboard 输出 SARIF
sbom-tools diff old.json new.json --fail-on-vuln --enrich-vulns -o sarif -O results.sarif
# 如果质量分数低于 80 则失败
sbom-tools quality sbom.json --profile security --min-score 80 -o json
# 验证 CRA 合规性
sbom-tools validate sbom.json --standard cra -o sarif -O compliance.sarif
# 检查所有 SBOM 中是否存在易受攻击的 Log4j 版本（如果发现则退出码为 1）
sbom-tools query "log4j" --version "<2.17.0" fleet/*.json -o json
```
GitHub Actions 示例
```
name: SBOM Check
on:
pull_request:
paths: ['sbom.json']
jobs:
sbom-gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 2
- name: Install sbom-tools
run: cargo install sbom-tools
- name: Diff SBOM against main
run: |
git show HEAD~1:sbom.json > /tmp/old-sbom.json
sbom-tools diff /tmp/old-sbom.json sbom.json \
--fail-on-vuln --enrich-vulns \
-o sarif -O results.sarif
- name: Upload SARIF
if: always()
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
```
### 退出代码
| 代码 | 含义 |
|------|---------|
| `0` | 成功 (未检测到变更，或未运行 `--fail-on-change`) |
| `1` | 检测到变更 (`--fail-on-change`) |
| `2` | 引入了新漏洞 (`--fail-on-vuln`) |
| `3` | 错误 |
## 配置
sbom-tools 按以下顺序查找配置：
1. CLI 参数：`--ecosystem-rules `
2. 环境变量：`SBOM_TOOLS_ECOSYSTEM_RULES`
3. 项目本地：`.sbom-tools/ecosystem-rules.yaml`
4. 用户配置：`~/.config/sbom-tools/ecosystem-rules.yaml`
请参阅 [`examples/ecosystem-rules.yaml`](examples/ecosystem-rules.yaml) 获取完整的配置示例，涵盖按生态系统标准化、别名、匹配预设和增强设置。
### 匹配预设
| 预设 | 描述 |
|--------|-------------|
| `strict` | 仅精确匹配 |
| `balanced` | 默认 — 使用标准化和适中的相似度阈值 |
| `permissive` | 针对噪声较大的 SBOM 进行激进模糊匹配 |
## 项目结构
```
src/
├── cli/ Command handlers (diff, view, validate, quality, query, fleet commands)
├── config/ YAML/JSON config with presets, validation, schema generation
├── model/ Canonical SBOM representation (NormalizedSbom, Component, CanonicalId)
├── parsers/ Format detection + parsing (streaming for >512MB)
├── matching/ Multi-tier fuzzy matching (PURL, alias, ecosystem, adaptive, LSH)
├── diff/ Semantic diffing engine with graph support + incremental diff
├── enrichment/ OSV/KEV vulnerability data + EOL detection (feature-gated), file cache with TTL
├── quality/ NTIA/FDA/CRA/NIST SSDF/EO 14028 compliance scoring
├── pipeline/ parse → enrich → diff → report orchestration
├── reports/ Output format generators + streaming reporter
└── tui/ Ratatui-based interactive UI
```
请参阅 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 了解详细的模块职责和数据流。
## 测试
```
# 运行所有测试
cargo test
# 运行 benchmarks
cargo bench
```
## 文档
- [架构概览](docs/ARCHITECTURE.md)
- [流程图](docs/pipeline-diagrams.md)
- [发布与更新日志](https://github.com/sbom-tool/sbom-tools/releases)
## 贡献
欢迎贡献！在提交 Pull Request 之前，请开一个 Issue 来讨论您的想法。请确保 `cargo test` 通过并遵循现有的代码风格。
许可证
[MIT](LICENSE)标签：CycloneDX, DevSecOps, Homebrew安装, Rust, SBOM, SBOM 比较, SPDX, TUI, 上游代理, 依赖管理, 可视化界面, 安全合规, 差异分析, 开源治理, 文档安全, 文档结构分析, 硬件无关, 组件变更追踪, 网络代理, 网络流量审计, 许可证冲突, 跌倒检测, 软件物料清单, 通知系统, 通知系统