API 文件

驗證

以 bearer token 或在 X-API-Key 標頭中傳送您的 API 金鑰：

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 或您的程式碼產生器。