Documentazione API

Autenticazione

Invia la tua chiave API come bearer token o nell'header X-API-Key:

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

Limiti di frequenza

120 richieste al minuto per chiave. Ogni risposta include gli header X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Il superamento del limite restituisce 429 con un header Retry-After.

Avvia una scansione

POST /api/v1/scans — avvia una scansione su richiesta su un target (aggiunto al tuo account se nuovo). Restituisce un id di scansione da interrogare.

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

Stato e risultati della scansione

GET /api/v1/scans/{id} — interroga finché done non è true. Restituisce un summary per gravità e l'elenco dei findings — usali per far passare o fallire una 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" } ] }

Vedi Pipeline DevSecOps per esempi completi di GitLab CI e GitHub Actions che attendono la scansione e fanno fallire la build in caso di risultati critici.

Aggiungi target (in blocco, fino a 1000)

POST /api/v1/targets/bulk — accetta domini o IP, facoltativamente con tag. Rispetta il limite di target del tuo piano.

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

Elimina target (in blocco)

DELETE /api/v1/targets/bulk — per ID o per valori (IP / hostname).

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

Aggiorna i tag (in blocco)

PATCH /api/v1/targets/tags — imposta, aggiungi o rimuovi tag su molti target contemporaneamente (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"}'

Specifica OpenAPI

La specifica completa leggibile dalle macchine è disponibile su /api/v1/openapi.json — importala in Postman, Insomnia o nel tuo generatore di codice.