HTTP API 参考¶

CVE Intelligence Panel 在 Node/Express 服务器上提供无状态 JSON REST API。开发环境中 UI 通过 Vite 代理（/api → localhost:3001）访问相同端点；生产环境使用同源路径。集成方可在不加载 React 客户端的情况下，从脚本、CI 门禁或内部仪表盘调用 API。

本章描述所有公开路由、请求校验、响应结构、错误码与运行限制。若无需运行服务器即可交互试用，请使用 API Explorer 标签页（浏览器模拟）。机器可读契约请请求 GET /api/openapi.json。

API 设计原则¶

API 遵循常见产品约定：JSON 请求体、UTF-8、无会话 Cookie（适合反向代理与 API 网关），并在 meta.mode 中明确区分扫描模式（full 与 watch）。每次扫描相互独立；除非客户端自行保存响应，服务器不会持久化你的技术栈或发现结果。

支持两种 URL 前缀：

前缀	用途
`/api/*`	与现有 UI 兼容的旧路径
`/api/v1/*`	版本化接口（相同处理程序，适合稳定集成）

新集成应优先使用 /api/v1，过渡期间将 /api 视为别名。

发现与元数据¶

扫描前，客户端通常调用发现端点以了解限制、可用数据源与运行时配置。建议集成流程为：先 GET /api/health 确认服务存活与 scanDays，再 GET /api/capabilities 读取表单上限，最后 GET /api/sources 渲染数据源开关。三者均可通过 /api/v1/… 别名访问，行为与 /api/… 完全一致。

健康检查 — `GET /api/health`（亦 `/api/v1/health`）¶

返回存活状态及非敏感能力标志。用于负载均衡健康检查与启动探针。

响应字段（摘要）：

字段	含义
`ok`	进程正常运行时恒为 `true`
`version`	来自 `package.json` 的应用 semver（如 `1.1.0`）
`sources`	内置数据源 ID
`nvdApiKey` / `githubToken`	是否已配置环境凭据（非凭据值本身）
`scanDays`	来自 `SCAN_DAYS` 的回溯窗口（默认 60）
`translate`	是否允许服务端翻译
`limits`	数值上限（栈大小、批大小等）

Detailed probe: GET /api/health?detailed=true 返回 uptime、各源可达性、cache、air-gap、alerts.webhookConfigured（任一通知渠道已配置）、alerts.minSeverity。

Prometheus metrics — `GET /metrics`¶

根路径（不在 /api 下）。METRICS_ENABLED=true 默认开启；METRICS_PROTECT=true 需 API_SECRET。见 Self-hosted metrics。

能力 — `GET /api/capabilities`¶

返回结构化产品限制与功能开关（单次扫描最大工具数、翻译语言、扫描模式）。构建表单或 CI 校验器时优先于解析 health。

典型响应包含 version、limits（如 maxStackTools: 50、maxCustomFeeds: 20、translateBatchMax）、features（fullScan、watch、translate、customRss、sourceToggles）以及 translateLocales 与 scanModes。集成脚本可缓存此响应数分钟，但在更改 .env 后应重新拉取。

数据源目录 — `GET /api/sources`¶

返回内置数据源注册表（NVD、OSV、GitHub、CISA KEV、RSS 等），含 kind、fullScan、watchScan 标志及默认 RSS URL。自定义源不在此列出；客户端通过 customFeeds 在每次请求中提供。

OpenAPI — `GET /api/openapi.json`¶

提供 OpenAPI 3.1 文档（server/openapi/spec.json），用于代码生成、Postman 导入或契约测试。

请求校验与错误¶

所有 POST 请求体必须为 JSON 对象。校验失败返回 HTTP 400：

{
  "error": "Human-readable message",
  "code": "VALIDATION_ERROR",
  "details": { "max": 50, "received": 72 }
}

上游失败（NVD 限速、RSS 超时）返回 502 或 429，含 error 文本及可选 code（SCAN_FAILED、WATCH_FAILED）。UI 将 error 显示为字符串；集成方可读取 code 与 details。

应用速率限制（middleware）： 当客户端超出每 IP 的 scan 或 watch 配额时，服务端返回 HTTP 429：

