Documentação da API

Autenticação

Envie sua chave de API como um bearer token ou no cabeçalho X-API-Key:

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

Limites de taxa

120 requisições por minuto por chave. Toda resposta inclui os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Exceder o limite retorna 429 com um cabeçalho Retry-After.

Iniciar uma varredura

POST /api/v1/scans — inicia uma varredura sob demanda em um alvo (adicionado à sua conta, se for novo). Retorna um id de varredura 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" }

Status e resultados da varredura

GET /api/v1/scans/{id} — consulte até que done seja true. Retorna um summary de severidade e a lista de findings — use-os para aprovar ou reprovar um 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" } ] }

Veja Pipeline DevSecOps para exemplos completos de GitLab CI e GitHub Actions que aguardam a varredura e reprovam o build em achados críticos.

Adicionar alvos (em massa, até 1000)

POST /api/v1/targets/bulk — aceita domínios ou IPs, opcionalmente com tags. Respeita o limite de alvos do seu plano.

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

Excluir alvos (em massa)

DELETE /api/v1/targets/bulk — por IDs ou por valores (IPs / nomes 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"]}'

Atualizar tags (em massa)

PATCH /api/v1/targets/tags — define, adiciona ou remove tags em vários alvos de uma 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"}'

Especificação OpenAPI

A especificação completa legível por máquina está disponível em /api/v1/openapi.json — importe-a para o Postman, Insomnia ou seu gerador de código.