Static Analysis

Static Analysis — Scan Automatizado de Vulnerabilidades

Eleva a Security Review (skill 06) de "review manual" para "scan + triagem". Semgrep para velocidade e cobertura ampla, CodeQL para taint tracking interprocedural quando o caso exige.

Governanca Global

Esta skill segue GLOBAL.md, policies/execution.md, policies/tool-safety.md, policies/quality-gates.md, policies/writing-clarity.md.

Consultar docs/skill-guides/static-analysis.md para rulesets avancados, custom rules e integracao em CI.

Quando Usar

• pre-release (toda release passa por scan)
• PR que toca auth, validacao de input, parsing, serializacao, deps externas
• bug encontrado: rodar variant analysis para achar similares
• suspeita de classe de bug recorrente (ex: SQL injection, SSRF, prototype pollution)
• antes de promover modulo para producao
• auditoria periodica (mensal ou trimestral)

Quando Nao Usar

• bug fix localizado em arquivo conhecido
• refactor sem mudanca de comportamento
• prototipagem inicial (onde codigo ainda muda muito)

Entradas Esperadas

• caminho do repositorio ou subdiretorio
• linguagens predominantes
• (opcional) ruleset especifico ou bug similar a procurar

Saidas Esperadas

• relatorio em SARIF (.sarif) ou markdown estruturado
• findings classificados por severidade (Critical / High / Medium / Low / Info)
• triagem (true positive / false positive / needs investigation)
• handoff para skill 06 (Security Review) com top findings
• handoff para debugger se finding tiver root cause nao trivial

Responsabilidades / Protocolo

1. Detectar linguagens do repositorio
2. Selecionar rulesets apropriados (default: --config=auto + ruleset OWASP)
3. Executar scan (Semgrep primeiro; CodeQL se padrao envolve fluxo)
4. Gerar SARIF + relatorio markdown
5. Triagem — classificar TP/FP/needs-investigation
6. Suprimir FPs com comentario justificando
7. Handoff para skill 06 com sumario
8. Variant analysis se padrao recorrer (custom rule)
9. CI integration quando aplicavel

Detalhes operacionais nas sub-secoes a seguir.

Ferramentas

Semgrep (default — comecar por aqui)

Instalar:

pip install semgrep
# ou via Docker
docker run --rm -v "$PWD:/src" returntocorp/semgrep semgrep --config=auto

Rodar:

# Auto: detecta linguagens, aplica rulesets oficiais
semgrep --config=auto --sarif --output=semgrep.sarif

# Ruleset especifico
semgrep --config=p/owasp-top-ten --sarif --output=owasp.sarif
semgrep --config=p/security-audit
semgrep --config=p/typescript

# Custom rule
semgrep --config=./my-rule.yml src/

Rulesets recomendados por linguagem:

• TS/JS: p/typescript, p/javascript, p/react, p/nextjs, p/owasp-top-ten
• Python: p/python, p/django, p/flask, p/owasp-top-ten
• Go: p/golang, p/gosec
• Java: p/java, p/spring
• Geral: p/security-audit, p/secrets, p/ci

CodeQL (quando precisar de taint tracking interprocedural)

Instalar:

# Download CodeQL CLI
# https://github.com/github/codeql-cli-binaries/releases

Rodar:

# Build database
codeql database create db --language=javascript --source-root=.

# Run query suite
codeql database analyze db --format=sarif-latest --output=results.sarif \
  codeql/javascript-queries

# Custom query
codeql query run --database=db my-query.ql

Quando usar CodeQL em vez de Semgrep:

• bug envolvendo data flow entre funcoes/arquivos
• bug que so aparece em condicoes de chamada especificas
• variant analysis sofisticada apos achar bug inicial

Subagents auxiliares (despachaveis via Task tool)

Para escala (multi-linguagem, >20 findings, variant analysis), despachar via Task:

• semgrep-scanner — executa scans em paralelo por categoria de linguagem, agrega SARIF. Use quando repo tem 2+ linguagens primarias.
• semgrep-triager — classifica findings em TP/FP/needs-investigation lendo contexto fonte. Use quando ha >20 findings.
• codeql-runner — orquestra build de database CodeQL + queries com taint tracking interprocedural. Use quando bug envolve data flow entre arquivos/funcoes.
• sarif-parsing — parse, dedup, agregacao de SARIF de multiplas fontes. Use quando consolidar Semgrep + CodeQL ou multiplos scans.
• variant-analysis — caca variantes do mesmo padrao apos achar bug inicial, gera custom rule reusavel. Use apos confirmar bug que pertence a classe (SQLi, XSS, missing auth, etc).

Cada subagent tem definicao em .claude/agents/.md com protocolo, inputs, outputs e guardrails proprios. Para uso simples (1 linguagem, scan rapido, poucos findings), rodar inline conforme blocos abaixo.

Pipeline Recomendado

1. Semgrep --config=auto    (5-30s, cobertura ampla)
   → triage via `semgrep-triager` subagent (ou inline se 

**Tool:** semgrep --config=auto + p/owasp-top-ten
**Scope:** src/
**Duration:** 23s
**Files scanned:** 247

## Summary
- Critical: 1
- High: 3
- Medium: 8
- Low: 14
- Info: 22

## Critical Findings

### F-001: SQL Injection em src/db/users.ts:42
**Rule:** javascript.lang.security.sql-injection
**Confidence:** high (TP confirmed)
**Evidence:**
```ts
const query = `SELECT * FROM users WHERE id = ${userId}`;

Fix: usar prepared statement

const query = `SELECT * FROM users WHERE id = $1`;
db.query(query, [userId]);

Owner: skill 03 (Backend)

High Findings

...

Suppressed (FP)

• src/legacy/oldHash.ts:88 — weak-crypto: hash usado para deduplicacao, nao seguranca

## Integracao com CI

Adicionar a `.github/workflows/`:

```yaml
- name: Semgrep scan
  run: semgrep --config=auto --error --severity=ERROR

--error faz CI quebrar em finding Critical/High.

Codigo Limpo

Output deve seguir policies/writing-clarity.md. Sem narrativa, sem hedging, sem prosa decorativa. Tabela de findings + acao concreta por linha.

Evidencia de Conclusao

• relatorio SARIF gerado (timestamped)
• findings triados (TP/FP/needs-investigation)
• top Critical/High com fix sugerido
• FPs suprimidos com comentario justificando
• handoff para skill 06 com sumario

Handoff

Apos conclusao, entregar:

1. caminho do .sarif + .md
2. contagem por severidade
3. lista de Critical/High que bloqueiam merge
4. sugestao: skill 06 valida, debugger investiga root cause complexo, variant analysis se padrao recorrente

Integracao com Pipeline

• Security Review (skill 06): consome output, valida contexto OWASP, bloqueia release
• Debugger (subagent): investiga root cause de finding com fluxo complexo
• Reviewer (skill 11): quality gate — Critical/High aberto = no merge
• Release Manager (skill 24): scan obrigatorio antes de cada release
• Migration & Refactor (skill 23): scan antes/depois de refactor grande para detectar regressao

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: felvieira
• Source: felvieira/claude-skills-fv
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.