O cenário da segurança em Finanças Descentralizadas (DeFi) é complexo e dinâmico. Ataques que antes eram considerados "simples" deram lugar a métodos "ultra-modernos" que utilizam técnicas avançadas para manipular protocolos, frequentemente capitalizando na velocidade e no poder de capital dos Flash Loans combinados com a execução atômica de lógica on-chain sofisticada.
Este toolkit, denominado "DeFi Blacksmith" (Ferreiro DeFi), é uma demonstração conceitual e educacional de como tais ataques sofisticados podem ser estruturados e executados. Ele personifica os aspectos "brutais" pelo seu potencial de causar danos massivos ao manipular capital e estado de contrato rapidamente, e "ultra-modernos/sofisticados" pela sua arquitetura modular, controle off-chain avançado e execução on-chain otimizada e adaptativa.
O objetivo deste projeto é permitir que pesquisadores de segurança, desenvolvedores e entusiastas aprendam sobre as táticas e ferramentas usadas em exploits complexos de DeFi, a fim de melhor defender e construir sistemas mais seguros.
A essência deste toolkit reside na combinação de:
- Capital Massivo sob Demanda: Utilizando Flash Loans de protocolos como Aave V3 para obter quantidades enormes de tokens sem garantia inicial.
- Execução Atômica: Realizando toda a sequência de ataque (obter Flash Loan -> executar exploit -> pagar Flash Loan -> coletar lucro) dentro de uma única transação on-chain. Se qualquer passo falhar, a transação inteira reverte, deixando o estado inicial inalterado (exceto pelo gás gasto). Isso minimiza a janela de reação para defesa e observadores.
- Orquestração On-Chain: Utilizando um contrato inteligente (o Orquestrador) como ponto de entrada do Flash Loan e motor de disparo da lógica de exploit.
- Módulos de Exploit Especializados: Separando a lógica específica da vulnerabilidade (reentrância, overflow, etc.) em contratos modulares que são chamados pelo Orquestrador. Isso torna o toolkit flexível e reutilizável para diferentes tipos de falhas.
- Coreografia Controlada por Dados: A lógica exata do ataque on-chain (qual função chamar, com quais parâmetros, em qual contrato, em que ordem, sob quais condições) é definida por estruturas de dados complexas configuradas off-chain e passadas para os contratos on-chain.
- Otimização Extrema: Utilizando Assembly inline em partes críticas do código on-chain para minimizar o consumo de gás e maximizar o número de operações que podem ser executadas dentro do limite de gás de um bloco, tornando a execução mais "brutalmente" eficiente.
- Telemetria Detalhada: Emitindo eventos ricos durante a execução on-chain para permitir que o script off-chain monitore o progresso, depure falhas e confirme o sucesso.
O toolkit é dividido em componentes off-chain (scripts Python) e on-chain (contratos Solidity), trabalhando em conjunto para planejar, preparar e executar o ataque atômico:
graph TD
A[Hacker / Pesquisador] --> B(scripts/scan_protocol.py);
B --> C{Análise de Vulnerabilidade / Eng. Reversa};
C --> D(scripts/prepare_exploit.py);
D --> E{Configuração do Ataque<br/>(configs/ & Payload On-Chain)};
E --> F(scripts/execute_attack.py v3);
F --> G{Interação com RPC/Mempool<br/>(tools/utils/rpc_client.py)};
G --> H[Blockchain / EVM];
H --> I[Contrato Orchestrator<br/>(on-chain)];
I --> J{Flash Loan<br/>(Aave V3)};
J --> I; @*Retorno para Orchestrator (executeOperation)*@
I --> K[Módulo de Exploit<br/>(on-chain - Reentrância/Overflow)];
K --> L[Contrato Alvo<br/>(vulnerável)];
L --> K; @*Triggers (ETH/Token Callbacks)*@
K --> L; @*Chamadas de Exploit (CallStep/ExploitStep)*@
K --> I; @*Sinalização (Eventos)*@
L --> M{Fundos Roubados};
M --> K; @*Coleta Intermediária no Módulo*@
M --> I; @*Coleta Direta no Orchestrator*@
I --> J; @*Pagamento do Flash Loan*@
I --> N{Endereço do Lucro<br/>(Hacker/Mixer)};
subgraph Off-Chain Components
B
D
F
G
end
subgraph On-Chain Components
I
K
L
end
subgraph Data/Config
E
end
subgraph Targets
J
L
M
end
subgraph Profit
N
end
style J fill:#f9f,stroke:#333,stroke-width:2px
style L fill:#f9f,stroke:#333,stroke-width:2px
style M fill:#f9f,stroke:#333,stroke-width:2px
style N fill:#ccf,stroke:#333,stroke-width:2px
style I fill:#ccf,stroke:#333,stroke-width:2px
style K fill:#ccf,stroke:#333,stroke-width:2px
Componentes do Toolkit
Contratos On-Chain (Solidity)
Estes são os smart contracts implantados na blockchain para executar o ataque atômico.
Orchestrator de Flash Loan (Ex: AaveFlashLoanExploitOrchestratorV2.sol)
Papel: O ponto de entrada para o Flash Loan e o maestro inicial da execução on-chain. Interage diretamente com o protocolo de Flash Loan (Aave V3).
Sofisticação V2:
Integração nativa com Aave V3 (IFlashLoanReceiver).
Execução do ataque principal inteiramente dentro da função executeOperation, garantindo a atomicidade.
Recebe instruções complexas (_params) do script off-chain, que incluem o endereço destinatário final do lucro e a coreografia de execução para o(s) módulo(s) de exploit.
Gerencia o recebimento dos fundos do Flash Loan (incluindo desempacotar WETH para ETH, se necessário).
Dispara a execução da coreografia passando dados para o(s) módulo(s) de exploit apropriado(s) via chamadas de baixo nível (.call).
CRÍTICO: Garante o pagamento do Flash Loan (valor emprestado + taxa) ao final da executeOperation.
Roteamento Direto de Lucro: Envia qualquer saldo remanescente (lucro) do módulo de exploit (ou coletado diretamente no orchestrator) diretamente para o endereço destinatário final especificado no _params, dentro da mesma transação atômica. Isso reduz o rastro on-chain em comparação com a coleta em uma transação separada.
Emite eventos detalhados sobre o início, falha (com dados de retorno) e sucesso da execução, incluindo o lucro enviado.
Inclui proteções como onlyOwner e nonReentrant (para proteger o próprio orquestrador, não o alvo).
Módulos de Exploit de Execução (Ex: GenericOverflowUnderflowExploitModule (Maximum Sophistication Level))
Papel: Contêm a lógica específica para explorar um tipo particular de vulnerabilidade (overflow/underflow neste caso). São configurados off-chain e chamados pelo Orchestrator (ou diretamente, em cenários mais simples).
Sofisticação Nível Máximo (Nesta Versão):
Coreografia de Execução Avançada: Utiliza a estrutura ExploitStep (target, value, data, conditionType, conditionValue, conditionTokenOrTarget, conditionOffset, nextStepIndexOffsetIfTrue, nextStepIndexOffsetIfFalse) para definir a sequência de ataque.
Interpretador de Coreografia em Assembly: A função executeExploit (o ponto de entrada para o Orchestrator chamar) contém um loop while com um bloco assembly que atua como um interpretador de bytecode de coreografia. Ele lê a sequência ExploitStep[] do storage e executa a lógica de interpretação e dispatch de chamadas inteiramente dentro do Assembly para máxima eficiência.
Verificação de Estado On-Chain Abrangente: O Assembly dentro do loop pode avaliar condições complexas (ConditionCheckType) antes de executar um passo. Isso inclui checar:
Sucesso/falha da chamada anterior (LastCallSuccessful, LastCallFailed).
Saldo de ETH ou Token deste módulo (EthBalanceGreaterThan, TokenBalanceGreaterThan).
Saldo de ETH ou Token do contrato alvo (TargetEthBalanceGreaterThan, TargetTokenBalanceGreaterThan) - usando staticcall via Assembly.
Valor em uma slot de storage específica do contrato alvo (TargetStorageValueEquals, TargetStorageValueGreaterThan) - usando staticcall via Assembly (assumindo uma view function no alvo ou técnica complexa).
Ramificação e Loops: Com base no resultado da avaliação da condição, o interpretador Assembly calcula o currentSequenceIndex do próximo passo usando os offsets definidos no ExploitStep (nextStepIndexOffsetIfTrue/nextStepIndexOffsetIfFalse). Isso permite saltar passos, criar loops e ramificar o fluxo de execução do exploit com base no estado on-chain, tudo atomicamente.
Otimização de Gás Extrema: O uso extensivo de Assembly para o loop de execução e dispatch de chamadas minimiza o consumo de gás por iteração.
Gerenciamento de Fundos Intermediários (Mecanismo): Inclui a função receiveTokens para permitir que tokens roubados sejam enviados para este módulo durante a execução do exploit (se um passo da coreografia realizar uma transferência para address(this)). A lógica para usar esses fundos em passos subsequentes seria integrada à coreografia ou ao interpretador Assembly.
Telemetria Detalhada: Emite eventos ricos (ExecutingStep, StepExecuted, ConditionCheckFailed, etc.) diretamente do Assembly ou Solidity para fornecer feedback granular sobre o que aconteceu em cada passo da coreografia.
Inclui onlyOwner e nonReentrant para autoproteção.
Módulos de Exploit de Reentrância (Ex: ReentrancyExecutionModule (Maximum Sophistication Level Concepts))
Papel: Similar ao módulo de Overflow/Underflow, mas especializado em explorar vulnerabilidades de reentrância. Sua execução é acionada por callbacks de ETH (receive()) ou token (tokensReceived, etc.), não por uma chamada direta executeExploit.
Sofisticação Nível Máximo (Nesta Versão):
Compartilha a mesma estrutura de Coreografia Avançada (CallStep com condições e offsets) que o módulo de Overflow/Underflow.
O interpretador da coreografia (loop, avaliação de condição, cálculo de próximo índice, dispatch de chamada) reside dentro da função receive() e potencialmente em callbacks de token (ERC777/ERC223), sendo acionado cada vez que ETH/Tokens são recebidos.
Utiliza Assembly para otimizar a execução da chamada (call opcode) dentro do loop de reentrância.
Suporta reentrância via callbacks de token (ERC777/ERC223), adicionando versatilidade para diferentes vetores de ataque reentrante.
Inclui proteções como onlyOwner e nonReentrant (aplicado ao receive() e callbacks de token) para proteger o módulo contra re-entrâncias não intencionais ou ataques ao próprio módulo.
Telemetria detalhada via eventos.
Scripts Off-Chain (Python)
Estes scripts orchestram o processo de ataque do lado do hacker.
scan_protocol.py
Papel: Ferramenta (conceptual neste toolkit) para analisar um contrato alvo, identificar possíveis vulnerabilidades (não automatizado aqui, requer análise humana), extrair ABIs, layouts de storage (se possível) e outras informações relevantes para construir o exploit.
Exemplo de Uso:
bash
Copiar
python3 scripts/scan_protocol.py <endereço_do_contrato>
prepare_exploit.py
Papel: A "inteligência" do ataque. Este script:
Compreende a vulnerabilidade específica encontrada.
Determina a sequência exata de interações necessária para desencadear a vulnerabilidade e capitalizá-la (coreografia do ataque).
Define qual Módulo de Exploit usar (Reentrância, Overflow/Underflow, etc.).
Cria a estrutura de dados complexa (CallStep[] ou ExploitStep[]) que define a coreografia, incluindo alvos, valores, dados de chamada, condições e offsets de ramificação/loop.
Calcula quaisquer valores necessários (quantia de Flash Loan, ETH inicial a ser enviado, etc.).
Codifica (abi.encode) os parâmetros necessários (endereço do lucro, coreografia, etc.) para o Orchestrator de Flash Loan e o Módulo de Exploit.
Gera o arquivo de configuração (.yaml ou .json) que será usado pelo execute_attack.py.
Exemplo de Uso:
bash
Copiar
python3 scripts/prepare_exploit.py --vulnerability overflow --target <endereço_do_contrato_alvo> --output configs/exploit.yaml
execute_attack.py (Versão 3 com Suporte a Orchestrator)
Papel: O ponto de controle principal para executar o ataque.
Lê a configuração de ataque gerada pelo prepare_exploit.py.
Lida com a implantação on-chain do contrato Orchestrator e do(s) Módulo(s) de Exploit (se ainda não estiverem implantados).
Chama a função configureModule no Módulo de Exploit apropriado, passando os dados da coreografia.
Chama a função requestFlashLoan no Orchestrator de Flash Loan, passando o ativo, a quantia e os _params complexos (que contêm o endereço do lucro e as instruções para o Orchestrator chamar o Módulo de Exploit com a coreografia).
Monitora a blockchain para a transação do ataque.
Analisa a receipt da transação e os eventos emitidos pelo Orchestrator e pelo Módulo de Exploit (usando os eventos detalhados) para determinar se o ataque foi bem-sucedido, se houve falhas e qual foi o lucro final.
Pode usar o RPCClient para interagir com a blockchain (enviar transação, ler estado) e potencialmente enviar transações via Mempools Privados ou Serviços de MEV para aumentar a chance de inclusão rápida e evitar front-running por defesas ou outros hackers.
Exemplo de Uso:
bash
Copiar
python3 scripts/execute_attack.py --config configs/exploit.yaml
exfiltrate_funds.py
Papel: Script (conceptual neste toolkit) responsável por mover os fundos roubados da carteira inicial do hacker (o profitRecipient) para locais mais seguros ou difíceis de rastrear (ex: mixers de moedas, pontes cross-chain). Este processo geralmente ocorre após o sucesso da transação de ataque atômico.
Ferramentas Utilitárias
tools/utils/rpc_client.py: Gerencia a conexão com nós blockchain, incluindo opções para enviar transações via RPCs padrão ou serviços de MEV/relays privados.
tools/utils/tx_builder.py: Ajuda a construir transações Ethereum cruas para interações complexas ou de baixo nível.
tools/utils/data_encoder.py: Utilitários para ABI encoding/decoding, hashing de slots de storage, cálculo de seletores de função, essenciais para criar o bytes calldata e as estruturas CallStep/ExploitStep off-chain.
tools/utils/fund_mixer/: Diretório para scripts ou contratos relacionados a misturar ou lavar fundos (conceptual).
Configuração
configs/: Diretório contendo arquivos de configuração (YAML/JSON) que armazenam informações específicas do ataque e do ambiente (endereços de contratos implantados, detalhes da vulnerabilidade, parâmetros do ataque, configurações de RPC). O prepare_exploit.py pode gerar ou usar esses arquivos, e o execute_attack.py os lê.
O Aspecto "Brutal"
A "brutalidade" deste toolkit se manifesta em:
Escala: A capacidade de usar Flash Loans permite ataques com capital que pode ser ordens de magnitude maior do que o disponível na carteira do atacante.
Velocidade Atômica: A execução instantânea da coreografia complexa nega às defesas e aos operadores de protocolo qualquer tempo de reação on-chain durante o ataque.
Corrupção Direta: Os módulos de exploit miram e manipulam diretamente o estado do contrato vulnerável, geralmente resultando em drenagem de fundos ou falha crítica do protocolo.
Eficiência Otimizada: O uso de Assembly minimiza o desperdício de gás, permitindo que o ataque extraia o máximo de valor e execute a coreografia mais longa possível dentro dos limites de gás.
O Aspecto "Ultra-Moderno e Sofisticado"
A sofisticação reside em:
Arquitetura Modular: Separando orquestração, tipos de exploit, configuração e controle off-chain.
Execução Controlada por Dados: A lógica complexa on-chain é definida por dados estruturados off-chain, permitindo flexibilidade sem reimplantar contratos de exploit para cada variação de um ataque.
Coreografia Adaptativa: A capacidade de coreografar chamadas com lógica condicional e ramificações on-chain permite que os ataques se ajustem a estados inesperados ou explorem caminhos diferentes dinamicamente dentro da transação atômica.
Verificação de Estado On-Chain: A capacidade de ler o estado do contrato alvo durante a execução do exploit e usar essa informação para controlar o fluxo é uma técnica de ponta.
Otimização de Baixo Nível: O uso de Assembly para partes críticas do loop de execução demonstra um entendimento profundo da EVM e a busca por eficiência máxima.
Telemetria Avançada: Eventos detalhados fornecem insights sem precedentes sobre a execução atômica complexa, essencial para depuração e análise pós-ataque.
Como Usar (Visão Geral Conceitual)
Configurar Ambiente:
Clone o repositório: git clone <repositório>
Instale as dependências:
bash
Copiar
pip install -r requirements.txt
Configure as conexões RPC na testnet alvo em configs/rpc.yaml.
Crie uma conta de teste com fundos na testnet.
Analisar Protocolo/Vulnerabilidade: Usar scan_protocol.py (se relevante) e análise manual/automatizada para encontrar a vulnerabilidade, entender seu funcionamento, obter ABIs, etc.
Preparar Exploit: Usar prepare_exploit.py para definir a coreografia do ataque (sequência de ExploitStep ou CallStep), a quantia do Flash Loan, o endereço do lucro e outros parâmetros. Este script gerará um arquivo de configuração para o ataque específico.
Implantar Contratos (se necessário): Implantar o Orchestrator e o(s) Módulo(s) de Exploit relevantes na testnet alvo. Atualizar a configuração com os endereços implantados.
Executar Ataque: Rodar execute_attack.py, especificando o arquivo de configuração gerado. O script chamará o Orchestrator com os parâmetros codificados.
Monitorar e Verificar: O execute_attack.py monitorará a transação, analisará a receipt e os eventos para confirmar o sucesso do ataque e o lucro obtido.
Coletar Lucro: Se o ataque for bem-sucedido e o lucro for direcionado para uma carteira controlada, usar a função getBalance do Orchestrator (se o lucro ficou lá) ou verificar o saldo do endereço destinatário final.
Próximos Passos e Expansões (Conceitual)
Este toolkit é um ponto de partida. Futuras expansões poderiam incluir:
Mais Módulos de Exploit: Desenvolver módulos especializados para outros tipos de vulnerabilidades (ex: falhas em oráculos, manipulação de governança, vulnerabilidades de token específicas).
Integração com Múltiplas Fontes de Flash Loan: Modificar o Orchestrator para interagir com Balancer, Uniswap V3, MakerDAO, etc., para aumentar o capital disponível.
Gerenciamento de Fundos Intermediários Integrado: Implementar a lógica no Assembly do módulo para gerenciar e usar tokens/ETH coletados durante a execução (ex: swaps on-chain usando um módulo de swap chamável).
Capacidades Cross-Chain: Explorar e orquestrar ataques que abrangem múltiplas blockchains via pontes ou protocolos cross-chain.
Automação da Análise: Integrar ferramentas de análise estática/dinâmica para identificar vulnerabilidades e auxiliar na geração automatizada da coreografia de exploit.
Contribuindo
Contribuições são bem-vindas! Consulte o arquivo CONTRIBUTING.md para obter mais informações sobre como contribuir para este projeto.
Licença
Este toolkit é fornecido apenas para fins educacionais. Consulte o arquivo LICENSE para obter detalhes.
Conclusão
O "DeFi Blacksmith" é uma demonstração educacional poderosa das táticas "ultra-modernas" e "brutais" empregadas em ataques sofisticados de DeFi. Ao estudar sua arquitetura, a coreografia avançada, a execução otimizada em Assembly e a orquestração off-chain/on-chain, desenvolvedores e pesquisadores podem obter insights valiosos para construir e proteger a próxima geração de protocolos descentralizados.
# Blockchain Security Research Toolkit
This toolkit is designed for security researchers to analyze and test smart contract vulnerabilities ethically. It enables systematic security research workflows including contract analysis, vulnerability detection, and proof-of-concept development.
## WARNING
This toolkit is for ETHICAL SECURITY RESEARCH ONLY. Usage for actual attacks or malicious purposes is illegal and unethical.
## Security Notice
- Keep this toolkit in a secure, encrypted environment
- Never store private keys directly in this toolkit's files
- Use isolated test environments for all operations
- Responsible disclosure is the right approach for any vulnerabilities found
## Directory Structure
- `/targets/` - For organizing intelligence about contracts under analysis
- `/exploits/` - Templates for common vulnerability exploits
- `/templates/` - Base code for quickly developing new exploits
- `/tools/` - Automated utilities for scanning and blockchain interaction
- `/data/` - Raw data storage from scans and analysis
- `/configs/` - Configuration files for all toolkit components
- `/scripts/` - High-level scripts that orchestrate the workflow
## Getting Started
1. Setup your environment: `python3 scripts/setup.py`
2. Configure RPC endpoints in `configs/rpc.yaml`
3. Start analyzing a contract: `python3 scripts/scan_contract.py <contract_address>`
4. See individual component READMEs for detailed usage guidance
## Ethical Guidelines
As a security researcher using this toolkit, you should:
1. Always obtain proper authorization before testing any contract
2. Report vulnerabilities to the project owners through secure channels
3. Provide reasonable time for fixes before public disclosure
4. Never exploit vulnerabilities for personal gain
5. Document your findings thoroughly for educational purposes
## License
This toolkit is provided for educational purposes only. See LICENSE file for details.
hacker_toolkit/
├── data/
│ └── README.md # Documentação ou descrição sobre os dados armazenados (que podem ser informações sobre alvos, resultados de scans, etc.)
├── configs/
│ ├── rpc.yaml # Configurações relacionadas a endpoints RPC (URLs de nós da blockchain, chaves, etc.)
│ ├── scanner.yaml # Configurações para as ferramentas de scanner (parâmetros de varredura, alvos, tipos de análise)
│ └── exploit.yaml # Configurações gerais para a execução de exploits (parâmetros padrão, alvos, etc.)
├── targets/
│ └── example_target/ # Diretório para informações específicas de um alvo de exemplo
│ ├── addresses.json # Arquivo JSON contendo endereços de contratos relevantes para o alvo de exemplo
│ └── notes.md # Notas em Markdown sobre o alvo de exemplo (descrição, vulnerabilidades conhecidas, etc.)
├── exploits/ # Diretório contendo os contratos de exploit e templates
│ ├── README.md # Documentação sobre os exploits ou como adicionar novos
│ ├── reentrancy/ # Diretório para exploits específicos de reentrância
│ │ └── generic_reentrancy.sol # Contrato Solidity para um exploit de reentrância genérico (como o que discutimos)
│ ├── overflow_underflow/ # Diretório para exploits específicos de overflow/underflow
│ │ └── generic_overflow.sol # Contrato Solidity para um exploit de overflow/underflow genérico
│ ├── flash_loan/ # Diretório para exploits relacionados a Flash Loans
│ │ └── aave_flash_loan.sol # Contrato Solidity de exemplo usando Flash Loan da Aave (ou um mock)
│ └── templates/ # Diretório para templates base de contratos
│ ├── base_exploit.sol # Contrato Solidity base para outros exploits (pode conter modificadores, funções utilitárias comuns)
│ └── erc20_interface.sol # Interface Solidity para o padrão ERC20 (usada pelos exploits para interagir com tokens)
├── tools/ # Diretório contendo ferramentas auxiliares
│ ├── scanners/ # Ferramentas de scanner (análise de código/bytecode)
│ │ ├── static_scanner.py # Script Python para análise estática de contratos (sem executar)
│ │ ├── dynamic_scanner.py # Script Python para análise dinâmica de contratos (executando em testnet/simulador)
│ │ └── custom_checks/ # Diretório para checks de scanner customizados
│ │ ├── README.md # Documentação sobre como adicionar checks customizados
│ │ └── reentrancy_check.py # Script Python com a lógica para detectar vulnerabilidades de reentrância no scanner
│ ├── utils/ # Utilitários diversos
│ │ ├── rpc_client.py # Cliente RPC em Python para interagir com nós da blockchain
│ │ ├── tx_builder.py # Utilitário Python para construir e assinar transações
│ │ ├── data_encoder.py # Utilitário Python para codificar/decodificar dados (como abi.encodeWithSignature)
│ │ └── monitoring/ # Utilitários para monitoramento
│ │ └── tx_watcher.py # Script Python para monitorar transações na blockchain
├── scripts/ # Scripts para orquestrar o fluxo de trabalho
│ ├── setup.py # Script para configurar o ambiente ou um novo alvo
│ ├── scan_contract.py # Script para executar as ferramentas de scanner em um contrato alvo
│ ├── prepare_exploit.py # Script para preparar os parâmetros de um exploit (gerar calldata, configurar módulos, etc.)
│ └── execute_attack.py # Script principal para executar o ataque (chamar o orquestrador, etc.)
└── Installed web3, eth-abi, eth-account, requests, pyyaml, rich # Lista de dependências Python instaladas