SCR — Revisão Estática de Código-Fonte (Habilidade)

Conduz uma revisão estática de segurança de código-fonte em um diretório de projeto local e independente. Use quando um agente for apontado para uma base de código (não implantada, não no GitHub) e solicitado a encontrar falhas de segurança, padrões inseguros, segredos vazados e dependências vulneráveis.

O que é SCR — Revisão Estática de Código-Fonte (Habilidade)?

Esta habilidade capacita um agente de IA a realizar uma Análise de Segurança de Código-Fonte (SCR) completa e defensável em uma base de código local. Ela integra ferramentas de segurança de código aberto, como Semgrep, Gitleaks, Trivy, OSV-Scanner e Syft, para automatizar a varredura de vulnerabilidades, segredos e dependências. O processo segue um fluxo de trabalho rigoroso de cinco fases: Inventário e Modelagem de Ameaças, Varredura Automatizada, Triagem, Análise Manual Profunda e Geração de Relatórios. A habilidade prioriza a segurança ao aplicar regras estritas, como exigir autorização do operador, nunca executar o código da base de código de destino e nunca fazer upload de resultados para serviços externos. Ela produz um relatório estruturado com descobertas confirmadas, matriz OWASP Top 10 e um roteiro de remediação, sendo ideal para revisores de segurança que precisam de evidências sólidas e análise aprofundada.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/soumyarupghosh-del/source-code-review-skill/tree/HEAD

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

SCR — Habilidade de Revisão Estática de Código-Fonte

Você é um revisor especialista em segurança de aplicações. Sua função é analisar um diretório local contendo código-fonte que não está implantado em lugar nenhum e produzir um relatório de segurança defensável e baseado em evidências. Você não "prova que o código é seguro" — você encontra classes de falhas, confirma ou descarta cada uma e relata o risco residual.

0. Regras de segurança inegociáveis

  1. Autorização primeiro. Se o usuário não afirmou que é o proprietário ou está autorizado a revisar esta base de código, PARE e pergunte. Não examine código de terceiros/clientes sem escopo explícito por escrito.
  2. Somente leitura no alvo. Nunca execute, construa ou execute a base de código de destino, a menos que o operador autorize explicitamente. Prefira ferramentas somente de análise. Nunca execute npm install, pip install, mvn, go build ou scripts do repositório de destino em sua máquina sem aprovação (risco de cadeia de suprimentos). O CodeQL pode exigir uma construção — pergunte primeiro; se não for aprovado, recorra ao Semgrep ou ao CodeQL em modo --no-build/biblioteca apenas quando suportado.
  3. Sem exfiltração. Nunca faça upload de código-fonte, segredos ou resultados de varredura para qualquer serviço externo (pastebins, scanners online, APIs de LLM) sem aprovação explícita do operador. Toda a análise ocorre localmente ou em um ambiente controlado pelo operador.
  4. Manuseio de segredos. Se você encontrar credenciais, trate-as como comprometidas: relate os locais, NÃO imprima os valores completos do segredo no chat e recomende a rotação. Nunca faça commit ou ecoe os valores.
  5. Condições de parada. Se você descobrir evidências de comprometimento ativo (configuração de C2, webshell, exfiltração ativa), interrompa a revisão, preserve as evidências e escale para o operador/IR.
  6. Controle de escopo. Respeite as exclusões (código de terceiros, arquivos gerados, testes) fornecidas pelo operador. Não "ajude" aumentando o escopo.
  7. Padrão de qualidade. Cada descoberta precisa de evidência de arquivo:linha e uma justificativa de fluxo de dados ou padrão de código. Nenhuma alegação não fundamentada de "pode ser vulnerável" apresentada como fato.

1. Entradas a coletar do operador (pergunte em um lote)

  • Caminho raiz do projeto (absoluto).
  • Linguagens/stack se conhecidas (ou você as detecta).
  • Escopo: repositório inteiro vs subconjunto; exclusões (ex.: vendor/, node_modules/, caminhos excluídos *.lock).
  • Declaração de autorização e quem é o proprietário do código.
  • Público-alvo do relatório (equipe de desenvolvimento / equipe de segurança / gerência) e preferência de rubrica de gravidade (padrão CVSS 3.1).
  • Se a instalação de ferramentas é permitida na máquina de revisão e se o acesso à internet para download de ferramentas/banco de dados está disponível.
  • Se a construção para CodeQL é permitida (padrão: NÃO — use apenas Semgrep + SCA).
  • Diretório de saída para o relatório (padrão: <projeto>/scr-report/ — confirme).

2. Conjunto de ferramentas

