Documentación de la API

Autenticación

Envíe su clave de API como bearer token o en la cabecera X-API-Key:

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

Límites de tasa

120 solicitudes por minuto por clave. Cada respuesta incluye las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Superar el límite devuelve 429 con una cabecera Retry-After.

Iniciar un análisis

POST /api/v1/scans — inicia un análisis bajo demanda sobre un objetivo (añadido a su cuenta si es nuevo). Devuelve un id de análisis para consultar.

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

Estado y resultados del análisis

GET /api/v1/scans/{id} — consulte hasta que done sea true. Devuelve un summary de severidad y la lista de findings — úselos para aprobar o reprobar un pipeline de 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" } ] }

Consulte el Pipeline DevSecOps para ver ejemplos completos de GitLab CI y GitHub Actions que esperan al análisis y hacen fallar la compilación ante hallazgos críticos.

Añadir objetivos (masivo, hasta 1000)

POST /api/v1/targets/bulk — acepta dominios o IP, opcionalmente con etiquetas. Respeta el límite de objetivos de su plan.

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

Eliminar objetivos (masivo)

DELETE /api/v1/targets/bulk — por IDs o por valores (IP / nombres de host).

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

Actualizar etiquetas (masivo)

PATCH /api/v1/targets/tags — establezca, añada o elimine etiquetas en muchos objetivos a la vez (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"}'

Especificación OpenAPI

La especificación completa legible por máquina está disponible en /api/v1/openapi.json — impórtela en Postman, Insomnia o su generador de código.