immunefi-team/forge-poc-templates

Overview

Welcome to the Immunefi PoC Templates repository! Here, you'll find reusable and easily modifiable Proof of Concept (PoC) examples for various Ethereum Virtual Machine (EVM) based vulnerabilities. Clone the branch corresponding to the chosen attack template. The aim is to enhance bug reporting quality and provide whitehat hackers with efficient tools to create PoCs and validate their findings quickly. These templates are intended for testing proof of concepts in local forks for submission to bug bounty programs. Any other use is explicitly prohibited.

Installation

To utilize this repository, you need to have Foundry installed. Check out the installation guide for Foundry.

Getting Started 📖

Initialize Forge Repository: Start by initializing a forge repository with the desired attack template. Use the command below, replacing [template] with the chosen template from the Template Categories:
```
forge init --template immunefi-team/forge-poc-templates --branch [template]
```
Download Contract Interfaces: Obtain contract interfaces either by creating your own or using Foundry's tools:
- Create Interface Automatically: Use Foundry's cast interface commandline tool to automatically generate interfaces based on contract ABIs.
```
cast interface [address] -o src/external/interfaces/IExample.sol -n IExample
```
- Download Entire Source Code: Alternatively, download entire contract source codes using cast etherscan-source command line tool.
```
cast etherscan-source [address] -d src/external
```
Write the Test: Import your attack contract into PoCTest.sol and modify the setUp() function to replicate necessary attack preconditions. Execute the attack in the testAttack() function.

The test should extend the PoC contract, which introduces functionality to automatically snapshot and print account balances before and after a test.

Use the modifier snapshot(address account, IERC20[] tokens) on the test* function to automatically print information such as pre-attack balances, post-attack balances, and profit. Passing a token with address(0x0) corresponds to the native token of the chain.

Running a PoC 🚀

To run a test, execute the following command in the console:

forge test -vv --match-path test/[test_name]

Template Categories 🪲

Explore various vulnerability categories along with their respective branches, source codes, and documentation in the table below:

Categorization	Branch	Source	Documentation
Default	default
Reentrancy	reentrancy	Source	Readme
Flash Loan	flash_loan	Source	Readme
Price Manipulation	price_manipulation	Source	Readme
Boilerplate Mocks	mocks	Source	Readme
Oracle Mocks	oracles	Source	Readme
Sandwich Attacks	sandwich

Foundry Concepts

Refer to Foundry for comprehensive understanding.

Community PoCs ✨

Explore PoCs contributed by our community members:

Hundred Finance Hack by @hephyrius
Omni Protocol Hack by @realgmhacker
Euler Exploit PoC by @iphelix
DFX Finance Bugfix Review by @unsafe_call

Contribute

We sincerely appreciate contributions to Immunefi's templates. Please review the contribution guidelines and code of conduct to ensure your contributions are merged as soon as possible.

Contributors

Showcasing the contributors behind this project:

Need Assistance?

For any queries or concerns, please don't hesitate to raise them at our GitHub issues.

Finally, if you're eager to collaborate and searching for beginner-friendly tasks, explore the issues labeled as "Good first issue".

Thank you for your time and contributions! 🙌

immunefi-team / forge-poc-templates