VulnScan AI
Você tem uma lista de achados de varredura e ninguém para dizer o que fazer com cada um.
VulnScan AI não é um scanner. É a camada de IA que fica em cima de um achado que o JustCyber Scan já produziu. O achado vive em `scan_findings`, e só existe sob um ativo cuja propriedade o cliente comprovou por DNS-TXT. O enrich não abre conexão nova com o alvo: ele analisa a evidência já coletada.
O fluxo é um botão. O analista abre a vulnerabilidade, pede o enriquecimento, e a chamada faz hold do crédito, chama o modelo pelo AiGateway e captura no sucesso. Se a chamada ao modelo falha (Gateway indisponível, erro de rede, parse quebrado antes da resposta), a reserva é liberada e o cliente não paga. Se o egress é barrado pelo guardrail ou o modelo devolve texto ilegível, a chamada ao provedor aconteceu: o crédito é capturado e a resposta vem com um bloco determinístico derivado da severidade do scanner, carimbado com o motivo (`egress_blocked` ou `unparseable`). O cliente paga nesses dois casos, mas o carimbo diz exatamente o que ele recebeu.
A evidência técnica do achado (headers, banners, TLS, DNS) é tratada como dado hostil: entra embrulhada em `<untrusted_context>` e nunca como instrução. O prompt proíbe inventar CVE e CVSS. Quando não há base, `ai_cvss` volta nulo e a confiança volta `low` — estado honesto em vez de número bonito. O resultado é gravado em `scan_findings.evidence->'ai'` com `jsonb_set`, então os GET do Scan já devolvem o enrich sem mudança no caminho de leitura.
Capacidades em operação
Cada item corresponde a funcionalidade que existe no código e é alcançável por um usuário com o escopo correto.
-
Enriquecimento sob demanda de um achado
POST /scan/findings/{id}/enrich, escopo `scan:finding:write`. Idempotency-Key é obrigatória (a rota movimenta crédito) e o rate-limit é 10 por minuto, contado por IP e por tenant.
-
Saída de vocabulário fechado
Explicação em PT-BR, prioridade p1 a p4, passos de remediação, impacto de negócio, CVSS estimado ou nulo, confiança low/medium/high, mais `model_used`, `run_id` e `enriched_at` para auditoria.
-
Não inventa CVE nem CVSS
O CVSS é saneado para 0.0-10.0 ou nulo; valor fora de faixa ou não numérico vira nulo. Resposta sem JSON válido cai no bloco determinístico por severidade, marcado com `fallback_reason`.
-
Cobrança só quando entrega
Cobrança por hold-then-capture — hold na abertura, capture quando a chamada ao provedor acontece, release em qualquer exceção. Guardrail barrado e resposta ilegível contam como chamada feita e são capturados, com o bloco de fallback carimbado. Achado já enriquecido devolve o enrich existente sem gastar crédito (`replayed: true`), a menos que o corpo peça `force`.
-
Persistência sem tabela nova
`jsonb_set` em `scan_findings.evidence->'ai'` preserva headers e banners já coletados. Cada enrich grava uma linha em `audit_log` com ação `vulnscan.finding.enriched`, sem PII.
-
Defesa contra injeção de prompt
Título, categoria e severidade passam por `sanitize_untrusted`; descrição e evidência entram por `wrap_untrusted`. Um enrich anterior é removido do payload antes de reenviar, para o modelo não se realimentar.
Entregáveis
- Bloco `ai` dentro de `evidence` do achado, devolvido por GET /scan/findings e GET /scan/findings/{id}.
- Painel de enriquecimento na tela /app/vulnerabilidades, com o resultado, a marca de prioridade e o aviso de "enrich já existente — sem novo custo".
- Linha de auditoria por enrich, com prioridade, confiança, modelo e id do turno de IA.
O que este módulo não faz
Não varre nada: depende de um achado que o Scan já produziu sob ativo verificado. O enrich automático ao fim da varredura NÃO existe — `app/worker/tasks/scan.py` não chama `enrich_finding`, e a configuração `JC_VULNSCAN_ENRICH_AUTO_MIN_SEVERITY` não é lida por nenhum código do repositório. Não há escopo RBAC `vulnscan:*`: a rota reusa `scan:finding:write`. Não há enrich em lote — um achado por chamada. O `ai_cvss` é estimativa do modelo, não CVSS calculado por vetor. O preço é fixo em créditos (3.0 por padrão) e não deriva do custo real do turno de IA.
Declaramos o limite porque software de segurança que promete tudo não é auditável. Se o que falta aqui é o que você precisa, o serviço consultivo cobre — ou dizemos que não cobre.
Conecta com
- app/scan (achados, gate de propriedade, guard SSRF)
- app/ai (AiGateway, registry, sanitize, persistence)
- app/billing (hold/capture/release)
- app/api/idempotency e app/core/ratelimit
- tela /app/vulnerabilidades no app web
Controle de acesso
O acesso é concedido por escopo, não por perfil genérico. Quem só precisa ler não recebe permissão de escrita, e a barreira é o banco de dados, não a interface.
- scan:finding:write
- scan:finding:read
Quer ver funcionando?
Demonstração com dado do seu ambiente, não com base de exemplo. É a única forma de saber se serve.