Skip to content

Commit

Permalink
Merge pull request #23 from immunefi-team/readme_updates
Browse files Browse the repository at this point in the history 
Updated readme to reflect forge template changes fixes #22
  • Loading branch information
@janbro
janbro authored Sep 27, 2023
2 parents 0d260f6 + 8648e7f commit 789c06c
Showing 1 changed file with 24 additions and 16 deletions.
40 changes: 24 additions & 16 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,19 @@ Foundry is required to use this repository. See: https://book.getfoundry.sh/gett

### 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, create an interface automatically with Foundry's [`cast interface`](https://book.getfoundry.sh/reference/cast/cast-interface) commandline tool, 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. To use the `cast` commands, define the `ETHERSCAN_API_KEY` environment variable, then call cast with either of the following methods:
### 1️⃣ Initialize Forge repository

### a. Download the interface (recommended)
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.
```
forge init --template immunefi-team/forge-poc-templates --branch [template]
```

---
### 2️⃣ Download the contract interfaces

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:

#### a. Download the interface (recommended)
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:

```sh
Expand All @@ -35,7 +45,7 @@ import "./external/interfaces/IExample.sol";
> see also: [ABI to sol](https://gnidan.github.io/abi-to-sol/)

### b. Download the entire source code
#### b. Download the entire source code
Alternatively, you can download the entire source code from Etherscan like block explorers using the following command:
> ##### *🚨 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).
```sh
Expand All @@ -51,18 +61,16 @@ Optionally, append `--chain [chain_name]` to specify a chain other than the Ethe


---
2️⃣ Pick a PoC [template](#template-categories-) 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.
<br>
### 3️⃣ Write the test
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.

---
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.

3️⃣ Once you have completed your attack contract, navigate to the corresponding [test](./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!
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.

### Running a PoC 🚀

To use a template, run the following in the console:
To run a test, use the following command in the console:
```
forge test -vv --match-path test/[test_name]
```
Expand All @@ -75,12 +83,12 @@ forge test -vv --match-path test/[test_name]

## Template Categories 🪲

| Categorisation | Template | Source | Test | Documentation |
| -------------------------- | -------- | ------ | ---- | ------------- |
| Reentrancy | [Template](./src/ReentrancyTemplate.sol) | [Source](./src/reentrancy/Reentrancy.sol) | [Test](./test/Reentrancy.t.sol) | [Readme](./src/reentrancy/README.md) |
| Token Balance Manipulation | [Template](./src/TokenTemplate.sol) | [Source](./src/tokens/Tokens.sol) | [Test](./test/Tokens.t.sol) | [Readme](./src/tokens/README.md) |
| Flash Loan | [Template](./src/FlashLoanTemplate.sol) | [Source](./src/flashloan/FlashLoan.sol) | [Test](./test/FlashLoan.t.sol) | [Readme](./src/flashloan/README.md) |
| Price Manipulation | [Template](./src/PriceManipulationTemplate.sol) | [Source](./src/pricemanipulation/PriceManipulation.sol) | [Test](./test/PriceManipulation.t.sol) | [Readme](./src/pricemanipulation/README.md) |
| Categorisation | Branch | Source | Documentation |
| -------------------------- | -------- | ------ | ------------- |
| Default | [default](https://github.com/immunefi-team/forge-poc-templates/tree/default) | | |
| Reentrancy | [reentrancy](https://github.com/immunefi-team/forge-poc-templates/tree/reentrancy) | [Source](./src/reentrancy/Reentrancy.sol) | [Readme](./src/reentrancy/README.md) |
| 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) |
| 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) |
<!-- | Forking | [Template](./src/ForkingTemplate.sol) | [Source](./src/Forking.sol) | [Test](./test/Forking.t.sol) |
| NFTX Loan | [Template](./src/NFTXLoanTemplate.sol) | [Source](./src/NFTXLoan.sol) | [Test](./test/NFTXLoan.t.sol) |
| Uninitialized Proxy | [Template](./src/UninitializedProxyTemplate.sol) | [Source](./src/UninitializedProxy.sol) | [Test](./test/UninitializedProxy.t.sol) | -->
Expand Down

0 comments on commit 789c06c

Please sign in to comment.