CyberMind-FR
ccfb58124c
Add complete French (fr) and Chinese (zh) translations for all documentation: - Root files: README, CHANGELOG, SECURITY, BETA-RELEASE - docs/: All 16 core documentation files - DOCS/: All 19 deep-dive documents including embedded/ and archive/ - package/secubox/: All 123+ package READMEs - Misc: secubox-tools/, scripts/, EXAMPLES/, config-backups/, streamlit-apps/ Total: 346 translation files created Each file includes language switcher links for easy navigation between English, French, and Chinese versions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
304 lines
11 KiB
Markdown
304 lines
11 KiB
Markdown
# SecuBox SBOM 流水线文档
|
||
|
||
🌐 **语言：** [English](../docs/sbom-pipeline.md) | [Français](../docs-fr/sbom-pipeline.md) | 中文
|
||
|
||
## 概述
|
||
|
||
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 验证 |
|
||
|
||
### 环境配置
|
||
|
||
```bash
|
||
# 检查前提条件
|
||
./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
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 日常开发
|
||
|
||
```bash
|
||
# 完整 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 目标
|
||
|
||
```bash
|
||
# 完整构建 + SBOM
|
||
make sbom
|
||
|
||
# 仅生成 SBOM（无需重新构建）
|
||
make sbom-quick
|
||
|
||
# 验证现有 SBOM
|
||
make sbom-validate
|
||
|
||
# 仅进行 CVE 扫描
|
||
make sbom-scan
|
||
|
||
# 清理 SBOM 输出
|
||
make sbom-clean
|
||
|
||
# 显示帮助
|
||
make sbom-help
|
||
```
|
||
|
||
### 审计 Feed 软件包
|
||
|
||
```bash
|
||
# 检查所有 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 示例
|
||
|
||
```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
|
||
|
||
```bash
|
||
# 下载并计算源码哈希
|
||
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 生成脚本。
|
||
|
||
**解决方案：**
|
||
```bash
|
||
git checkout origin/master -- scripts/package-metadata.pl
|
||
```
|
||
|
||
#### "syft: command not found"
|
||
|
||
Syft 未安装或不在 PATH 中。
|
||
|
||
**解决方案：**
|
||
```bash
|
||
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`
|
||
|
||
### 调试模式
|
||
|
||
```bash
|
||
# 详细输出
|
||
DEBUG=1 ./scripts/sbom-generate.sh
|
||
|
||
# 保留中间文件
|
||
KEEP_TEMP=1 ./scripts/sbom-generate.sh
|
||
```
|
||
|
||
## 版本历史
|
||
|
||
| 版本 | 日期 | 变更 |
|
||
|------|------|------|
|
||
| 1.0 | 2026-03-04 | 初始流水线实现 |
|
||
|
||
---
|
||
|
||
_由 CyberMind Produits SASU 维护_
|
||
_联系方式：secubox@cybermind.fr_
|