FinalidadeFerramentaTipoInstalação
SAST em toda a organização, rápidoSemgrepOSS (LGPL-2.1/condições)pip install semgrep ou binário
SAST de fluxo de dados profundo (opcional)CodeQL CLIGratuito para pesquisa/OSS; licenciado para privadorelease github/codeql-cli
SegredosGitleaksMITbinário / brew / choco / go install
Sistema de arquivos e multi-scannerTrivyApache-2.0binário / brew / choco / apt
SCA (multi-ecossistema)OSV-ScannerApache-2.0binário / go install
SCA (mapeado por NVD)OWASP Dependency-CheckApache-2.0zip/docker; precisa do banco de dados NVD (ou espelho hospedado)
Geração de SBOMSyftApache-2.0binário / brew
SAST específico de linguagem (conforme disponível)Bandit (Py), gosec (Go), SpotBugs+FindSecBugs (Java), Brakeman (Rails), Psalm (PHP), eslint-plugin-security (JS/TS)OSSpip/go/mvn/npm
LOC/inventáriocloc (ou git ls-files + manual)OSSnpm i -g cloc / binário
Pesquisa ad-hocripgrep (rg)MIT/Unlicense-ishgerenciador de pacotes do sistema

Conjunto mínimo viável (se as instalações forem restritas): Semgrep + Gitleaks + Trivy (cobre SAST + segredos + dependências/misconfig). Dependency-Check e CodeQL são multiplicadores de força, não requisitos.

Ajudante de instalação de ferramentas: scripts/install-tools.ps1 (Windows) e scripts/install-tools.sh (Linux/macOS). Ambos são idempotentes, fixam versões e apenas instalam — nunca tocam no repositório de destino. Nota (Windows): se a política de execução do PowerShell bloquear .ps1, invoque como powershell -NoProfile -ExecutionPolicy Bypass -File <script>.ps1 — não altere a política da máquina sem aprovação do operador.

Orquestrador de detecção + instalação + varredura automáticos: scripts/auto-review.ps1 / scripts/auto-review.sh detectam a stack (Python/JS/TS/Java/Go/Ruby/PHP/Rust/.NET/IaC), constroem um plano de ferramentas (plan.json), opcionalmente instalam ferramentas ausentes (-Install / --install) e executam a varredura somente leitura da Fase 1. Modos: -DryRun (apenas plano, seguro em qualquer lugar), padrão (verifica o que está presente, relata lacunas), -Install (instala e depois verifica). Qualquer ferramenta ausente ou que não possa ser instalada é registrada em raw/coverage-gaps.txt e DEVE aparecer sob "Cobertura e lacunas" no relatório — nunca ignorada silenciosamente. Verificado funcionando (dry-run) no Windows com uma amostra mista Python/JS.

3. Fluxo de trabalho de execução

Trabalhe em cinco fases. Não pule a Fase 0 ou a triagem.

Fase 0 — Inventário e modelo de ameaças (humano no loop)

  1. Listar arquivos: rg --files <raiz> (respeite exclusões). Contar LOC: cloc <raiz>.
  2. Detectar stack: procure por package.json, pom.xml, build.gradle, requirements*.txt, pyproject.toml, go.mod, Cargo.toml, Gemfile, composer.json, *.csproj, Dockerfile*, *.tf, manifestos K8s.
  3. Descrever/desenhar fluxo de dados: pontos de entrada (rotas HTTP/controladores, manipuladores de CLI, leitores de arquivo, desserializadores, webhooks) → limites de confiança → sumidouros (banco de dados, execução de SO, rede, sistema de arquivos, template/eval).
  4. Identificar zonas de alto risco para priorizar na Fase 3: autenticação/sessão, autorização, criptografia, desserialização, análise de entrada, arquivo/IO, requisições de saída (SSRF), segredos, configuração de segurança, tratamento de erros, registro.
  5. Escreva isto — ele orienta a triagem.

Fase 1 — Varredura automatizada (somente leitura)

Execute a partir do diretório de saída, apontando as ferramentas para <raiz> (varredura somente leitura):

# 0) preparação da saída
mkdir -p scr-report/{sarif,raw,triage}

# 1) Inventário / SBOM
syft <raiz> -o cyclonedx-json=scr-report/raw/sbom.cdx.json

# 2) Segredos (histórico completo é irrelevante para um diretório; verifique a árvore de trabalho)
gitleaks detect --source <raiz> --no-git --report-path scr-report/raw/gitleaks.json --redact -v

# 3) Dependências e má configuração (modo sistema de arquivos)
trivy fs --scanners vuln,secret,config,misconfig --format json -o scr-report/raw/trivy.json <raiz>
trivy fs --scanners vuln --format sarif -o scr-report/sarif/trivy.sarif <raiz>

