isecwire/fw-sbom
GitHub: isecwire/fw-sbom
一款为固件供应链安全设计的 SBOM 生成器，帮助满足欧盟 CRA 合规要求。
Stars: 0 | Forks: 0
# fw-sbom
[](https://github.com/isecwire/fw-sbom/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.rust-lang.org/)
固件软件物料清单（SBOM）生成器。扫描提取的固件镜像以识别软件组件，并生成机器可读的SBOM文档，格式为**SPDX 2.3**或**CycloneDX 1.6** JSON。
旨在帮助设备制造商和集成商满足**欧盟网络安全韧性法案（CRA）**的透明度要求，该法案要求带有数字元件的产品在投放市场时附带准确的软件物料清单。
## 功能
`fw-sbom` 分析提取的固件目录树，并通过多种检测方法识别软件组件：
1. **ELF 动态链接**——解析 ELF 二进制文件并提取动态链接的共享库（例如 `libssl.so`、`libz.so`），将其映射到已知软件包。
2. **深度 ELF 分析**——提取 SONAME、NEEDED 条目、RPATH/RUNPATH、构建 ID（来自 `.dynamic` 段）；从 `.comment` 段检测编译器（GCC/Clang 版本）；检查安全加固标志（PIE、RELRO、NX、堆栈保护器）。
3. **字符串签名扫描**——在二进制内容中搜索 54 多种常见嵌入式软件包的已知版本字符串和标识符。
4. **软件包管理器元数据**——读取 `opkg` 和 `dpkg` 状态文件以及各个 `.control` 文件，提取已安装软件包及其精确版本。
5. **文件系统元数据**——解析 `/etc/os-release` 和 `/etc/openwrt_release` 以获取发行版信息。
6. **许可证检测**——扫描 LICENSE/COPYING 文件中的已知许可证文本，检测 SPDX-License-Identifier 头，并将软件包映射到许可证。
7. **加密算法检测**——通过扫描算法常量（S 盒值、初始化向量）识别 AES 和 SHA-256 实现。
8. **内核配置分析**——解析 `/boot/config-*` 以获取与安全相关的内核设置（堆栈保护器、ASLR、SELinux、seccomp 等）。
对于每个发现的组件，该工具记录：名称、版本（可检测时）、SHA-256 哈希、SPDX 许可证标识符、软件包 URL（purl）、检测方法以及置信度分数。
## v1.1.0 新特性
- **VEX 生成**（`--vex`）：生成配套 OpenVEX 文档，将已知 CVE 映射到组件及其可利用性状态。
- **SBOM 合并**（`--merge`）：合并多个 SBOM 文件，按名称和版本去重。
- **模式验证**（`--validate`）：对生成的 SBOM JSON 进行结构验证，确保包含必需字段。
- **并行扫描**：文件分析现在使用 rayon 进行多线程扫描，在多核系统上显著更快。
- **CycloneDX 1.6**：输出已从规范 1.5 更新至 1.6。
- **可机器读取的静默模式**：`--quiet` 现在会将 JSON 摘要输出到标准错误。
- **减少误报**：文档和许可证文件已从二进制签名扫描中排除。
- **符号链接处理**：不再跟踪符号链接文件，避免错误的 SHA-256 哈希。
请参阅 [CHANGELOG.md](CHANGELOG.md) 查看完整版本历史。
## 构建
需要 Rust 1.70+ 和 Cargo。
```
cd tools/fw-sbom
cargo build --release
```
生成的可执行文件位于 `target/release/fw-sbom`。
## 用法
```
fw-sbom [OPTIONS]
Arguments:
Path to extracted firmware directory or file to analyze
Options:
-f, --format Output SBOM format: spdx or cyclonedx [default: spdx]
-o, --output Output file path (prints to stdout if omitted)
-n, --name Firmware / product name [default: firmware]
--fw-version Firmware / product version [default: 0.0.0]
--diff Compare with another SBOM file (diff mode)
--enrich Add CPE identifiers and vulnerability hints
--graph Output dependency graph in DOT format
--exclude Exclude paths matching pattern (repeatable)
--min-confidence Minimum confidence score 0.0-1.0 [default: 0.0]
--merge ... Merge multiple SBOM files into one
--vex Generate VEX document alongside SBOM
--validate Validate generated SBOM against JSON schema
--quiet Suppress colored output; emit JSON summary to stderr
-h, --help Print help
-V, --version Print version
```
### 示例
从提取的 OpenWrt 根文件系统生成 SPDX SBOM：
```
fw-sbom ./openwrt-rootfs/ \
--format spdx \
--name "gateway-fw" \
--fw-version "2.4.1" \
--output gateway-sbom.spdx.json
```
生成带有 CPE 丰富信息和 VEX 的 CycloneDX SBOM：
```
fw-sbom ./extracted-firmware/ \
--format cyclonedx \
--enrich \
--vex \
--output firmware-sbom.cdx.json
```
这将同时生成 `firmware-sbom.cdx.json`（SBOM）和 `firmware-sbom.vex.json`（VEX 文档）。
比较两个固件 SBOM 以查看版本之间的变更：
```
fw-sbom old-sbom.spdx.json --diff new-sbom.spdx.json
```
将多个固件分区的 SBOM 合并为一个：
```
fw-sbom dummy --merge rootfs-sbom.json modem-sbom.json radio-sbom.json \
--name "combined-fw" --output combined.spdx.json
```
验证生成的 SBOM：
```
fw-sbom ./firmware/ --validate --output sbom.spdx.json
```
以 DOT 格式生成依赖关系图并用 Graphviz 渲染：
```
fw-sbom ./firmware-rootfs/ --graph --quiet > deps.dot
dot -Tpng deps.dot -o deps.png
```
按置信度过滤——仅包含高置信度检测结果：
```
fw-sbom ./firmware/ --min-confidence 0.7 --format spdx
```
排除测试和文档目录：
```
fw-sbom ./firmware/ --exclude test --exclude doc --exclude man
```
### 示例输出（缩写版 SPDX）
```
{
"spdxVersion": "SPDX-2.3",
"dataLicense": "CC0-1.0",
"SPDXID": "SPDXRef-DOCUMENT",
"name": "gateway-fw",
"documentNamespace": "https://spdx.org/spdxdocs/gateway-fw-2.4.1-...",
"creationInfo": {
"created": "2026-04-03T10:00:00Z",
"creators": ["Tool: fw-sbom 1.1.0", "Organization: isecwire GmbH"]
},
"packages": [
{
"SPDXID": "SPDXRef-Package-0",
"name": "busybox",
"versionInfo": "1.36.1",
"licenseConcluded": "GPL-2.0-only",
"checksums": [{"algorithm": "SHA256", "checksumValue": "a1b2c3..."}],
"externalRefs": [
{"referenceType": "purl", "referenceLocator": "pkg:generic/busybox@1.36.1"},
{"referenceType": "cpe23Type", "referenceLocator": "cpe:2.3:a:busybox:busybox:1.36.1:*:*:*:*:*:*:*"}
]
}
]
}
```
## 检测能力
### 置信度评分
每个组件根据其检测方法被赋予一个置信度分数：
| 方法 | 置信度 | 描述 |
|------|--------|------|
| 软件包管理器 | 95% | 来自 opkg/dpkg 状态文件 |
| 文件系统元数据 | 90% | 来自 os-release、openwrt_release |
| 内核配置 | 85% | 来自 /boot/config-* |
| 深度 ELF | 75% | 来自 .comment/.dynamic 段 |
| ELF 动态链接 | 70% | 来自 NEEDED 库条目 |
| 许可证文件 | 65% | 来自 LICENSE/COPYING 文件 |
| 加密常量 | 60% | 来自算法常量 |
| 字符串签名 | 50% | 来自版本字符串 |
### 支持的组件签名（54+）
**核心嵌入式组件**：BusyBox、OpenSSL、U-Boot、zlib、curl、Dropbear、lighttpd、dnsmasq、SQLite、mbedTLS、wolfSSL、lwIP、FreeRTOS、libnl、libpcap、glibc、musl、uClibc、iptables、Linux 内核
**网络相关**：mosquitto、nginx、wpa_supplicant、hostapd、NetworkManager、iproute2、nftables、tcpdump、avahi、BlueZ
**系统服务**：systemd、D-Bus、OpenSSH、bash、coreutils
**脚本运行时**：Lua、Python、Node.js
**库文件**：libxml2、libpng、libjpeg、expat、ncurses、readline、jansson
**OpenWrt 特定组件**：ubus、procd、netifd、libubox、libuci、uhttpd、swconfig
**调试工具**：strace、GDB、valgrind
### VEX（漏洞可利用性交换）
使用 `--vex` 时，会生成配套的 OpenVEX 文档，将每个已知 CVE 提示映射到其组件。默认情况下，所有 CVE/组件对均标记为 `under_investigation`，因为自动化工具无法确认其可利用性。安全团队随后可将条目更新为 `not_affected`、`affected` 或 `fixed`。
### SBOM 合并
`--merge` 标志会加载多个 SBOM 文件（SPDX 或 CycloneDX JSON），提取各组件内容，按名称+版本去重（保留置信度更高的条目），并输出统一的 SBOM。
### CPE / 漏洞丰富化
使用 `--enrich` 时，每个组件会附加以下信息：
- **CPE 2.3 标识符**：基于内置的 50 多个软件包字典进行映射
- **已知 CVE 提示**：来自针对常见嵌入式软件包的高严重性漏洞 curated 数据库
### SBOM 差异比较
`--diff` 模式会比较两个 SBOM 文件（SPDX 或 CycloneDX），并报告：
- 新增组件
- 移除组件
- 版本变更
- 未变更组件数量
### 依赖关系图
`--graph` 模式会输出 DOT 格式的有向图，展示哪些 ELF 二进制文件链接到哪些共享库。可使用 Graphviz 或任何兼容 DOT 的工具进行渲染。
### ELF 安全加固检测
对于每个 ELF 二进制文件，该工具会检查并报告：
- **PIE**（位置无关可执行文件）
- **RELRO**（重定位只读）
- **堆栈保护器**（__stack_chk_fail）
- **NX**（不可执行 / W^X）
- **编译器版本**来自 .comment 段）
## CRA 合规性上下文
欧盟网络安全韧性法案（CRA）第 13 条要求制造商“识别和记录产品中存在的漏洞和组件，包括编制软件物料清单”。每个带有数字元件的产品在投放欧盟市场时都必须附带 SBOM。
`fw-sbom` 自动完成该流程的第一步：发现固件镜像中实际存在的软件内容，即使没有构建系统清单。其输出可直接输入到漏洞数据库（例如 OSV、NVD）进行已知漏洞匹配。配套的 VEX 文档支持 CRA 的漏洞披露要求。
## 常见问题
### 什么是 SBOM？
**SBOM**（软件物料清单）是设备中包含的所有软件组件的**列表**。就像食品包装上的配料表，但用于软件。例如：你的网关包含 Linux 内核 5.15、BusyBox 1.36、OpenSSL 3.1、U-Boot 2023.10。SBOM 是一个结构化的 JSON 文档，列出所有这些信息及其版本、哈希和许可证。
### 什么是 CRA，为什么重要？
**CRA**（欧盟网络安全韧性法案）是欧盟的一项**新法律**（执法于 2027 年）。它**要求**所有带有软件的制造商（物联网设备、路由器、网关等）：
- 向客户提供 SBOM
- 监控其组件中的已知漏洞（CVE）
- 及时修补安全漏洞
**不合规的处罚**：最高可达 1500 万欧元或全球收入的 2.5%。这不是可选项——这是法律。
fw-sbom 会自动生成符合要求的 SBOM。
### 实际使用方式
```
# 从提取的固件生成 SPDX SBOM
fw-sbom /path/to/firmware/ --format spdx --name "Gateway-Pro" --fw-version "2.1.0" --output sbom.json
# 使用漏洞丰富功能生成
fw-sbom /path/to/firmware/ --format cyclonedx --enrich --output sbom-enriched.json
```
## 许可证
MIT —— 参见 [LICENSE](LICENSE)。
Copyright (c) 2026 isecwire GmbH
标签：AES, .comment 编译器版本, CycloneDX, dpkg, ELF 分析, EU CRA 合规, License, NX, openwrt-release, opkg, os-release, OS 发行版识别, PIE, RELRO, RPATH, RUNPATH, SBOM, SHA-256, SONAME, SPDX, SPDX-License-Identifier, 供应链透明, 加密算法检测, 动态链接库, 包管理元数据, 可视化界面, 固件, 固件安全, 字符串特征扫描, 安全加固标志, 嵌入式包, 构建ID, 栈保护, 版本标识, 版权扫描, 硬件无关, 许可证检测, 设备制造商, 跌倒检测, 软件物料清单, 通知系统, 集成商