secubox-openwrt/docs-zh/sbom-pipeline.md

SecuBox SBOM 流水线文档

🌐 语言： English | Français | 中文

概述

SecuBox SBOM（软件物料清单）流水线生成符合 CycloneDX 1.6 和 SPDX 2.3 标准的 SBOM，以满足欧盟网络弹性法案（CRA）附件一的合规要求。

架构

┌─────────────────────────────────────────────────────────────────────────────┐
│                         SecuBox SBOM 流水线                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│   │   数据源 A  │    │   数据源 B  │    │   数据源 C  │    │   数据源 D  │  │
│   │  OpenWrt    │    │   SecuBox   │    │   Rootfs    │    │   固件      │  │
│   │  原生       │    │   Feed      │    │   扫描      │    │   镜像      │  │
│   │             │    │             │    │             │    │             │  │
│   │ 软件包      │    │ Makefiles   │    │ Syft 扫描   │    │ Syft 扫描   │  │
│   │ .manifest   │    │ PKG_* 变量  │    │ dir:rootfs  │    │ file:*.bin  │  │
│   └──────┬──────┘    └──────┬──────┘    └──────┬──────┘    └──────┬──────┘  │
│          │                  │                  │                  │         │
│          └──────────────────┴──────────────────┴──────────────────┘         │
│                                    │                                         │
│                                    ▼                                         │
│                          ┌─────────────────┐                                 │
│                          │   合并与去重    │                                 │
│                          │   (jq fusion)   │                                 │
│                          └────────┬────────┘                                 │
│                                   │                                          │
│                                   ▼                                          │
│                          ┌─────────────────┐                                 │
│                          │      验证       │                                 │
│                          │ cyclonedx-cli   │                                 │
│                          └────────┬────────┘                                 │
│                                   │                                          │
│                    ┌──────────────┼──────────────┐                           │
│                    ▼              ▼              ▼                           │
│             ┌───────────┐  ┌───────────┐  ┌───────────┐                      │
│             │ CVE 扫描  │  │ CRA 报告  │  │  校验和   │                      │
│             │  (grype)  │  │   摘要    │  │ sha256sum │                      │
│             └───────────┘  └───────────┘  └───────────┘                      │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

输出文件：
├── secubox-VERSION.cdx.json          # CycloneDX 1.6（主要格式）
├── secubox-VERSION.spdx.json         # SPDX 2.3（备选格式）
├── secubox-VERSION-cve-report.json   # Grype CVE 扫描结果
├── secubox-VERSION-cve-table.txt     # 人类可读的 CVE 表格
├── secubox-VERSION-cra-summary.txt   # CRA 合规摘要
├── sbom-warnings.txt                 # 缺失元数据警告
└── checksums.sha256                  # 文件完整性校验和

前提条件

最低版本要求

工具	最低版本	用途
OpenWrt	22.03	原生 SBOM 支持
Perl	5.26+	package-metadata.pl
jq	1.6+	JSON 处理
Syft	0.100+	文件系统扫描
Grype	0.70+	CVE 扫描
cyclonedx-cli	0.25+	SBOM 验证

环境配置

# 检查前提条件
./scripts/check-sbom-prereqs.sh

# 安装 SBOM 工具（如果未安装）
# Syft
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b ~/.local/bin

# Grype
curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b ~/.local/bin

# cyclonedx-cli
curl -sSfL -o ~/.local/bin/cyclonedx-cli \
  https://github.com/CycloneDX/cyclonedx-cli/releases/latest/download/cyclonedx-linux-x64
chmod +x ~/.local/bin/cyclonedx-cli

# 添加到 PATH
export PATH="$HOME/.local/bin:$PATH"

OpenWrt Kconfig 配置

在 .config 中启用原生 SBOM 生成：

CONFIG_JSON_CYCLONEDX_SBOM=y
CONFIG_COLLECT_KERNEL_DEBUG=n

使用方法

日常开发

# 完整 SBOM 生成（全部 4 个数据源）
./scripts/sbom-generate.sh

# 从现有构建产物快速生成 SBOM（无需重新构建）
./scripts/sbom-generate.sh --version 0.20

# 离线模式（无网络，使用缓存的数据库）
./scripts/sbom-generate.sh --offline

# 跳过 CVE 扫描（更快）
./scripts/sbom-generate.sh --no-cve

使用 Makefile 目标

# 完整构建 + SBOM
make sbom

# 仅生成 SBOM（无需重新构建）
make sbom-quick

# 验证现有 SBOM
make sbom-validate

