Tài liệu API

Xác thực

Gửi khóa API của bạn dưới dạng bearer token hoặc trong header X-API-Key:

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

Giới hạn tốc độ

120 yêu cầu mỗi phút cho mỗi khóa. Mỗi phản hồi đều có các header X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Vượt quá giới hạn sẽ trả về 429 kèm header Retry-After.

Bắt đầu một lần quét

POST /api/v1/scans — bắt đầu một lần quét theo yêu cầu trên một mục tiêu (sẽ được thêm vào tài khoản của bạn nếu là mới). Trả về id quét để theo dõi.

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" }

Trạng thái & kết quả quét

GET /api/v1/scans/{id} — theo dõi cho đến khi done là true. Trả về một summary theo mức độ nghiêm trọng và danh sách findings — dùng chúng để cho qua hoặc làm thất bại một pipeline 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" } ] }

Xem Quy trình DevSecOps để có các ví dụ đầy đủ về GitLab CI và GitHub Actions chờ lần quét hoàn tất và làm thất bại bản dựng khi có phát hiện nghiêm trọng.

Thêm mục tiêu (hàng loạt, tối đa 1000)

POST /api/v1/targets/bulk — chấp nhận tên miền hoặc IP, tùy chọn kèm thẻ. Tuân theo giới hạn mục tiêu của gói bạn dùng.

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"]}]}'

Xóa mục tiêu (hàng loạt)

DELETE /api/v1/targets/bulk — theo ID hoặc theo giá trị (IP / tên máy chủ).

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"]}'

Cập nhật thẻ (hàng loạt)

PATCH /api/v1/targets/tags — đặt, thêm hoặc xóa thẻ trên nhiều mục tiêu cùng lúc (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"}'

Đặc tả OpenAPI

Đặc tả đầy đủ, máy đọc được có sẵn tại /api/v1/openapi.json — nhập nó vào Postman, Insomnia hoặc trình tạo mã của bạn.