ShinigamiKiko/wolfee-sca
GitHub: ShinigamiKiko/wolfee-sca
一款自托管的软件成分分析平台，支持导入 SBOM 进行漏洞分诊并通过质量门在 CI 中阻断高风险构建。
Stars: 0 | Forks: 0
# Wolfee SCA 平台
包含三个服务并支持 PostgreSQL 持久化的 Docker Compose 技术栈。
| 服务 | 端口 | 描述 |
|----------------|------|--------------------------------------------------|
| `postgres` | 5432 | PostgreSQL 16 — 持久化存储 |
| `backend` | 4000 | Go SCA 扫描器 + REST API + 后台 worker |
| `frontend` | 80 | React + nginx |
## 快速开始
```
cp .env.example .env
# 编辑 .env — 至少添加 GITHUB_TOKEN, NVD_API_KEY
docker compose up --build
```
打开 http://localhost
## 构建速度
首次执行 `docker compose up --build` 会创建 `wolfee-vuln-data:local` 镜像并
下载离线的 OSV、NVD、PoC、恶意软件和 Grype 数据。这是一次耗时的构建。
后续的应用重构会复用该镜像，仅编译 Go 服务器和 React 应用。
在需要时可显式刷新数据：
```
docker compose build backend-data
docker compose build backend frontend
```
## 身份验证
首次启动时会创建一个默认的 **admin / admin** 账号（首次登录时强制修改
密码）。也可以设置 `WOLFEE_ADMIN_PASSWORD` 来指定初始密码。
- **UI 会话** — 通过 `POST /api/v1/auth/login` 获取 JWT，作为
`Authorization: Bearer
` 发送。TTL 由 `WOLFEE_JWT_TTL` 控制（默认为 8h）。
- **CI / 自动化** — 在 *Settings → API Keys* 中创建的团队级 API 密钥 (`wsca_...`)，
作为 `X-Api-Key` 发送。密钥会继承其所属团队的权限；由其创建的项目会自动附加到该团队。
- **权限**（Dependency-Track 风格）：`VIEW_PORTFOLIO`、
`PORTFOLIO_MANAGEMENT`、`BOM_UPLOAD`、`VIEW_VULNERABILITY`、
`VULNERABILITY_ANALYSIS`、`POLICY_MANAGEMENT`、`ACCESS_MANAGEMENT`、
`SYSTEM_CONFIGURATION` — 授予给用户和团队；生效的权限集为两者的并集。
- **Portfolio ACL** — 团队只能看到授予给它们的项目
（*Settings → Teams → Project access*）。拥有 `ACCESS_MANAGEMENT` 权限的主体可以
绕过 ACL。
- **LDAP** — 可选的第二身份提供者（search+bind 模式），通过
`WOLFEE_LDAP_*` 环境变量配置；用户在首次登录时自动开通，但不具有任何
权限。
- **已弃用**：全局 `API_KEY` 环境变量仍可作为超级用户密钥使用，
以保持现有 CI 继续运行 — 请尽快迁移至团队 API 密钥并移除该变量。
## API
### 项目
```
PUT /api/v1/project create project
GET /api/v1/project list all projects
GET /api/v1/project/{uuid} get one project
DELETE /api/v1/project/{uuid} delete project
GET /api/v1/project/{uuid}/branches list branches
POST /api/v1/project/{uuid}/branches create branch: {"name":"feature/api"}
```
每个项目都会获得一个默认的 `main` 分支。分支的创建仅限 API；
项目页面提供了分支切换器，但不提供创建操作。
### BOM 上传 (异步)
```
POST /api/v1/bom multipart: project=, bom=
→ 200 { token, branchUuid }
```
处理过程在后台 worker 中进行。轮询 `/api/v1/bom/token/{token}` 以获取状态。
传入 `branch=` 可以上传到指定分支。`upload=true` 是
`autoCreate=true` 的 CI 友好别名：如果具名项目和/或分支不
存在，上传请求会在将 SBOM 加入队列之前创建它。
```
curl -X POST http://localhost:4000/api/v1/bom \
-H "X-Api-Key: $WOLFEE_API_KEY" \
-F project=my-service \
-F branch=feature/payment-refactor \
-F upload=true \
-F bom=@bom.json
```
JSON 客户端可以发送包含 base64 编码 BOM 的等效 payload：
```
{
"projectName": "my-service",
"branch": "feature/payment-refactor",
"upload": true,
"bom": ""
}
```
支持分支感知的读取和重新扫描接受 `?branch=` 参数。若无此参数，
API 将使用项目的默认分支，从而保持与现有集成的兼容性。
`WORKER_CONCURRENCY` 控制单个后端并行处理的 BOM 扫描数量。
默认值为 `3`；后端强制最高上限为 `4`。
### 发现与组件 (在 BOM 任务完成后填充)
```
GET /api/v1/finding/project/{uuid}?branch= findings for the branch's active BOM
GET /api/v1/vulnerability/project/{uuid}?branch= unique vulnerabilities for the branch
GET /api/v1/component/project/{uuid}?branch= components for the branch
GET /api/v1/metrics/project/{uuid}?branch= severity and audit counters for the branch
GET /api/v1/quality-gate/project/{uuid}?branch= pass/block result for the branch
```
质量门响应仅根据所请求分支的当前活跃 BOM 进行评估。
它包含了阻断性的发现项，以便 CI 可以在不获取整个项目的情况下解释失败原因：
```
{
"projectUuid": "...",
"branch": { "uuid": "...", "name": "feature/payment-refactor" },
"bomUuid": "...",
"gate": "block",
"pipeline": "failed",
"findingsTotal": 12,
"blockingFindings": 2,
"critical": 1,
"high": 4,
"findings": [
{
"branchUuid": "...", "branchName": "feature/payment-refactor",
"vulnerabilityId": "CVE-...", "severity": "CRITICAL", "cvss": 9.8,
"componentName": "...", "componentVersion": "...",
"gate": "block", "policyAction": "block", "policyWhy": "critical threshold exceeded"
}
]
}
```
`findings` 包含了该分支当前活跃 BOM 中的所有发现项，按严重程度（从 `CRITICAL` 到 `LOW`）以及降序的 CVSS 分数进行排序。
CI 门禁示例 (需要 `jq`)：
```
gate_json=$(curl -fsS --get \
-H "X-Api-Key: $WOLFEE_API_KEY" \
--data-urlencode "branch=$CI_COMMIT_REF_NAME" \
"http://localhost:4000/api/v1/quality-gate/project/$WOLFEE_PROJECT_UUID")
echo "$gate_json" | jq .
test "$(echo "$gate_json" | jq -r .gate)" = "pass"
```
### 导出
```
GET /api/v1/finding/project/{uuid}/export?format=sarif SARIF 2.1.0
GET /api/v1/finding/project/{uuid}/export?format=cyclonedx-vex CycloneDX VEX
```
### 规则 (全局，持久化存储于数据库)
```
GET /api/rules current rules config
PUT /api/rules replace rules config
```
### 遗留接口 (用于前端兼容)
```
POST /api/scan single-package scan with rules evaluation
```
## 架构
```
cmd/server/main.go entry point, DI wiring
internal/
config/ env-based config
domain/ entities: Project, BOM, Component, Finding, Job, Rules
repository/ interfaces + memory.go + postgres.go + migrate.go
service/ use cases (business logic)
worker/ background job processor
http/ thin HTTP handlers
modules/ vulnerability data sources (OSV, NVD, EPSS, KEV…)
scanner/ scan pipeline
migrations/ SQL migration files (auto-applied at startup)
```
## 存储模式
- **配置 DATABASE_URL 时**：PostgreSQL — 数据在重启后依然持久化
- **未配置 DATABASE_URL 时**：内存模式 — 零配置，但数据在重启后丢失
## 环境变量
有关所有选项，请参阅 `.env.example`。
## 生产环境部署
请参阅 [DEPLOY.md](DEPLOY.md) — 了解 TLS/ingress、secrets、速率限制、BOM
保留策略、备份/恢复、升级以及生产环境检查清单。
# 构建速度
首次执行 `docker compose up --build` 会创建 `wolfee-vuln-data:local` 镜像。该过程会
下载离线漏洞语料库，可能需要很长时间。后续的应用重构会复用该镜像，并仅编译 Go 服务器 /
React 应用。可使用以下命令显式刷新语料库：
```
docker compose build backend-data
docker compose build backend frontend
```
标签：Checkov, DevSecOps, Docker Compose, EVTX分析, Go, GPT, React, Ruby工具, Syscalls, 上游代理, 日志审计, 漏洞管理, 请求拦截, 软件成分分析(SCA)