auditoria-de-seguranca-de-contratos-inteligentes-foundry

Auditoria de Segurança de Contratos Inteligentes Foundry

Visão Geral

Contratos inteligentes implantados são imutáveis e custodiam fundos reais, portanto, um bug enviado para a mainnet não pode ser corrigido — ele só pode ser explorado. A maioria das perdas catastróficas em DeFi vem de um pequeno conjunto de classes recorrentes: reentrância, controle de acesso quebrado, manipulação de oráculo/preço e aritmética ou chamadas externas não verificadas.

Esta skill executa uma auditoria pré-implantação em camadas de um projeto Foundry, combinando quatro técnicas independentes que cada uma captura o que as outras perdem:

1. Análise estática — slither (90+ detectores) e aderyn (Cyfrin, Rust) escaneiam o AST/IR em segundos em busca de anti-padrões conhecidos.
2. Execução simbólica — mythril (opcional, lento) explora caminhos de execução e resolve SMT para bugs profundos de aritmética/reentrância.
3. Testes baseados em propriedades — forge test com fuzzing (testFuzz_*) e testes de invariantes (invariant_* + contratos handler com variáveis fantasma) prova que propriedades de nível de protocolo se mantêm em milhões de sequências aleatórias.
4. Revisão manual + higiene de chaves — uma checklist estruturada (consulte references/vulnerability-checklist.md) e uma auditoria de segredos/keystore para que nenhuma chave privada esteja em texto simples e a implantação passe por um keystore criptografado do cast (consulte references/secure-deployment-and-keys.md).

A skill é do lado do desenvolvedor e pré-implantação — é executada pelo engenheiro que está construindo o contrato, não por um SOC após um incidente. As descobertas bloqueiam o deploy: qualquer descoberta estática de alta/crítica, teste falhando, chave vazada ou baixa cobertura = FAIL.

Quando Usar

• Antes de implantar qualquer contrato Solidity em uma testnet ou mainnet EVM.
• Ao escrever ou revisar um projeto Foundry (foundry.toml, src/, test/, script/).
• Quando um contrato lida com valor: tokens (ERC-20/721/1155), vaults, staking, AMMs, pontes, governança.
• Ao adicionar testes de fuzz ou invariantes, ou quando a cobertura de funções que movimentam valor é desconhecida.
• Ao conectar scripts de implantação — para verificar se as chaves estão em um keystore criptografado, não em texto simples no .env.
• Ao integrar um oráculo de preço, chamada externa, delegatecall ou proxy atualizável.
• Ao triar um relatório do Slither/Aderyn e precisar separar bugs reais de falsos positivos.

Pré-requisitos

• Foundry instalado (forge, cast, anvil): curl -L https://foundry.paradigm.xyz | bash && foundryup
• Slither + solc: pip install slither-analyzer e solc-select install <ver> && solc-select use <ver>
• Aderyn (recomendado): cargo install aderyn (ou npm i -g @cyfrin/aderyn)
• Mythril (opcional, execução simbólica lenta): pip install mythril
• gitleaks (varredura de vazamento de chaves): veja a skill complementar implementing-secret-scanning-with-gitleaks
• Um projeto Foundry que compila (forge build bem-sucedido) — os analisadores precisam dos artefatos de build.
• Solidity ^0.8.x é assumido (verificações de estouro embutidas); contratos pré-0.8 precisam de revisão extra com SafeMath.

Instale as ferramentas Python em um virtualenv (recomendado em distros gerenciadas externamente). Nunca execute análises contra código fonte de contrato não confiável em uma máquina com carteiras desbloqueadas com fundos.

Passos

Passo 1: Compilar e verificar a integridade do projeto

forge build                    # analisadores exigem artefatos novos
forge fmt --check              # verificação de estilo (opcional)
cat foundry.toml               # observe versão do solc, otimizador, remapeamentos, evm_version

Passo 2: Análise estática (rápida, execute sempre)

# Slither — projeto completo (usa foundry.toml + remapeamentos automaticamente)
slither . --json slither-report.json

# Aderyn — analisador Cyfrin Rust, detectores complementares
aderyn . -o aderyn-report.json

Ou execute o orquestrador incluído que executa ambos, deduplica e bloqueia o resultado:

python3 scripts/agent.py --project . --output audit-report.json

Passo 3: Execução simbólica em contratos críticos (opcional, lento)

# Apenas no(s) contrato(s) de maior valor — Mythril é explosivo de caminhos
myth analyze src/Vault.sol --solc-json mythril.config.json --execution-timeout 300 -o json
# ou: python3 scripts/agent.py --project . --mythril src/Vault.sol

Passo 4: Testes baseados em propriedades — fuzz + invariantes

forge test -vvv                                  # testes unitários + fuzz
forge coverage --report summary                  # cobertura de código que movimenta valor
forge test --match-test invariant_ -vvv          # suite de invariantes (baseado em handler)

Todo contrato que movimenta valor deve ter testes de invariantes com um handler (entradas limitadas, variáveis fantasma, targetContract(handler)) — não apenas testes unitários. Veja references/api-reference.md para o padrão de handler, e escreva um test_RevertWhen_* (com vm.expectRevert) para cada guarda de controle de acesso.

Passo 5: Revisão manual contra a checklist

Percorra references/vulnerability-checklist.md para cada contrato: reentrância (checks-effects-interactions / nonReentrant), controle de acesso, manipulação de oráculo, delegatecall/layout de armazenamento de proxy, valores de retorno não verificados, tx.origin, aleatoriedade fraca, DoS, front-running/MEV e armadilhas específicas de ERC (corrida de aprovação, fee-on-transfer, rebasing).

Passo 6: Higiene de chaves e implantação segura

gitleaks detect --no-banner            # sem chaves privadas / mnemônicos / .env no commit
git ls-files | grep -E '\.env$|keystore' && echo "AVISO: segredos rastreados pelo git"

# Importe a chave de deploy UMA VEZ em um keystore criptografado — nunca uma variável PRIVATE_KEY em texto simples
cast wallet import deployer --interactive

# Faça o deploy através da conta do keystore (testnet primeiro), simule antes de --broadcast
forge script script/Deploy.s.sol --account deployer --rpc-url <testnet> --broadcast --verify

Veja references/secure-deployment-and-keys.md para as regras completas de hardening (higiene do MetaMask, hardware wallet para mainnet, confiança no RPC, verificação pós-implantação).

Passo 7: Triagem e relatório

Combine os resultados de Slither + Aderyn + Mythril + testes, deduplique por (arquivo, linha), descarte falsos positivos confirmados, classifique por explorabilidade × impacto financeiro e mapeie cada um para seu SWC ID. O orquestrador gera audit-report.json com uma porta PASS/FAIL.

Saída Esperada

Um relatório de auditoria JSON listando descobertas com identificadores SWC, gravidade, ferramenta de origem, contrato/função/linha afetados e remediação; além do resumo de testes/cobertura e uma única porta de deploy PASS / FAIL. FAIL em qualquer descoberta estática de alta/crítica, teste falhando, segredo vazado ou cobertura abaixo do limite configurado em código que movimenta valor.