API-Dokumentation

Authentifizierung

Senden Sie Ihren API-Schlüssel als Bearer-Token oder im X-API-Key-Header:

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

Rate-Limits

120 Anfragen pro Minute pro Schlüssel. Jede Antwort enthält die Header X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Bei Überschreitung des Limits wird 429 mit einem Retry-After-Header zurückgegeben.

Einen Scan starten

POST /api/v1/scans — startet einen On-Demand-Scan eines Ziels (wird Ihrem Konto hinzugefügt, falls neu). Gibt eine Scan-id zum Abfragen zurück.

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

Scan-Status & Ergebnisse

GET /api/v1/scans/{id} — fragen Sie ab, bis done true ist. Gibt eine Schweregrad-summary und die Liste der findings zurück — nutzen Sie sie, um eine CI-Pipeline zu bestehen oder fehlschlagen zu lassen.

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

Siehe DevSecOps-Pipeline für vollständige GitLab CI- und GitHub Actions-Beispiele, die auf den Scan warten und den Build bei kritischen Befunden fehlschlagen lassen.

Ziele hinzufügen (Massen, bis zu 1000)

POST /api/v1/targets/bulk — akzeptiert Domains oder IPs, optional mit Tags. Berücksichtigt das Ziellimit Ihres Plans.

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

Ziele löschen (Massen)

DELETE /api/v1/targets/bulk — nach IDs oder nach Werten (IPs / Hostnamen).

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

Tags aktualisieren (Massen)

PATCH /api/v1/targets/tags — setzen, hinzufügen oder entfernen Sie Tags an vielen Zielen gleichzeitig (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-Spezifikation

Die vollständige maschinenlesbare Spezifikation ist verfügbar unter /api/v1/openapi.json — importieren Sie sie in Postman, Insomnia oder Ihren Code-Generator.