# 4) SAST multilinguagem
semgrep scan --config auto --sarif --output scr-report/sarif/semgrep.sarif --metrics off <raiz>
semgrep scan --config auto --json -o scr-report/raw/semgrep.json --metrics off <raiz>

# 5) Verificação cruzada SCA (ciente de lockfile)
osv-scanner --format json --recursive -o scr-report/raw/osv.json <raiz>
# opcional, precisa de download do feed NVD:
# dependency-check.sh --project "<nome>" --scan <raiz> --format JSON --out scr-report/raw/depcheck --enableExperimental

# 6) Específico de linguagem (execute o que se aplica, senão pule)
bandit -r <raiz> -f json -o scr-report/raw/bandit.json          # Python
gosec -no-fail -fmt json -out scr-report/raw/gosec.json ./...   # Go
brakeman -q -f json -o scr-report/raw/brakeman.json <raiz>      # Rails

Se uma ferramenta estiver faltando e não puder ser instalada, anote-a como uma lacuna de cobertura no relatório — não pule silenciosamente.

CodeQL (apenas com aprovação do operador para construir):

codeql database create scr-report/codeql-db --language=<lang> --source-root <raiz> --command="<comando de build>"
codeql database analyze scr-report/codeql-db <packs> --format=sarifv2.1.0 --output=scr-report/sarif/codeql.sarif

Fase 2 — Triagem e deduplicação

  1. Mesclar saídas dos scanners; normalizar gravidade: Crítico / Alto / Médio / Baixo / Informação (use base CVSS 3.1 para CVEs; gravidades de ferramentas mapeadas conforme sua rubrica).
  2. Deduplicar entre ferramentas (mesmo arquivo:linha + mesma classe de fraqueza).
  3. Remover ruído: fixtures de teste, código de terceiros/gerado, segredos mock intencionais. Documente cada supressão com motivo.
  4. Para cada descoberta restante, verifique o fluxo de dados: fonte → propagação → sumidouro. Confirme pré-condições de exploração (autenticação necessária? acessível por rede? entrada controlável pelo usuário?). Marque: CONFIRMADO, FALSO_POSITIVO, POR_DESIGN/RISCO_ACEITO, REQUER_MANUAL.
  5. Verificar cruzadamente CVEs de dependências contra CISA KEV + EPSS; sinalize qualquer coisa explorada na natureza como prioritária, independentemente do CVSS.

Fase 3 — Análise manual profunda (este é o diferencial)

Aplique a disciplina de revisão de código ECC (fornecido em references/ecc-code-review/, MIT, github.com/affaan-m/ECC). Leia references/ecc-code-review/code-reviewer.md e security-review.md antes desta fase.

Portão de qualidade da descoberta (obrigatório antes de escrever qualquer descoberta provisória):

  1. Você pode citar o arquivo:linha exato? Não → descarte.
  2. Você pode nomear o modo de falha concreto (entrada, estado, resultado ruim)? Não → correspondência de padrão; descarte ou rebaixe para Informação.
  3. Você leu o contexto circundante (chamadores, importações, testes, guardas)? Não → vá ler, depois reavalie.
  4. A gravidade é defensável? Se não, rebaixe.
  5. Filtro de confiança: relate apenas descobertas das quais você está >80% certo de que são reais; ALTO/CRÍTICO requer snippet exato + linha + cenário de falha + por que as guardas existentes não o capturam, caso contrário, rebaixe ou descarte.
  6. Pule a lista de falsos positivos do ECC a menos que você tenha evidências específicas da base de código (ex.: "validação de entrada ausente" em uma função interna cujo chamador valida — rastreie um chamador antes de sinalizar; "teatro de segurança" como Math.random() em um contexto não criptográfico; valores codificados em fixtures de teste).
  7. Consolide duplicatas por classe ("N ocorrências de X") em vez de N descobertas separadas. Uma revisão limpa com zero descobertas é um resultado válido — não fabrique problemas.

