vincents-ai/transparenz-server-oss

# Transparenz Server OSS **开源欧盟 CRA/NIS2 合规报告服务器** Transparenz 合规服务器的 AGPL-3.0 许可版本。提供核心的 CRA Art. 10 功能：SBOM 管理、漏洞扫描、VEX 生命周期、CSAF 2.0 公告、SLA 跟踪以及协调漏洞披露。 此仓库也是商业版（`transparenz-server`）所使用的共享代码的**唯一事实来源**，商业版通过 Go 模块依赖导入模型、存储库、服务、中间件、接口和任务。 ## 功能 - **SBOM 管理** — 上传 CycloneDX/SPDX SBOM，跟踪漏洞状态 - **漏洞扫描** — 基于 VulnzMatcher 的扫描（无 Grype 依赖） - **VEX 生命周期** — 创建、批准、发布漏洞利用交换声明 - **CSAF 2.0** — 根据通用安全公告框架生成和分发安全公告 - **SLA 跟踪** — 自动执行期限强制：已利用 24 小时，严重 72 小时（CRA Art. 10） - **协调披露** — 具有 90 天响应窗口的上游通知工作流 - **审计跟踪** — 具有验证功能的合规事件跟踪 - **实时警报** — 基于 SSE 的漏洞和 SLA 警报 - **多租户隔离** — 行级安全 (RLS) 和每个组织一个 schema - **ENISA 只读** — 列出并下载 ENISA 提交 - **指标** — 带有 basic auth 的 Prometheus `/metrics` 端点 ## 商业版 商业版（`transparenz-server`）在此仓库之上进行了分层构建： - ENISA EVD API 提交管道 - Greenbone 漏洞扫描器集成 - SBOM webhook 摄入 (CI/CD) - 使用遥测和分析 - PDF 报告生成 (BSI TR-03116) - Ed25519 签名密钥管理 - 按组织的速率限制和计费层级 - NixOS 气隙设备部署 请参阅下面的[架构：OSS 与商业版对比](#oss-vs-commercial-architecture)。 ## 快速入门 ### 前置条件 - Go 1.25+ - PostgreSQL 14+ - Podman 或 Docker（用于集成测试） ### 设置 ``` # Clone git clone https://github.com/transparenz/transparenz-server-oss.git cd transparenz-server-oss # 配置环境 export DATABASE_URL="postgres://user:pass@localhost:5432/transparenz?sslmode=disable" export JWT_SECRET="change-me-to-at-least-32-characters" export PORT=8080 # 创建数据库和 schema psql -c "CREATE DATABASE transparenz;" psql -d transparenz -c "CREATE SCHEMA IF NOT EXISTS compliance;" # 运行 migrations go run ./cmd/migrate ./migrations # 启动服务器 go run ./cmd/server ``` ### 验证 ``` curl http://localhost:8080/health curl http://localhost:8080/readyz ``` ## 项目结构 ``` transparenz-server-oss/ ├── cmd/ │ ├── server/main.go # Application entrypoint (Cobra + Gin) │ └── migrate/main.go # Standalone migration runner ├── pkg/ # Public packages (importable by commercial edition) │ ├── models/ # GORM database models │ ├── repository/ # Data access layer (TenantBackend, scopes) │ ├── services/ # Business logic │ ├── interfaces/ # Service interfaces + mocks │ ├── middleware/ # JWT, RBAC, tenant, rate limiting │ └── jobs/ # Background job queue ├── internal/ │ ├── api/rest/ # REST API handlers (OSS routes only) │ └── config/ # Configuration (Viper, Zap logger) ├── migrations/ # SQL migrations (000001–000041) ├── bdd/ # BDD test suite (godog) │ ├── features/ # Gherkin feature files (13 features, 82 scenarios) │ ├── testcontext/ # Test infrastructure (container, DB, auth, app wiring) │ └── *_steps.go # Step definitions ├── tests/integration/ # Integration tests (42 tests) ├── Makefile # Build, test, lint commands ├── flake.nix # Nix flake for reproducible builds ├── go.mod # github.com/transparenz/transparenz-server-oss └── LICENSE # AGPL-3.0 ``` ### 为什么使用 `pkg/` 而不是 `internal/`？ Go 的 `internal/` 包限制阻止了其他模块导入内部包。由于商业版的 `transparenz-server` 会从此仓库导入共享代码，因此所有共享包都存放在 `pkg/` 中。只有 REST 处理程序和配置保留在 `internal/` 中 —— 这些是 OSS 特有的，不会被商业版导入。 ## 架构 ``` ┌─────────────────────────────────────────────────┐ │ Gin HTTP Router │ │ (JWT + Tenant Middleware) │ ├─────────┬───────────┬──────────┬───────────┬───────┤ │ Scan │ Compli- │ VEX │ Export │Alerts │ │ API │ ance API │ API │ API │ SSE │ ├─────────┴───────────┴──────────┴───────────┴───────┤ │ Service Layer (pkg/services) │ │ CSAF Generator · SLA Calculator · VEX Service │ │ VulnzMatcher · Disclosure Service · ScanWorker │ ├───────────────────────────────────────────────────┤ │ Repository Layer (pkg/repository) │ │ TenantBackend: RLS / Schema-per-Org │ ├───────────────────────────────────────────────────┤ │ PostgreSQL 14+ │ │ compliance schema · multi-tenant isolation │ └───────────────────────────────────────────────────┘ ``` ## OSS 与商业版架构对比 ``` ┌──────────────────────────────────────────────────────────────┐ │ transparenz-server (commercial) │ │ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Commercial-only REST handlers: │ │ │ │ greenbone.go · sbom_webhook.go · signing.go │ │ │ │ telemetry.go · pdf export · rate limiting │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ transparenz-server-oss (this repo) via go.mod replace │ │ │ │ │ │ │ │ pkg/models · pkg/repository · pkg/services │ │ │ │ pkg/interfaces · pkg/middleware · pkg/jobs │ │ │ │ │ │ │ │ Also includes: OSS REST handlers + config + migrations │ │ │ └─────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────┘ ``` 商业版的 `go.mod` 包含： ``` replace github.com/transparenz/transparenz-server-oss => ../transparenz-server-oss ``` 所有共享代码均在此仓库中维护。商业版仅包含： - 仅限商业版的 REST 处理程序（Greenbone、webhooks、签名、遥测、PDF） - 商业版 BDD 测试 - 包含完整路由配置的 cmd/server/main.go - 存储库和服务测试文件 ## API 端点 ### 公开（无需认证） | Method | Path | Description | |--------|------|-------------| | GET | `/health` | 存活探针 | | GET | `/readyz` | 就绪探针 | | GET | `/.well-known/csaf/:org/provider-metadata.json` | CSAF 提供商发现 | | GET | `/.well-known/csaf/:org/changes.csv` | CSAF 更改跟踪 | | GET | `/.well-known/csaf/:org/:id.json` | CSAF 公告文档 | ### 需认证（需要 JWT） | Method | Path | Description | |--------|------|-------------| | POST | `/api/sboms/upload` | 上传 SBOM (CycloneDX/SPDX) | | GET | `/api/sboms` | 列出 SBOM | | GET | `/api/sboms/:id` | 获取 SBOM | | GET | `/api/sboms/:id/download` | 下载 SBOM | | DELETE | `/api/sboms/:id` | 删除 SBOM | | POST | `/api/scan` | 触发漏洞扫描 | | GET | `/api/scans` | 列出扫描 | | GET | `/api/scans/:id/vulnerabilities` | 获取扫描漏洞 | | GET | `/api/vulnerabilities` | 列出漏洞 | | GET | `/api/vulnerabilities/:cve` | 通过 CVE 获取漏洞 | | GET | `/api/compliance/status` | 合规状态和 SLA 跟踪 | | GET | `/api/compliance/sla` | 列出 SLA 跟踪条目 | | POST | `/api/compliance/exploited` | 报告已利用的漏洞 | | POST | `/api/vex` | 创建 VEX 声明 | | GET | `/api/vex` | 列出 VEX 声明 | | PUT | `/api/vex/:id/approve` | 批准 VEX 声明 | | PUT | `/api/vex/:id/publish` | 发布 VEX 声明 | | POST | `/api/disclosures` | 创建披露 | | GET | `/api/disclosures` | 列出披露 | | GET | `/api/disclosures/:id` | 获取披露 | | PUT | `/api/disclosures/:id/status` | 更新披露状态 | | GET | `/api/csaf/provider-metadata.json` | CSAF 提供商元数据 | | GET | `/api/csaf/advisories` | 列出 CSAF 公告 | | GET | `/api/csaf/advisories/:id` | 获取 CSAF 公告 | | GET | `/api/csaf/changes.csv` | 下载 changes.csv | | GET | `/api/enisa/submissions` | 列出 ENISA 提交 | | GET | `/api/enisa/submissions/:id` | 获取 ENISA 提交 | | GET | `/api/enisa/submissions/:id/download` | 下载 ENISA 提交 | | POST | `/api/enisa/submit` | **返回 403**（仅限商业版） | | GET | `/api/audit/verify` | 验证审计链 | | GET | `/api/export/audit` | 导出审计跟踪 (CSV) | | GET | `/api/export/enriched-sbom/:id` | 导出富化 SBOM | | GET | `/api/alerts/stream` | SSE 警报流 | | GET | `/api/orgs/support-period` | 获取支持期 | | PUT | `/api/orgs/support-period` | 更新支持期 | | GET | `/api/feeds/status` | 订阅源同步状态 | | GET | `/metrics` | Prometheus 指标（basic auth） | ## 测试 ### BDD 测试（82 个场景） ``` # 运行 BDD 测试 (需要 Podman/Docker) DOCKER_HOST="unix://$XDG_RUNTIME_DIR/podman/podman.sock" \ go test -count=1 -timeout 15m -v ./bdd/... ``` 特性文件涵盖：审计/认证、扫描/漏洞、VEX 生命周期、合规/SLA、披露工作流、CSAF 提供商、CSAF well-known、导出、警报、边缘情况、协调披露、管理员组织管理。 ### 集成测试（42 个测试） ``` # 运行集成测试 (需要 Podman/Docker + auth-service) DOCKER_HOST="unix://$XDG_RUNTIME_DIR/podman/podman.sock" \ INTEGRATION_AUTH_ROOT=../auth-service \ go test -count=1 -timeout 40m -tags integration ./tests/integration/... ``` ### 单元测试 ``` make test ``` ## 环境变量 | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `DATABASE_URL` | 是 | — | PostgreSQL 连接字符串 | | `JWT_SECRET` | 是 | — | JWT 签名密钥（最少 32 个字符） | | `PORT` | 否 | `8080` | HTTP 监听端口 | | `ENCRYPTION_KEY` | 否 | — | 静态数据加密 | | `GIN_MODE` | 否 | `debug` | Gin 模式（生产环境使用 `release`） | | `METRICS_USER` | 否 | — | /metrics 的 Basic auth 用户名 | | `METRICS_PASSWORD` | 否 | — | /metrics 的 Basic auth 密码 | ## 欧盟 CRA 合规映射 | Article | Requirement | Implementation | |---------|-------------|----------------| | Art. 10(1) | 在 24 小时内报告已利用的漏洞 | SLA 跟踪 + 合规事件 | | Art. 10(2) | 在 72 小时内解决严重漏洞 | SLA 计算器 + 期限强制执行 | | Art. 10(4) | 通知 ENISA/CSIRT | ENISA 提交（商业版），只读列表（OSS） | | Art. 11 | 记录漏洞处理过程 | 合规事件审计跟踪 | | Art. 13 | 发布支持期 | 组织支持期端点 | | Art. 14 | 协调漏洞披露 | 协调披露工作流 | | Art. 20 | 向当局提供 SBOM | SBOM 上传/下载 + 富化导出 | | Annex I | CSAF 漏洞公告 | CSAF 2.0 提供商 + well-known 端点 | ## 许可证 AGPL-3.0。请参阅 [LICENSE](LICENSE)。 商业许可证适用于不希望遵守 AGPL-3.0 要求的用户。请联系维护者了解详情。

标签：CISA项目, CRA, CSAF 2.0, CycloneDX, Docker, ENISA, EVTX分析, Go语言, NIS2, Podman, PostgreSQL, Prometheus监控, SBOM管理, SLA跟踪, SPDX, VEX生命周期, 人工智能安全, 协调漏洞披露, 合规性, 安全公告, 安全防御评估, 实时警报, 审计跟踪, 开源, 无线安全, 日志审计, 欧盟网络弹性法案, 测试用例, 程序破解, 网络安全, 请求拦截, 隐私保护