dannydoodlesstory/evm-audit-helpersColeção de trechos Solidity e scripts Foundry para auditorias de segurança de contratos inteligentes
evm-audit-helpers é uma coleção curada de trechos Solidity, scripts Foundry e modelos de teste projetados para acelerar auditorias de segurança de contratos inteligentes EVM. O repositório agrupa blocos de construção reutilizáveis para preocupações comuns de auditoria, como reentrância, incompatibilidades de layout de armazenamento e armadilhas de otimização de gás, permitindo que auditores e desenvolvedores se concentrem na lógica em vez de código repetitivo.
Objetivos principais:
| Categoria | Descrição | Arquivos Principais |
|---|---|---|
| Verificadores de Reentrância | Modificadores auxiliares, padrões nonReentrant e scripts de detecção em tempo de execução. | src/helpers/Reentrancy.sol, scripts/reentrancy_check.sol |
| Analisador de Layout de Armazenamento | Utilitários para comparar slots de armazenamento, gerar diagramas de layout e detectar upgrades inseguros. | src/helpers/StorageLayout.sol, scripts/storage_analyzer.sol |
| Modelos de Teste Foundry | Suítes de teste padrão cobrindo vulnerabilidades comuns (controle de acesso, aritmética, delegatecall, etc.). | test/templates/* |
| Auditorias de Gás e Opcodes | Scripts para analisar o uso de gás e sinalizar opcodes caros. | scripts/gas_profiler.sol |
| Auxiliares de Relatórios | Geradores de relatórios JSON/Markdown que podem ser integrados a dashboards de CI. | scripts/report_generator.sol |
| Integração CI | Exemplo de workflow GitHub Actions para execução automatizada de auditorias. | .github/workflows/ci.yml |
Todos os auxiliares são escritos para Solidity ^0.8.20 e são compatíveis com Foundry (forge, cast).
# 1️⃣ Clone o repositório
git clone https://github.com/your-org/evm-audit-helpers.git
cd evm-audit-helpers
# 2️⃣ Instale o Foundry (se ainda não estiver instalado)
curl -L https://foundry.paradigm.xyz | bash
foundryup
# 3️⃣ Instale as dependências
forge install
# 4️⃣ Execute a suíte de testes padrão (inclui verificações de reentrância, armazenamento e gás)
forge test
Dica: Adicione
export FOUNDRY_PROFILE=ciao seu shell para usar as configurações do compilador otimizadas para CI.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import "evm-audit-helpers/src/helpers/Reentrancy.sol";
contract MyVault is ReentrancyGuard {
mapping(address => uint256) private balances;
function deposit() external payable nonReentrant {
balances[msg.sender] += msg.value;
}
function withdraw(uint256 amount) external nonReentrant {
require(balances[msg.sender] >= amount, "Insufficient");
balances[msg.sender] -= amount;
(bool ok,) = msg.sender.call{value: amount}("");
require(ok, "Transfer failed");
}
}
Execute o detector em tempo de execução em um contrato compilado:
forge script scripts/reentrancy_check.sol:ReentrancyChecker --rpc-url $RPC_URL --broadcast
# Gere uma descrição JSON do layout de armazenamento de um contrato compilado
cast abi-storage --contract MyUpgradeable.sol:MyUpgradeable > storage.json
# Compare com um layout de referência (ex.: de uma versão anterior)
forge script scripts/storage_analyzer.sol:StorageComparator \
--sig "compare(string memory, string memory)" storage.json reference.json
O script exibirá slots incompatíveis, possível shadowing e sugestões para anotações @custom:oz-upgrades-unsafe-allow.
Copie um modelo para o seu repositório de auditoria:
cp -r test/templates/reentrancy/ my-audit/tests/
Edite MyContract.t.sol para importar o contrato sob auditoria e execute:
forge test --match-contract MyContract
Adicione o workflow fornecido ao seu repositório:
# .github/workflows/audit.yml
name: EVM Audit
on:
push:
branches: [main]
pull_request:
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Foundry
run: curl -L https://foundry.paradigm.xyz | bash && foundryup
- name: Run Audit Suite
run: |
forge install
forge test -vv
forge script scripts/reentrancy_check.sol:ReentrancyChecker --rpc-url ${{ secrets.RPC_URL }}
forge script scripts/storage_analyzer.sol:StorageComparator --sig "compare(string,string)" storage.json reference.json
O workflow sinalizará automaticamente falhas e publicará um relatório markdown como comentário no PR.
Aceitamos contribuições! Siga estes passos:
git checkout -b feat/<nome>).forge coverage).npm run lint – usa solhint e prettier).pragma solidity ^0.8.20;snake_case para funções internas, camelCase para públicas/externas.///).# Instale as ferramentas de linting
npm install
# Execute o solhint
npx solhint 'src/**/*.sol' 'test/**/*.sol'
# Formatação automática
npx prettier --write '**/*.sol'
evm-audit-helpers é licenciado sob a Licença MIT. Consulte o arquivo LICENSE para obter detalhes.
Boas auditorias!