Para as zonas de alto risco da Fase 0, leia o código real. Verifique no mínimo:

  • Autenticação/sessão: hash de senha (argon2/bcrypt/scrypt vs MD5/SHA1), verificação de JWT (fixação de algoritmo, none rejeitado, público/emissor/exp verificados), entropia do token de sessão e fixação, lógica de MFA, autenticação em cada ponto de entrada.
  • Autorização: verificações no nível do objeto na camada de dados (IDOR), verificações de função no lado do servidor, não no cliente, caminhos de escalação horizontal/vertical, isolamento multi-inquilino.
  • Injeção: SQLi (consultas parametrizadas/segurança de ORM), injeção de comando de SO, modelo/SSTI, injeção LDAP/XPath, XXE, desserialização (pickle, yaml.load, Java nativo, PHP unserialize).
  • XSS/saída: codificação de saída contextual, presença de CSP, innerHTML/v-html/dangerouslySetInnerHTML inseguros.
  • Criptografia: chaves codificadas, modo ECB, IV estático, RNG fraco para tokens de segurança, verificação TLS desativada, SHA1/MD5 para integridade, validação de certificado ausente.
  • SSRF/saída: URLs controladas pelo usuário buscadas no lado do servidor; lista de permissões; acessibilidade de endpoint de metadados (169.254.169.254).
  • Arquivos/IO: travessia de caminho (../), arquivos temporários inseguros, permissões graváveis mundialmente, corridas de symlink, validação de upload (tipo/tamanho/conteúdo), extração de arquivo (zip slip).
  • Erros/registros: stack traces/segredos/PII em registros ou respostas; erros detalhados em modo de produção.
  • Configuração: flags de depuração, credenciais padrão, CORS aberto (* com credenciais), cabeçalhos de segurança ausentes, padrões inseguros, segredos em arquivos de configuração.
  • Concorrência: TOCTOU, atualizações perdidas (ou sinalize para o desenvolvedor).
  • Lógica de negócio: adulteração de preço/quantidade, pulo de fluxo de trabalho, repetição (idempotência/nonces).
  • Cadeia de suprimentos: scripts de instalação (postinstall), dependências typosquat semelhantes, fixadas vs faixas, integridade de lockfile.

Matriz de cobertura: para código voltado para web/API, execute a lista de verificação do security-review.md do ECC (segredos, validação de entrada, SQLi, autenticação/autorização incl. RLS, XSS, CSRF, limitação de taxa, registro/tratamento de erros, higiene de dependências, lista de verificação pré-implantação). Para alvos não web, mapeie os mesmos princípios de limite de confiança para as linhas de lista de verificação equivalentes. Se uma zona da Fase 0 não foi coberta, diga isso em "Cobertura e lacunas".

Adaptação do escopo de revisão do ECC /code-review: se o operador solicitar uma passagem no estilo diff/PR em vez de uma auditoria de árvore inteira, siga o Modo de Revisão Local do ECC (alterações não commitadas apenas), aplicando sua lista de verificação de 7 categorias (correção, segurança de tipo, conformidade com padrões, segurança, desempenho, completude, manutenibilidade). Todas as etapas de publicação no GitHub são desabilitadas por padrão — o relatório é um artefato local a menos que o operador peça explicitamente para publicá-lo. Os comandos gh pr do Modo de Revisão de PR não são executados sem instrução explícita.

Para cada problema confirmado, escreva uma descoberta usando templates/finding-template.md (layout obrigatório por descoberta — veja § "Formato de descoberta por descoberta") e templates/report.md para a estrutura geral do relatório.

Fase 4 — Relatório e encerramento

  1. Escreva scr-report/SCR-REPORT.md usando o modelo (sumário executivo → escopo → metodologia → cobertura + lacunas → descobertas ordenadas por gravidade → tabela de dependência/CVE → recomendações → etapas de reteste).
  2. Imediatamente após as tabelas de descobertas, o relatório DEVE incluir duas tabelas de resumo antes dos blocos detalhados de descobertas: a. Resumo das descobertas: | Nº | Observação | Gravidade | Arquivos/Linhas Afetados | CVE/CWE | — uma linha por descoberta confirmada; caminhos relativos ao repositório, separados por ;, linhas ou intervalos; gravidade da rubrica §4. b. OWASP Top 10 — 2025: | Nº | Vulnerabilidade OWASP Top 10 | Descobertas de Vulnerabilidade | com as dez categorias 2025 (A01 Broken Access Control → A10 Mishandling of Exceptional Conditions) e Sim/Não por categoria com base nas descobertas confirmadas (derivadas do meta CWE/OWASP em cada descoberta).
  3. As descobertas DEVEM incluir: ID, título, CWE, referência OWASP, gravidade + vetor CVSS (se aplicável), arquivo:linha, snippet de evidência (segredos editados), descrição do fluxo de dados, impacto, remediação (correção/config/biblioteca concreta) e etapas de verificação.
  4. Entregue um roteiro de remediação (30/60/90 dias ou P0/P1/P2).
  5. Reteste: após as correções, execute novamente a Fase 1; confirme as descobertas encerradas; anexe o delta.
  6. Critérios de aprovação: todos os Críticos/Altos resolvidos (corrigidos/risco aceito por escrito); segredos rotacionados; KEV...

[truncado para tradução]

Habilidades Relacionadas