Ir para o conteĂşdo

Vulnerability Flow 🔬
Tipo Vulnerabilidade (CWE / OWASP / pentest finding)
Trigger /scan-vuln → /analyze-vuln CWE-NN (ou OWASP-Axx)
Status 🔬 experimental (v1.2.0) — promovido para estável após 2 pilotos OK
Agentes vuln-triage → vuln-investigator → impact-analyzer → architecture-agent → builder-agent → test-validator → pr-generator → release-agent → learning-agent
Checkpoints humanos 5 (o CP0 Ă© extra: o triage define o escopo das ondas)

Pré-requisitos: instalação concluída (00 — Instalação e Setup) e /bootstrap-security rodado (popula cwe-catalog.md e os wrappers em tools/).

1. O que Ă© e quando usar

Diferente do Bug Flow, este fluxo trata classes inteiras de CWE — todas as instâncias de XSS, todas as conexões hardcoded, etc. — com um padrão único de fix.

Use quando: - Há findings de SAST (Semgrep, Veracode), DAST (ZAP) ou relatório de pentest. - O fix envolve uma classe de problema, não um sintoma isolado. - O ticket nasceu de auditoria de security. - Regra prática: se o ticket tem cwe: ou label security/vulnerability, use este workflow.

Use o Bug Flow quando há 1 sintoma específico com root cause única e fix localizado.

2. Diferenças em relação ao Bug Flow

Etapa Bug Flow Vulnerability Flow
Entrada Ticket com sintoma Scan multi-fonte (Semgrep + Veracode + pentest)
Investigação 1 root cause Todas as instâncias da classe CWE
Pré-investigação — vuln-triage: dedup + FP filtering
Granularidade 1 ticket = 1 sintoma 1 ticket = 1 classe CWE
Fix Patch focado PadrĂŁo Ăşnico cobrindo N arquivos
Wave residual — Wave-N permitido quando scanner posterior revela residual
Gate adicional Code review + /security-review + re-scan SAST com 0 findings
Speckit update known-issues + cwe-catalog.md (obrigatório — gate)

architecture-agent, builder-agent, test-validator, pr-generator, release-agent e learning-agent são reusados sem alteração — apenas leem inputs diferentes.

3. VisĂŁo geral do fluxo

/scan-vuln
    └── vuln-triage          → VulnInventory (multi-fonte, dedup, FPs)
             ↓
    ⚡ CHECKPOINT 0 — humano valida classes e ondas
/analyze-vuln CWE-NN (ou OWASP-Axx)
    └── vuln-investigator    → VulnReport por classe (hipóteses L1–L4)
    └── impact-analyzer      → ImpactReport (blast radius dos N arquivos)
             ↓
    ⚡ CHECKPOINT 1 — humano aprova padrão único de fix
             ↓
/generate-fix <ticket>       → architecture-agent (+Mini RFC) + builder-agent (todas as instâncias)
             ↓
    ⚡ CHECKPOINT 2 — humano revisa o patch
             ↓
/run-regression <ticket>     → test-validator (+ re-scan SAST = 0 findings)
             ↓
/open-pr <ticket>            → pr-generator + /security-review (gate adicional)
             ↓
    ⚡ CHECKPOINT 3 — reviewer aprova (dupla aprovação se utilitário cross-cutting)
             ↓
/release-check <ticket>      → release-agent (fast-track de security disponível)
             ↓
    ⚡ CHECKPOINT 4 — humano aprova o deploy
             ↓
    [deploy via pipeline] → learning-agent → atualiza cwe-catalog.md + anti-patterns + metrics

4. Passo a passo

Passo 0 — /scan-vuln [flags] — vuln-triage

  1. LĂŞ .claude/.local-config.json (blocos veracode e semgrep).
  2. Invoca os wrappers tools/semgrep/Run-SemgrepScan.ps1 e/ou tools/veracode/Get-VeracodeFlaws.ps1.
  3. LĂŞ os JSONs em .ns-flow/discovery/ (+ --include-pentest=<path> opcional).
  4. Deduplica por arquivo:linha:cwe e descarta FPs (utilitários endurecidos + heurísticas do cwe-catalog.md).
  5. Atribui status a cada finding: open / closed-via-commit-{SHA} / dismissed-fp / backlog.
  6. Propõe waves por alavanca (config first, design last). Output: .ns-flow/discovery/<TICKET_ID>-vuln-inventory.md (se não houver ticket, o /scan-vuln usa um ID temporário SCAN-YYYY-MM-DD-HHMM).

