Skip to content

Commit ef9b140

Browse files
janbrojanbro
committed
Readme overhaul
1 parent 5d05466 commit ef9b140

File tree

1 file changed

+61
-87
lines changed

1 file changed

+61
-87
lines changed

‎README.md

+61-87
Original file line numberDiff line numberDiff line change
@@ -1,131 +1,105 @@
11
<a href="https://immunefi.com"><img src="https://github.com/immunefi-team/forge-poc-templates/blob/assets/imgs/Logo_white@3x.png"/></a>
22

3+
34
[![GitHub issues](https://img.shields.io/github/issues/immunefi-team/forge-poc-templates.svg)](https://GitHub.com/immunefi-team/forge-poc-templates/issues/)
5+
[![Foundry][foundry-badge]][foundry]
46
[![LGPLv3 license](https://img.shields.io/badge/License-LGPLv3-blue.svg)](./LICENSE)
57

68
[![Immunefi Discord](https://badgen.net/discord/online-members/immunefi)](https://discord.gg/immunefi)
79
[![Twitter](https://badgen.net/badge/icon/twitter?icon=twitter&label)](https://twitter.com/immunefi)
810
[![Medium](https://badgen.net/badge/icon/medium?icon=medium&label)](https://medium.com/immunefi)
911
[![YouTube](https://badgen.net/badge/icon/YouTube?icon=googleplay&label)](https://www.youtube.com/channel/UCmulw2BHpP6IiBM0Re0yP5Q)
1012

11-
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.
12-
1313
## Overview
1414

15-
### Installation
16-
17-
Foundry is required to use this repository. See: https://book.getfoundry.sh/getting-started/installation.
18-
19-
### Getting Started 📖
20-
21-
### 1️⃣ Initialize Forge repository
22-
23-
First, initialize a forge repository with the attack template you would like to use. Passing `default` as the branch will initialize a minimal forge repository with the correct dependencies installed. See the [template categories](#template-categories-) below for a list of templates which can be chosen.
24-
```
25-
forge init --template immunefi-team/forge-poc-templates --branch [template]
26-
```
27-
28-
---
29-
### 2️⃣ Download the contract interfaces
30-
31-
You can create your own interface contracts, create an interface automatically with Foundry's [`cast interface`](https://book.getfoundry.sh/reference/cast/cast-interface) commandline tool (a), or download the full source code for contracts for the protocol using Foundry's [`cast etherscan-source`](https://book.getfoundry.sh/reference/cast/cast-etherscan-source) command line tool (b). To use the `cast` commands, define the `ETHERSCAN_API_KEY` environment variable, then call cast with either of the following methods:
15+
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](#template-categories). 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.
3216

33-
#### a. Download the interface (recommended)
34-
Rather than copying the entire smart contract code itself, you can use the Interface feature introduced in Solidity version 0.6.x to define which functions a contract implements. To do so automatically, run the following command in the console:
17+
## Installation
3518

36-
```sh
37-
cast interface [address] -o src/external/interfaces/IExample.sol -n IExample
38-
```
19+
To utilize this repository, you need to have Foundry installed. Check out the [installation guide](https://book.getfoundry.sh/getting-started/installation) for Foundry.
3920

40-
Foundry automatically creates the interface based on the externally available functions according to the contracts ABI. Then import the newly created interface contract in your PoC:
21+
## Getting Started 📖
4122

42-
```js
43-
import "./external/interfaces/IExample.sol";
44-
```
45-
> see also: [ABI to sol](https://gnidan.github.io/abi-to-sol/)
23+
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](#template-categories):
24+
```
25+
forge init --template immunefi-team/forge-poc-templates --branch [template]
26+
```
4627
28+
2. **Download Contract Interfaces**: Obtain contract interfaces either by creating your own or using Foundry's tools:
29+
- **Create Interface Automatically**: Use Foundry's `cast interface` commandline tool to automatically generate interfaces based on contract ABIs.
4730
48-
#### b. Download the entire source code
49-
Alternatively, you can download the entire source code from Etherscan like block explorers using the following command:
50-
> ##### *🚨 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`](./remappings.txt).
51-
```sh
52-
cast etherscan-source [address] -d src/external
53-
```
54-
55-
This will download the contracts' entire source code to `src/external`, where you can import any contract interfaces by adding the following to the top of your PoC:
56-
```js
57-
import "./external/ExampleProtocol/ExampleEtherscanContract.sol";
58-
```
59-
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.
60-
<br>
31+
```
32+
cast interface [address] -o src/external/interfaces/IExample.sol -n IExample
33+
```
6134
35+
- **Download Entire Source Code**: Alternatively, download entire contract source codes using `cast etherscan-source` command line tool.
6236
63-
---
64-
### 3️⃣ Write the test
65-
Once you have created your attack contract, import your attack contract into the PoCTest.sol, 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.
37+
```
38+
cast etherscan-source [address] -d src/external
39+
```
6640
67-
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. Execute the attack in the `testAttack()` function.
41+
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.
6842
69-
The test should extend the [PoC](./src/PoC.sol) 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.
43+
The test should extend the `PoC` contract, which introduces functionality to automatically snapshot and print account balances before and after a test.
44+
45+
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.
7046
71-
### Running a PoC 🚀
47+
## Running a PoC 🚀
7248
73-
To run a test, use the following command in the console:
49+
To run a test, execute the following command in the console:
7450
```
7551
forge test -vv --match-path test/[test_name]
7652
```
7753
78-
### Environment Variables
79-
80-
| Variable | Example |
81-
| ----------------- | ---------------------------------------------- |
82-
| ETHERSCAN_API_KEY | [API_KEY] |
83-
8454
## Template Categories 🪲
8555
86-
| Categorisation | Branch | Source | Documentation |
87-
| -------------------------- | -------- | ------ | ------------- |
88-
| Default | [default](https://github.com/immunefi-team/forge-poc-templates/tree/default) | | |
89-
| Reentrancy | [reentrancy](https://github.com/immunefi-team/forge-poc-templates/tree/reentrancy) | [Source](./src/reentrancy/Reentrancy.sol) | [Readme](./src/reentrancy/README.md) |
90-
| Flash Loan | [flash_loan](https://github.com/immunefi-team/forge-poc-templates/tree/flash_loan) | [Source](./src/flashloan/FlashLoan.sol) | [Readme](./src/flashloan/README.md) |
91-
| Price Manipulation | [price_manipulation](https://github.com/immunefi-team/forge-poc-templates/tree/price_manipulation) | [Source](./src/pricemanipulation/PriceManipulation.sol) | [Readme](./src/pricemanipulation/README.md) |
92-
| Boilerplate Mocks | [mocks](./src/mocks/) | [Source](./src/mocks/) | [Readme](./src/mocks/README.md) |
93-
| Oracle Mocks | [oracles](./src/oracle/) | [Source](./src/oracle/) | [Readme](./src/oracle/README.md) |
94-
<!-- | Forking | [Template](./src/ForkingTemplate.sol) | [Source](./src/Forking.sol) | [Test](./test/Forking.t.sol) |
95-
| NFTX Loan | [Template](./src/NFTXLoanTemplate.sol) | [Source](./src/NFTXLoan.sol) | [Test](./test/NFTXLoan.t.sol) |
96-
| Uninitialized Proxy | [Template](./src/UninitializedProxyTemplate.sol) | [Source](./src/UninitializedProxy.sol) | [Test](./test/UninitializedProxy.t.sol) | -->
56+
Explore various vulnerability categories along with their respective branches, source codes, and documentation in the table below:
57+
58+
| Categorization | Branch | Source | Documentation |
59+
| -------------- | ------ | ------ | ------------- |
60+
| Default | [default](https://github.com/immunefi-team/forge-poc-templates/tree/default) | | |
61+
| Reentrancy | [reentrancy](https://github.com/immunefi-team/forge-poc-templates/tree/reentrancy) | [Source](./src/reentrancy/Reentrancy.sol) | [Readme](./src/reentrancy/README.md) |
62+
| Flash Loan | [flash_loan](https://github.com/immunefi-team/forge-poc-templates/tree/flash_loan) | [Source](./src/flashloan/FlashLoan.sol) | [Readme](./src/flashloan/README.md) |
63+
| Price Manipulation | [price_manipulation](https://github.com/immunefi-team/forge-poc-templates/tree/price_manipulation) | [Source](./src/pricemanipulation/PriceManipulation.sol) | [Readme](./src/pricemanipulation/README.md) |
64+
| Boilerplate Mocks | [mocks](./src/mocks/) | [Source](./src/mocks/) | [Readme](./src/mocks/README.md) |
65+
| Oracle Mocks | [oracles](./src/oracle/) | [Source](./src/oracle/) | [Readme](./src/oracle/README.md) |
66+
| Sandwich Attacks | [sandwich](https://github.com/immunefi-team/forge-poc-templates/tree/sandwich) | | |
9767
9868
## Foundry Concepts
9969
100-
- [Foundry](https://book.getfoundry.sh/)
70+
Refer to [Foundry](https://book.getfoundry.sh/) for comprehensive understanding.
10171
102-
## PoCs from our community ✨
72+
## Community PoCs ✨
10373
104-
- [Hundred Finance Hack](https://medium.com/immunefi/a-poc-of-the-hundred-finance-heist-4121f23a098) by [@hephyrius](https://twitter.com/hephyrius)
105-
- [Omni Protocol Hack](https://medium.com/immunefi/hack-analysis-omni-protocol-july-2022-2d35091a0109) by [@realgmhacker](https://twitter.com/realgmhacker)
106-
- [Euler Exploit PoC](https://github.com/iphelix/euler-exploit-poc) by [@iphelix](https://twitter.com/_iphelix)
107-
- [DFX Finance Bugfix Review](./pocs/DFXFinanceBugfixReview.sol) by [@unsafe_call](https://twitter.com/unsafe_call)
74+
Explore PoCs contributed by our community members:
10875
109-
## Contribute 📝
76+
- [Hundred Finance Hack](https://medium.com/immunefi/a-poc-of-the-hundred-finance-heist-4121f23a098) by [@hephyrius](https://twitter.com/hephyrius)
77+
- [Omni Protocol Hack](https://medium.com/immunefi/hack-analysis-omni-protocol-july-2022-2d35091a0109) by [@realgmhacker](https://twitter.com/realgmhacker)
78+
- [Euler Exploit PoC](https://github.com/iphelix/euler-exploit-poc) by [@iphelix](https://twitter.com/_iphelix)
79+
- [DFX Finance Bugfix Review](./pocs/DFXFinanceBugfixReview.sol) by [@unsafe_call](https://twitter.com/unsafe_call)
11080
111-
We sincerely appreciate contributions to Immunefi's templates. Please take the time to review the [contribution guidelines](.github/CONTRIBUTING.md) and [code of conduct](.github/CODE_OF_CONDUCT.md) to ensure your contributions are merged as soon as possible.
81+
## Contribute
82+
83+
We sincerely appreciate contributions to Immunefi's templates. Please review the [contribution guidelines](.github/CONTRIBUTING.md) and [code of conduct](.github/CODE_OF_CONDUCT.md) to ensure your contributions are merged as soon as possible.
11284
11385
## Contributors
114-
* [@unsafe_call](https://twitter.com/unsafe_call)
115-
* [@Omikomikomik](https://twitter.com/omikomikomik)
116-
* [@ArbazKiraak](https://twitter.com/ArbazKiraak)
117-
* [@AdrianHetman](https://twitter.com/adrianhetman)
118-
* [@Pep1nn](https://twitter.com/Pep1nn)
119-
* [@realgmhacker](https://twitter.com/realgmhacker)
120-
* [@_iphelix](https://twitter.com/_iphelix)
121-
* [0xlead](https://github.com/0xlead)
122-
* [@infosec_us_team](https://twitter.com/infosec_us_team)
12386
87+
Showcasing the contributors behind this project:
88+
89+
- [@unsafe_call](https://twitter.com/unsafe_call)
90+
- [@Omikomikomik](https://twitter.com/omikomikomik)
91+
- [@ArbazKiraak](https://twitter.com/ArbazKiraak)
92+
- [@AdrianHetman](https://twitter.com/adrianhetman)
93+
- [@Pep1nn](https://twitter.com/Pep1nn)
94+
- [@realgmhacker](https://twitter.com/realgmhacker)
95+
- [@_iphelix](https://twitter.com/_iphelix)
96+
- [0xlead](https://github.com/0xlead)
97+
- [@infosec_us_team](https://twitter.com/infosec_us_team)
12498
125-
## All set!
99+
## Need Assistance?
126100
127-
If you have any questions, feel free to post them to https://github.com/immunefi-team/forge-poc-templates/issues.
101+
For any queries or concerns, please don't hesitate to raise them at [our GitHub issues](https://github.com/immunefi-team/forge-poc-templates/issues).
128102
129-
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"](https://github.com/immunefi-team/forge-poc-templates/labels/good%20first%20issue).
103+
Finally, if you're eager to collaborate and searching for beginner-friendly tasks, explore the issues labeled as ["Good first issue"](https://github.com/immunefi-team/forge-poc-templates/labels/good%20first%20issue).
130104
131-
Thanks for your time and code!
105+
Thank you for your time and contributions! 🙌

0 commit comments

Comments
 (0)