# 仅进行 CVE 扫描
make sbom-scan

# 清理 SBOM 输出
make sbom-clean

# 显示帮助
make sbom-help

审计 Feed 软件包

# 检查所有 SecuBox feed 软件包是否缺失元数据
./scripts/sbom-audit-feed.sh

# 输出：feeds/secubox/MANIFEST.md

添加新软件包

向 SecuBox feed 添加新软件包时，请确保 SBOM 兼容性：

检查清单

• 已定义 PKG_NAME
• 已定义 PKG_VERSION
• 已定义 PKG_LICENSE（SPDX 标识符）
• 已定义 PKG_HASH（sha256）
• 已定义 PKG_SOURCE_URL（可选但推荐）

Makefile 示例

include $(TOPDIR)/rules.mk

PKG_NAME:=my-package
PKG_VERSION:=1.0.0
PKG_RELEASE:=1

PKG_SOURCE_URL:=https://github.com/example/my-package/archive
PKG_SOURCE:=$(PKG_NAME)-$(PKG_VERSION).tar.gz
PKG_HASH:=a1b2c3d4e5f6...  # 源码压缩包的 sha256sum

PKG_LICENSE:=MIT
PKG_LICENSE_FILES:=LICENSE

PKG_MAINTAINER:=您的姓名 <email@example.com>

计算 PKG_HASH

# 下载并计算源码哈希
wget https://example.com/package-1.0.0.tar.gz
sha256sum package-1.0.0.tar.gz

# 或使用 OpenWrt 下载助手
make package/my-package/download V=s
sha256sum dl/my-package-1.0.0.tar.gz

CRA 附件一映射

CRA 要求	SBOM 实现
第13(5)条 - 组件识别	components[].purl（软件包 URL）
第13(5)条 - 供应商识别	metadata.component.supplier
第13(5)条 - 版本信息	components[].version
第13(5)条 - 依赖关系	dependencies[] 数组
第13(5)条 - 许可证信息	components[].licenses[]
第13(6)条 - 机器可读格式	CycloneDX 1.6 JSON + SPDX 2.3
第13(6)条 - 漏洞披露	SECURITY.md + VEX 文档
第13(7)条 - 唯一标识	PURL + serialNumber UUID
附件一(2) - 完整性验证	hashes[]（含 SHA-256）

ANSSI CSPN 提交

申请 CSPN 认证时，请在申请材料中包含以下内容：

必需文档

1. SBOM 文件

   • secubox-VERSION.cdx.json（主要格式）
   • secubox-VERSION.spdx.json（备选格式）

2. 来源证明

   • checksums.sha256（完整性验证）
   • 元数据中的 Git 提交哈希

3. 漏洞分析

   • secubox-VERSION-cve-report.json
   • secubox-VERSION-cra-summary.txt

4. 流程文档

   • 本文档（docs/sbom-pipeline.md）
   • SECURITY.md（漏洞披露政策）

提交检查清单

• 所有组件都有 PKG_HASH 和 PKG_LICENSE
• SBOM 通过 cyclonedx-cli 验证
• 无未处理的严重级别 CVE
• VEX 文档说明了已接受的风险
• 已验证 SOURCE_DATE_EPOCH 可重现性

故障排除

常见错误

"OpenWrt version < 22.03"

原生 CycloneDX SBOM 支持需要 OpenWrt 22.03 或更高版本。

解决方案： 升级您的 OpenWrt 分支，或使用不依赖原生支持的 sbom-generate.sh（将回退到 Makefile 解析）。

"package-metadata.pl not found"

您的 OpenWrt 检出中缺少 SBOM 生成脚本。

解决方案：

git checkout origin/master -- scripts/package-metadata.pl

"syft: command not found"

Syft 未安装或不在 PATH 中。

解决方案：

curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"

"SBOM validation failed"

生成的 SBOM 存在架构错误。

解决方案：

1. 检查 sbom-warnings.txt 了解缺失的元数据
2. 修复缺少 PKG_HASH 或 PKG_LICENSE 的 Makefile
3. 重新生成 SBOM

"Grype database update failed"

网络连接问题或速率限制。

解决方案：

• 使用 --offline 模式配合缓存的数据库
• 或手动更新：grype db update

调试模式

# 详细输出
DEBUG=1 ./scripts/sbom-generate.sh

# 保留中间文件
KEEP_TEMP=1 ./scripts/sbom-generate.sh

版本历史

版本	日期	变更
1.0	2026-03-04	初始流水线实现

---

由 CyberMind Produits SASU 维护 联系方式：secubox@cybermind.fr