Modos: auto (padrĂŁo), --fallback, --semgrep-only, --veracode-only, --include-pentest=<path>, --veracode-app=<nome>.

Passo 1 — ⚡ Checkpoint 0 (escopo)

Humano valida classes CWE, proposta de waves, FPs descartados (amostral) e re-classificações. Se OK, abre tickets <prefixo>-NNN por wave/classe.

Passo 2 — /analyze-vuln CWE-NN [<ticket>] (ou OWASP-Axx) — vuln-investigator

  1. Hipóteses L1–L4 (config → cookies → output → estrutural) antes de qualquer Grep.
  2. Lê todas as instâncias open da classe e confirma cada uma no código (não confia no scanner).
  3. Identifica padrão único de fix e o utilitário interno seguro (ou propõe criar).
  4. Lista CIAs/tenants afetados (multi-tenant) e define o ciclo RED→GREEN. Output: .ns-flow/analysis/<ticket>-cwe<NN>-vulnreport.md + ...-cwe<NN>-impact.md

Wave-N: se a classe já tem VulnReport anterior, o agente renomeia o anterior para ...-wave1-vulnreport.md e gera o novo como atual, preservando linhagem auditável.

Passo 3 — ⚡ Checkpoint 1 (padrão único)

Humano valida: padrão cobre todas as instâncias? Utilitário é canônico? L1 tentado antes de L3? CIAs completos? Dependências de infra listadas?

Passos 4–7 — Reuso do Bug Flow

Idênticos ao Bug Flow — incluindo a Esteira de Qualidade (Gates 1/2/3 + /qa-gate). Diferenças mínimas: - /run-regression: além do Gate 1 (1a cobertura + 1b execucao no dev), test-validator acrescenta re-scan /scan-vuln --semgrep-only e exige 0 findings da classe-alvo (gate de segurança específico, complementar aos 4 gates). - /open-pr: pr-generator invoca /security-review como gate — findings ≥ MEDIUM bloqueiam. - /release-check: release-agent aplica release-policy.md com fast-track para severidade ALTA/CRÍTICA.

Passo 8 — Pós-deploy — learning-agent

  1. Atualiza .speckit/known-issues/cwe-catalog.md (cria entrada CWE-NN se não existia — gate).
  2. Atualiza anti-patterns.md (padrão vulnerável novo) e risk-map.md (arquivos do inventário).
  3. Grava em metrics-feed.jsonl (type: "vulnerability", cwe, wave, findings_closed, fps_dismissed...).
  4. Se há wave próxima planejada → cria item no backlog do squad.

5. Checkpoints humanos

# Quando Quem aprova Verifica
0 ApĂłs triage Security/TL Classes corretas? Waves adequadas (config first)? FPs realmente FPs?
1 Após análise por classe Security/TL Padrão cobre todas as instâncias? Utilitário canônico? CIAs completos?
2 ApĂłs patch Reviewer Patch aplica o padrĂŁo Ăşnico em todos os arquivos?
3 No PR Reviewer (dupla se utilitário) /security-review passou? Re-scan = 0 findings?
4 Antes do deploy Responsável de release Gates ✅? Fast-track aplicável?

6. Pastas e arquivos gerados

Etapa Arquivo
Inventário .ns-flow/discovery/<ticket>-vuln-inventory.md
Scans brutos .ns-flow/discovery/semgrep.json, .ns-flow/discovery/veracode-flaws.json
VulnReport por classe .ns-flow/analysis/<ticket>-cwe<NN>-vulnreport.md
Impacto .ns-flow/analysis/<ticket>-cwe<NN>-impact.md
Patch / Validação / PR / Release mesmos do Bug Flow (.ns-flow/delivery/)
Encerramento cwe-catalog.md (gate) + anti-patterns.md + metrics-feed.jsonl

7. Aplicação pelo time (papéis)

Papel Responsabilidade
Security / AppSec Roda /scan-vuln, valida escopo e waves (CP0), aprova padrĂŁo Ăşnico (CP1)
Dev Aplica o padrão único em todas as instâncias via /generate-fix
Reviewer Aprova PR + /security-review (CP3); dupla aprovação se utilitário cross-cutting
Release Aprova deploy com fast-track quando ALTA/CRĂŤTICA (CP4)

8. MĂ©tricas especĂ­ficas

MĂ©trica Target (maduro)
FP-rate por scanner Semgrep < 95%, Veracode < 30% após calibração
Cycle time por classe ≤ 5 dias para classes ≤ 50 findings
Regressões pós-deploy 0
Cobertura de CIAs 100%

ReferĂŞncias

Voltar ao topo