{
  "error": "Too many scan requests. Try again later.",
  "code": "RATE_LIMITED",
  "retryAfterSec": 42
}

POST /scan 与 POST /watch 使用独立的每分钟桶。
POST /scan/validate 豁免（适合 CI 与栈检查）。
通过 .env 中的 RATE_LIMIT_SCAN_PER_MIN 与 RATE_LIMIT_WATCH_PER_MIN 调整。

API key / RBAC (v1): 设置 API_SECRET 后需 X-Api-Key 或 Bearer；/api/v1/* 执行 API_ROLE（403 权限不足）。PostgreSQL 多租户发送 X-Tenant-Id。

技术栈规则：

stack — 必填非空工具名字符串数组（trim 后），最多 50 个工具。
customFeeds — 可选，最多 20 条；每条需 id 与 url。
enabledBuiltin — 可选，数据源 ID → boolean；省略键默认为启用。

仅校验不扫描 — `POST /api/scan/validate`¶

校验 stack、enabledBuiltin、customFeeds，不调用外部 CVE 提供方。用于向导或 CI，在昂贵全量扫描前拒绝无效输入。成功时返回 valid: true、toolCount 与 enabledBuiltinSources 计数；失败时与 scan 相同返回 400 及 VALIDATION_ERROR。

请求示例：

{
  "stack": ["Redis", "HAProxy"],
  "enabledBuiltin": { "NVD": true, "TuxCare": false },
  "customFeeds": [{ "id": "custom:team-feed", "name": "Team RSS", "url": "https://example.com/cve.rss" }]
}

响应示例：

{
  "valid": true,
  "stack": ["Redis", "HAProxy"],
  "toolCount": 2,
  "customFeedCount": 1,
  "message": "Stack and source options are valid; run POST /api/scan for findings."
}

全量扫描 — `POST /api/scan`¶

执行 全量扫描：NVD、OSV、GitHub Advisories、CISA KEV、内置 RSS 及启用的自定义 RSS。结果按 CVE ID 合并，经 KEV 利用标志 enrich，可选翻译后一次性返回。

请求体：

字段	类型	必填	说明
`stack`	`string[]`	是	待匹配的工具名
`translate`	`boolean`	否	为 `true` 时翻译标题/描述
`locale`	`fa` \| `ar` \| `ru` \| `zh` \| `fr`	否	`translate` 为 true 时的目标语言
`enabledBuiltin`	`object`	否	各数据源开关
`customFeeds`	`array`	否	额外 RSS/Atom（`custom:…` ID）

示例：

{
  "stack": ["Redis", "HAProxy", "Kubernetes"],
  "translate": true,
  "locale": "zh",
  "enabledBuiltin": { "NVD": true, "TheHackerNews": true }
}

响应： ScanResponse — vulns[]、summary、search_date、meta（sources_checked、sources_updated_at、duration_ms、mode: "full"）。

每条漏洞含 id、tool、title、severity，以及可选的 affected_versions、fixed_version、sources[]、url、patch_available、exploited_in_wild；启用 EPSS 时有 epss（0–1）与 riskScore（0–10），启用合规映射时有 cwe[] 与 compliance_controls[]， enrich 后可有 translations / title_fa。

summary 对象汇总按严重级别计数的总数（如 critical、high、medium、low），便于仪表盘展示。meta.sources_updated_at 记录各数据源最后成功拉取的时间戳，可用于判断数据新鲜度。

扫描时序（集成方视角）¶

sequenceDiagram
  participant Client
  participant API as Express API
  participant Feeds as 外部数据源

  Client->>API: POST /api/scan { stack, translate, locale }
  API->>Feeds: 并行 NVD/OSV/GitHub/KEV/RSS
  Feeds-->>API: 原始发现
  API->>API: 合并、KEV enrich、可选翻译
  API-->>Client: 200 { vulns, summary, meta }

图表说明¶

客户端发送单一 JSON 载荷。服务器向已配置数据源扇出请求，将记录规范为统一漏洞结构，按 CVE ID 去重，并对前 N 项可选翻译（由 TRANSLATE_MAX_ITEMS 控制）。响应含耗时元数据，便于展示进度或审计 SLA。

逐步流程¶

调用 GET /api/capabilities 读取 maxStackTools 与 translateLocales。
可选：用计划扫描的相同 body 调用 POST /api/scan/validate。
携带 stack 与数据源选项执行 POST /api/scan。
若需增量 UI 徽章，保存 vulns 与 meta.sources_updated_at。
遇 429 时退避重试，降低依赖 NVD 的扫描频率。

监视 — `POST /api/watch`¶

运行监视模式：OSV、GitHub、KEV 与 RSS，不含 NVD，延迟更低。请求体与 scan 相同，另可选 knownIds（已见过的 CVE ID）。响应增加 newVulns 与 hasNew，供告警流水线使用。

监视适合定时轮询：客户端保存上次 vulns 的 ID 列表，下次请求传入 knownIds，仅当 hasNew: true 时触发通知。翻译上限低于全量扫描（translateMaxItemsWatch 默认为 15），因此高流量监视场景建议关闭 translate 或事后调用 POST /api/translate。

示例：

{
  "stack": ["Redis"],
  "knownIds": ["CVE-2024-1234", "CVE-2023-9999"],
  "translate": false
}

响应： 同 scan，另含 newVulns[]、hasNew: boolean、meta.mode: "watch"。

当 newVulns 非空且已配置通知环境变量时，服务端通过 NotificationService 分发已配置通道（不影响 JSON 响应）。

翻译 — `POST /api/translate`¶

批量将英文 title / description 译为 UI 语言（MyMemory / LibreTranslate / Ollama，见配置）。用于扫描后切换 UI 语言，或处理超出服务端扫描翻译上限的条目。

请求：

{
  "locale": "zh",
  "items": [
    {
      "id": "CVE-2024-1",
      "tool": "Redis",
      "title": "Heap buffer overflow",
      "description": "…"
    }
  ]
}

响应： { "locale": "zh", "items": [{ "id", "tool", "title", "description" }] }
每请求最大条目数：TRANSLATE_BATCH_MAX（默认 40）。

Versioned API (`/api/v1` only)¶

POST /api/v1/scan/stream（SSE）、GET /api/v1/scans/history、GET /api/v1/scans/trends、tenant/stack CRUD、GET /api/v1/discovery/kubernetes。详见英文 API 章节。

端点汇总¶

方法	路径	说明
GET	`/api/health`	存活 + 标志（`?detailed=true`）
GET	`/metrics`	Prometheus 指标
GET	`/api/capabilities`	限制与功能
GET	`/api/sources`	内置数据源目录
GET	`/api/openapi.json`	OpenAPI 3.1 规范
POST	`/api/scan/validate`	仅校验栈/数据源
POST	`/api/scan`	全量扫描
POST	`/api/watch`	监视轮询 + diff
POST	`/api/translate`	批量翻译
POST	`/api/v1/scan/stream`	SSE 全量扫描 (v1)
GET	`/api/v1/scans/history`	租户扫描历史
GET/POST	`/api/v1/tenants/stacks`	已保存技术栈
GET	`/api/v1/discovery/kubernetes`	K8s 发现

核心 scan/metadata 有 /api/* 别名；v1 专属路由见上表。

安全与部署说明¶

API 面向可信网络。可选共享密钥：服务器设置 API_SECRET；客户端发送 X-Api-Key 或 Authorization: Bearer。GET /api/health 与 GET /api/v1/health 对负载探针免认证。勿在无 TLS 情况下公网暴露。设置 NVD_API_KEY 可提高吞吐。

生产部署时，Express 在 NODE_ENV=production 下同时提供静态前端与 API。健康检查应指向 /api/v1/health 或 /api/health；OpenAPI 契约可用于在 CI 中对比响应 schema。若上游 RSS 或 GitHub 返回 502，请检查服务器日志中的 SCAN_FAILED / WATCH_FAILED 代码并重试。

HTTP API 参考¶

API 设计原则¶

发现与元数据¶

健康检查 — GET /api/health（亦 /api/v1/health）¶

Prometheus metrics — GET /metrics¶

能力 — GET /api/capabilities¶

数据源目录 — GET /api/sources¶

OpenAPI — GET /api/openapi.json¶