Home

Awesome

<a href="https://immunefi.com"><img src="https://github.com/immunefi-team/forge-poc-templates/blob/assets/imgs/Logo_white@3x.png"/></a>

GitHub issues Foundry LGPLv3 license

Immunefi Discord Twitter Medium YouTube

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 📖

  1. 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]
    
  2. 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
    
  3. 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:

CategorizationBranchSourceDocumentation
Defaultdefault
ReentrancyreentrancySourceReadme
Flash Loanflash_loanSourceReadme
Price Manipulationprice_manipulationSourceReadme
Boilerplate MocksmocksSourceReadme
Oracle MocksoraclesSourceReadme
Sandwich Attackssandwich

Foundry Concepts

Refer to Foundry for comprehensive understanding.

Community PoCs ✨

Explore PoCs contributed by our community members:

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! 🙌