vincents-ai/transparenz
GitHub: vincents-ai/transparenz
一款用于生成、增强、校验和提交符合 BSI TR-03183-2 标准 SBOM 的命令行工具，同时集成漏洞扫描与数据库持久化功能。
Stars: 1 | Forks: 0
# transparenz
一个用于生成、补充、验证和提交符合 BSI TR-03183-2 标准的软件物料清单 (SBOM) 的 CLI 工具。
## 功能
- 通过原生 Syft 库生成 SBOM (CycloneDX 1.6 JSON, SPDX 2.3 JSON)
- BSI TR-03183-2 信息补充：SHA-512 制品哈希、供应商检测、许可证检测、组件分类 (executable/archive/structured)、依赖完整性断言
- 带加权评分的 SBOM 合规性验证 (`bsi-check`)
- 使用 Bearer token 认证将 SBOM 提交到远程服务器 endpoint
- 基于 PostgreSQL 的 SBOM 和漏洞扫描结果持久化存储
- 通过原生 Grype 库进行独立漏洞扫描
## 要求
- Go 1.25+
- PostgreSQL（用于 `--save` 标志以及 `db` / `list` / `show` / `search` / `delete` 命令）
- Grype 漏洞数据库（在首次运行 `scan` 时自动下载）
## 安装
```
# 通过 go install 安装
go install github.com/vincents-ai/transparenz@latest
# 或者从源码构建
git clone https://github.com/vincents-ai/transparenz.git
cd transparenz
go build -o transparenz .
```
## 快速开始
### 1. 生成符合 BSI 标准的 SBOM 并保存到文件
```
transparenz generate . \
--format cyclonedx \
--bsi-compliant \
--binary ./build/myapp \
--manufacturer "Acme Corp" \
--manufacturer-url "https://acme.example.com" \
--output sbom.json
```
### 2. 生成并直接提交到服务器
```
export TRANSPARENZ_SERVER_URL=https://sbom.example.com/api/sbom
export TRANSPARENZ_TOKEN=my-bearer-token
transparenz generate . \
--format cyclonedx \
--bsi-compliant \
--submit
```
### 3. 生成、持久化到数据库并进行漏洞扫描
```
# 首先运行数据库迁移（一次）
transparenz db migrate
# 生成并持久化
transparenz generate . --bsi-compliant --save
# 列出已存储的 SBOM 以获取 ID
transparenz list
# 扫描 SBOM 并将结果保存到数据库
transparenz scan sbom.json --save
```
## 命令参考
### 全局标志
| 标志 | 简写 | 默认值 | 描述 |
|------|-------|---------|-------------|
| `--config` | `-c` | `$HOME/.transparenz.yaml` | 配置文件路径 |
| `--verbose` | `-v` | `false` | 启用详细输出 |
### `generate [source]`
从源路径或容器镜像生成 SBOM。
```
transparenz generate [source] [flags]
```
| 标志 | 简写 | 默认值 | 描述 |
|------|-------|---------|-------------|
| `--format` | `-f` | `spdx` | 输出格式：`spdx` 或 `cyclonedx` |
| `--output` | `-o` | stdout | 输出文件路径 |
| `--save` | | `false` | 将 SBOM 持久化到 PostgreSQL 数据库 |
| `--bsi-compliant` | `-b` | `false` | 应用 BSI TR-03183-2 信息补充 (哈希、许可证、供应商、属性) |
| `--manufacturer` | | | SBOM 生产者组织名称 (也可使用：`TRANSPARENZ_MANUFACTURER`) |
| `--manufacturer-url` | | | SBOM 生产者组织 URL (也可使用：`TRANSPARENZ_MANUFACTURER_URL`) |
| `--binary` | | | 用于注入 SHA-512 哈希的已编译二进制文件路径 (需要 `--bsi-compliant`) |
| `--scope` | | `source` | SBOM 范围：`source` (依赖清单) 或 `binary` (已编译二进制文件/容器镜像) |
| `--no-fetch` | | `false` | 跳过预扫描依赖获取 (禁用 `go mod download` 等) |
| `--submit` | | `false` | 生成后将生成的 SBOM 提交到远程服务器 |
| `--server-url` | | | 远程服务器 endpoint URL (也可使用：`TRANSPARENZ_SERVER_URL`) |
| `--token` | | | Bearer 认证 token (也可使用：`TRANSPARENZ_TOKEN`) |
| `--insecure` | | `false` | 跳过 TLS 验证 (也可使用：`TRANSPARENZ_INSECURE=true`) |
| `--timeout` | | `30` | 提交的 HTTP 超时时间 (秒) |
**示例：**
```
transparenz generate .
transparenz generate . --format cyclonedx --output sbom.json
transparenz generate docker:nginx:latest --format spdx
transparenz generate . --bsi-compliant --binary ./build/app --save
```
### `enrich [sbom-path]`
使用 BSI TR-03183-2 元数据补充现有 SBOM。
```
transparenz enrich [sbom-path] [flags]
```
为所有组件添加：BSI 属性 (`executable`、`archive`、`structured`)、依赖完整性断言，并将 CycloneDX 的 `specVersion` 升级到 1.6。
| 标志 | 简写 | 默认值 | 描述 |
|------|-------|---------|-------------|
| `--output` | `-o` | stdout | 输出文件路径 |
| `--artifacts` | | | 用于计算 SHA-512 哈希的已编译二进制文件目录 |
| `--binary` | | | 用于注入 SHA-512 哈希的单个已编译二进制文件路径 |
| `--manufacturer` | | | SBOM 生产者组织名称 (也可使用：`TRANSPARENZ_MANUFACTURER`) |
| `--manufacturer-url` | | | SBOM 生产者组织 URL (也可使用：`TRANSPARENZ_MANUFACTURER_URL`) |
| `--submit` | | `false` | 补充后将增强的 SBOM 提交到远程服务器 |
| `--server-url` | | | 远程服务器 endpoint URL (也可使用：`TRANSPARENZ_SERVER_URL`) |
| `--token` | | | Bearer 认证 token (也可使用：`TRANSPARENZ_TOKEN`) |
| `--insecure` | | `false` | 跳过 TLS 验证 (也可使用：`TRANSPARENZ_INSECURE=true`) |
| `--timeout` | | `30` | 提交的 HTTP 超时时间 (秒) |
**示例：**
```
transparenz enrich sbom.json -o sbom-enriched.json
transparenz enrich sbom.json --artifacts ./build/ -o sbom-final.json
transparenz enrich sbom.json --binary ./build/app --manufacturer "Acme Corp" -o sbom-final.json
```
### `bsi-check [sbom-path]`
根据 BSI TR-03183-2 要求验证 SBOM 并输出合规性报告。
```
transparenz bsi-check [sbom-path] [flags]
```
| 标志 | 简写 | 默认值 | 描述 |
|------|-------|---------|-------------|
| `--output` | `-o` | stdout | JSON 合规性报告的输出文件路径 |
**示例：**
```
transparenz bsi-check sbom.json
transparenz bsi-check sbom.json --output report.json
```
### `validate [sbom-path]`
根据 BSI TR-03183-2 要求验证 SBOM。这是 `bsi-check` 的别名，侧重于通过/失败的验证结果。
```
transparenz validate [sbom-path]
```
检查项：
- 哈希算法 (根据 BSI TR-03183-2 强制要求 SHA-512)
- 许可证覆盖率 (所有组件的 SPDX 标识符)
- 供应商覆盖率 (所有组件的供应商/作者信息)
- 组件属性 (`executable`、`archive`、`structured`)
- 依赖完整性断言
- 格式版本 (CycloneDX 1.6+ 或 SPDX 2.3+)
### `submit`
使用 Bearer token 认证将 SBOM 提交到远程服务器。从 `--file` 或 stdin 读取。除非覆盖，否则 Content-Type 会根据 SBOM 内容自动检测。
```
transparenz submit [flags]
```
| 标志 | 简写 | 默认值 | 描述 |
|------|-------|---------|-------------|
| `--file` | `-f` | stdin | 要提交的 SBOM 文件路径 |
| `--url` | | | 服务器 endpoint URL (也可使用：`TRANSPARENZ_SERVER_URL`) |
| `--token` | | | Bearer 认证 token (也可使用：`TRANSPARENZ_TOKEN`) |
| `--timeout` | | `30` | HTTP 超时时间 (秒) |
| `--insecure` | | `false` | 跳过 TLS 证书验证 |
| `--content-type` | | 自动检测 | 覆盖 `Content-Type` header |
**示例：**
```
transparenz submit --file sbom.json --url https://sbom.example.com/api/sbom --token my-token
cat sbom.json | transparenz submit --url https://sbom.example.com/api/sbom --token my-token
```
### `scan [sbom-path]`
使用原生 Grype 库扫描 SBOM 中的已知漏洞。接受 SPDX JSON 和 CycloneDX JSON 输入。
```
transparenz scan [sbom-path] [flags]
```
| 标志 | 简写 | 默认值 | 描述 |
|------|-------|---------|-------------|
| `--output-format` | `-f` | `json` | 输出格式：`json` 或 `table` |
| `--output` | `-o` | stdout | 输出文件路径 |
| `--severity` | | | 按最低严重程度过滤结果 (`Critical`, `High`, `Medium`, `Low`) |
| `--save` | | `false` | 将扫描结果持久化到数据库 (需要先保存 SBOM) |
**示例：**
```
transparenz scan sbom.json
transparenz scan sbom.json --output-format table
transparenz scan sbom.json --severity Critical --save
transparenz scan sbom.json -f json --output results.json
```
### `list`
列出存储在数据库中的 SBOM。
```
transparenz list [flags]
```
| 标志 | 简写 | 默认值 | 描述 |
|------|-------|---------|-------------|
| `--limit` | `-l` | `50` | 要显示的 SBOM 最大数量 |
| `--offset` | `-s` | `0` | 分页偏移量 |
| `--format` | | `table` | 输出格式：`table` 或 `json` |
### `show [sbom-id]`
显示已存储 SBOM 的详细信息，包括其软件包列表。
```
transparenz show [sbom-id]
```
### `search [package-name]`
按软件包名称搜索已存储的 SBOM。
```
transparenz search [package-name]
```
### `delete [sbom-id]`
从数据库中删除已存储的 SBOM 及所有相关数据。
```
transparenz delete [sbom-id] [flags]
```
| 标志 | 简写 | 默认值 | 描述 |
|------|-------|---------|-------------|
| `--force` | `-f` | `false` | 跳过确认提示 |
### `db migrate`
运行 GORM 自动迁移以创建或更新数据库 schema。
```
transparenz db migrate
```
### `db export `
从数据库导出原始 SBOM JSON。接受完整的 UUID 或 8 个字符的前缀。
```
transparenz db export [flags]
```
| 标志 | 简写 | 默认值 | 描述 |
|------|-------|---------|-------------|
| `--output` | `-o` | stdout | 输出文件路径 |
**示例：**
```
transparenz db export a1b2c3d4
transparenz db export a1b2c3d4-e5f6-7890-abcd-ef1234567890 --output exported.json
```
## 环境变量
| 变量 | 使用者 | 描述 |
|----------|---------|-------------|
| `DATABASE_URL` | 所有 db 命令 | PostgreSQL 连接字符串 (默认：`host=localhost user=shift dbname=transparenz port=5432 sslmode=disable`) |
| `TRANSPARENZ_SERVER_URL` | `generate`, `enrich`, `submit` | 远程服务器 endpoint URL |
| `TRANSPARENZ_TOKEN` | `generate`, `enrich`, `submit` | Bearer 认证 token |
| `TRANSPARENZ_MANUFACTURER` | `generate`, `enrich` | SBOM 生产者组织名称 |
| `TRANSPARENZ_MANUFACTURER_URL` | `generate`, `enrich` | SBOM 生产者组织 URL |
| `TRANSPARENZ_INSECURE` | `generate`, `enrich` | 设为 `true` 以跳过 TLS 证书验证 |
## BSI TR-03183-2 合规性
`transparenz` 旨在满足《欧盟网络弹性法案》要求的 BSI TR-03183-2 软件物料清单技术指南。
**该工具的功能：**
- **格式**：输出 CycloneDX 1.6 JSON (或 SPDX 2.3 JSON)。`bsi-check` 验证器最低要求 CycloneDX 1.6+ 或 SPDX 2.3+。
- **SHA-512 哈希** (第 4.3 节)：通过 `--binary` (单个文件) 或 `--artifacts` (目录扫描) 从已编译的二进制文件计算得出。SHA-512 是强制性的；仅使用 SHA-256 是不合规的。
- **供应商和许可证补充**：将基于命名空间的供应商检测和 SPDX 许可证标准化应用于所有组件。
- **组件分类** (第 4.1 节)：每个组件都会获得 `executable`、`archive` 和 `structured` 属性。
- **依赖完整性** (第 4.2 节)：将 `completeness: complete` 断言注入到 SBOM 元数据中。
- **制造商身份**：`metadata.manufacturer` 字段由 `--manufacturer` / `TRANSPARENZ_MANUFACTURER` 填充。
**合规性评分 (`bsi-check`)：**
验证器根据六个类别生成加权总分：
| 类别 | 权重 | 达标阈值 |
|----------|--------|------------------------|
| SHA-512 哈希覆盖率 | 30% | ≥ 80% 的组件 |
| 许可证覆盖率 | 25% | ≥ 80% 的组件 |
| 供应商覆盖率 | 15% | ≥ 80% 的组件 |
| 组件属性 | 15% | ≥ 80% 的组件 |
| 依赖完整性 | 10% | 存在 |
| 格式版本 | 5% | CycloneDX 1.6+ 或 SPDX 2.3+ |
当所有六个类别都分别达到其阈值时，该 SBOM 即被标记为**合规**。
## 数据库设置
`transparenz` 通过 GORM 使用 PostgreSQL。 `DATABASE_URL` 环境变量或使用默认连接字符串。
```
# 示例：创建数据库
createdb transparenz
# 运行迁移（创建表）
transparenz db migrate
```
`generate` 和 `scan` 上的 `--save` 标志需要运行已应用迁移的 PostgreSQL 实例。
## 许可证
本软件采用双重许可：
- **社区版**：GNU Affero General Public License v3.0 或更高版本 (AGPL-3.0-or-later)。免费用于开源使用、研究、公共部门和非营利组织。修改版本的网络使用需要根据 AGPL 披露源代码。
- **商业许可证**：用于闭源商业应用、专有 SaaS 或嵌入到非 AGPL 兼容产品中。请联系 `shift@someone.section.me`。
请参阅 [LICENSE.md](LICENSE.md) 获取完整的许可文本。
标签：EVTX分析, Go, LLM防护, Ruby工具, SBOM, 合规检测, 日志审计, 测试用例, 硬件无关