API 文档

身份验证

将您的 API 密钥作为 bearer 令牌发送，或放入 X-API-Key 标头中：

curl https://vulny.app/api/v1/targets \
  -H "Authorization: Bearer vlny_your_key"

速率限制

每个密钥每分钟 120 个请求。每个响应都包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 标头。超出限制将返回 429 并附带 Retry-After 标头。

启动扫描

POST /api/v1/scans — 对某个目标启动按需扫描（如为新目标则添加到您的账户）。返回可供轮询的扫描 id。

curl -X POST https://vulny.app/api/v1/scans \
  -H "Authorization: Bearer vlny_your_key" \
  -H "Content-Type: application/json" \
  -d '{"target":"example.com"}'

# → { "id": "...", "target": "example.com", "status": "queued" }

扫描状态与结果

GET /api/v1/scans/{id} — 轮询直至 done 为 true。返回严重性 summary 和 findings 列表——可用于让 CI 流水线通过或失败。

curl https://vulny.app/api/v1/scans/SCAN_ID \
  -H "Authorization: Bearer vlny_your_key"

# → { "status": "finished", "done": true, "progress": 100,
#     "summary": { "critical": 1, "high": 2, "medium": 0, "low": 3, "total": 6 },
#     "findings": [ { "severity": "critical", "title": "CVE-2024-...", "cvss_score": 9.8, "port": "443/tcp" } ] }

如需等待扫描完成并在出现严重发现项时使构建失败的完整 GitLab CI 和 GitHub Actions 示例，请参见 DevSecOps 流水线。

添加目标（批量，最多 1000 个）

POST /api/v1/targets/bulk — 接受域名或 IP，可选附带标签。遵守您方案的目标数量上限。

curl -X POST https://vulny.app/api/v1/targets/bulk \
  -H "Authorization: Bearer vlny_your_key" \
  -H "Content-Type: application/json" \
  -d '{"targets":["example.com","203.0.113.10",{"value":"api.example.com","tags":["prod"]}]}'

删除目标（批量）

DELETE /api/v1/targets/bulk — 按 ID 或按值（IP / 主机名）删除。

curl -X DELETE https://vulny.app/api/v1/targets/bulk \
  -H "Authorization: Bearer vlny_your_key" \
  -H "Content-Type: application/json" \
  -d '{"values":["example.com","203.0.113.10"]}'

更新标签（批量）

PATCH /api/v1/targets/tags — 一次性对多个目标设置、添加或移除标签（mode：set | add | remove）。

curl -X PATCH https://vulny.app/api/v1/targets/tags \
  -H "Authorization: Bearer vlny_your_key" \
  -H "Content-Type: application/json" \
  -d '{"values":["example.com"],"tags":["pci","prod"],"mode":"add"}'

OpenAPI 规范

完整的机器可读规范位于 /api/v1/openapi.json — 可将其导入 Postman、Insomnia 或您的代码生成器。