Skip to content

Latest commit

 

History

History
84 lines (57 loc) · 6.4 KB

README.md

File metadata and controls

84 lines (57 loc) · 6.4 KB
Raw

GitHub issues LGPLv3 license

Immunefi Discord Twitter Medium YouTube

This is a collaborative repository that aims to provide reusable and easily modifiable PoC examples for a variety of EVM based vulnerabilities. This will increase the quality of bug reports and allow whitehats an easier, faster way to create PoCs and verify their claims. These templates are intended for testing proof of concepts in local forks for submission to bug bounty programs. Any other use is explicitly prohibited.

Overview

Installation

Foundry is required to use this repository. See: https://book.getfoundry.sh/getting-started/installation.

Getting Started 📖

1️⃣ First, set up the interfaces for the protocol you will be creating a PoC for. You can create your own interface contracts, or download the contracts for the protocol using Foundry's cast etherscan-source command line tool. Define the ETHERSCAN_API_KEY environment variable, then call

cast etherscan-source [address] -d src/external

This will download the contracts' source code to src/external, where you can simply import any contract interfaces by adding the following to the top of your PoC.

*🚨 When downloading source code from deployed contracts, there may be remappings that need to be modified for the source files to compile. Add any necessary remappings to remappings.txt.
import "./external/ExampleProtocol/ExampleEtherscanContract.sol"

Optionally, append --chain [chain_name] to specify a chain other than the Ethereum mainnet to download contracts from. Note: you will have to update your Etherscan API key when switching between different chains.

2️⃣ Pick a PoC template and modify the template file which extends* from the corresponding source contract. Within the template contract, there will be comments describing how you can modify the PoC to fit your vulnerability.

*🚨 When extending from an abstract contract, there will be functions which must be defined. Implement any undefined functions with your attack.

3️⃣ Once you have completed your attack contract, navigate to the corresponding test file, import your attack contract, and modify the setUp() to replicate any necessary attack preconditions, such as forking from a network, initializing accounts with certain balances, or creating any other conditions which are necessary for the attack. Try to keep your setup as close to mainnet state as possible. The more the setup differs from the mainnet state, the harder it is for projects to verify your claims. Now, you're ready to run your PoC!

Running a PoC 🚀

To use a template, run the following in the console:

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

Environment Variables

Variable Example
ETHERSCAN_API_KEY [API_KEY]

Template Categories 🪲

Categorisation Template Source Test Documentation
Reentrancy Template Source Test Readme
Token Balance Manipulation Template Source Test Readme
Flash Loan Template Source Test Readme
Price Manipulation Template Source Test Readme

Foundry Concepts

PoCs from our community ✨

Contribute 📝

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

All set!

If you have any questions, feel free to post them to https://github.com/immunefi-team/forge-poc-templates/issues.

Finally, if you're looking to collaborate and want to find easy tasks to start, look at the issues we marked as "Good first issue".

Thanks for your time and code!