Skip to content

Commit

Permalink
Merge pull request SunWeb3Sec#591 from akshaynexus/improve-contributi…
Browse files Browse the repository at this point in the history 
…ngmd
  • Loading branch information
@SunWeb3Sec
SunWeb3Sec authored Mar 24, 2024
2 parents 0b984dd + b3be6a1 commit 417916c
Showing 1 changed file with 69 additions and 122 deletions.
191 changes: 69 additions & 122 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,149 +1,96 @@
# Contributing Guidelines

Thank you for your interest in contributing to our project! This guide will walk you through the process of adding a new entry to README using the provided script.
Thank you for your interest in contributing to the DeFiHackLabs project! We appreciate your efforts to help us maintain a comprehensive collection of DeFi hack incidents and their respective proof-of-concept (POC) exploits. This guide will walk you through the process of adding a new incident entry to the project.

## Prerequisites

Before getting started, ensure you have the following:

- Python 3.x installed on your system
- Basic knowledge of using the command line
- toml package installed,use `pip install toml`,this allows the script to read the networks available
- `toml` package installed (run `pip install toml` to install it)

## Steps to Contribute
## Adding a New Incident Entry

1. Clone the repository to your local machine.
To add a new incident entry to the project, follow these steps:

2. Navigate to the project directory in your terminal.
1. Fork the [DeFiHackLabs repository](https://github.com/SunWeb3Sec/DeFiHackLabs) on GitHub.

3. Run the `add_new_entry.py` script by executing the following command:
```
python add_new_entry.py
2. Clone your forked repository to your local machine:
```bash
git clone https://github.com/your-username-here/DeFiHackLabs.git
```

4. The script will prompt you to enter the following information:

- **File Name**: Enter the name of the Exploit POC file in the format `Example_exp.sol`.

- **Timestamp String**:
- Go to the Etherscan explorer (or the equivalent explorer for the relevant chain) and locate the transaction details page for the hack or POC.
- Copy the timestamp from the transaction details page, without including the time zone information, without any quotes.
- Paste the timestamp in the format: `Mar-21-2024 02:51:33 PM`.

- **Lost Amount**: Enter the amount lost in the hack or POC.
3. Navigate to the project directory:
```bash
cd DeFiHackLabs
```

- **Additional Details**: Provide any additional relevant details about the hack or POC.
4. Run the `add_new_entry.py` script:
```bash
python add_new_entry.py
```

5. The script will prompt you to enter the following information:
## Note: do not paste in explorer urls,the script automatically generates them based on the network selected
- **Network**: Enter the index of the network the exploit was on: here is an example screen you will see when running the script
```bash
$ python3 add_new_entry.py
Available networks:
1. mainnet
2. blast
3. optimism
4. fantom
5. arbitrum
6. bsc
7. moonriver
8. gnosis
9. Avalanche
10. polygon
11. celo
12. Base
13. Add a new network
Enter the number corresponding to the network you want to use:
```
- **File Name**: Enter the name of the POC file in the format `IncidentName_exp.sol`.
- **Timestamp String**: Enter the timestamp of the incident in the format `Mar-21-2024 02:51:33 PM`. Make sure to copy the timestamp from the incident's transaction details page on the relevant blockchain explorer, without including the UTC offset. (ie the +UTC part of the time)
- **Lost Amount**: Enter the amount lost in the incident.
- **Additional Details**: Provide any additional relevant details about the incident.
- **Link Reference**: Enter the link to the reference material or source of information.
- **Attacker's Address**: Enter the attacker's address.
- **Attack Contract Address**: Enter the address of the contract used in the attack.
- **Vulnerable Contract Address**: Enter the address of the vulnerable contract.
- **Attack Transaction Hash**: Enter the transaction hash of the attack.
- **Post-mortem URL**: Enter the URL to the post-mortem analysis of the incident.
- **Twitter Guy URL**: Enter the URL to a Twitter thread or user providing insights about the incident.
- **Hacking God URL**: Enter the URL to a write-up or analysis by a respected security researcher or hacker.
- Additional data: additional data will be asked to record if you want a boilerplate exploit file autogenerated also for you

5. After entering all the required information, the script will automatically update the `README.md` file with the new entry and update the table of contents.

6. Review the changes made to the `README.md` file to ensure the information is accurate and properly formatted.

7. Commit the changes and push them to your forked repository.

8. Create a pull request from your forked repository to the main repository, providing a clear description of the changes you made.

9. Wait for the maintainers to review your pull request. They may provide feedback or request further changes.

10. Once your pull request is approved, it will be merged into the main repository.

## Important Notes

- Make sure to follow the formatting guidelines and provide accurate information when adding a new entry.
- If you encounter any issues or have questions, please open an issue on the repository or reach out to the maintainers.

Thank you for your contribution to our project! Your efforts are greatly appreciated.
6. The script will ask if you want to create a new Solidity file for the POC. If you choose "yes", it will generate a new file in the `src/test/` directory with the provided information and a template for the exploit code.
7. The script will update the `README.md` file with the new incident entry and add it to the table of contents.
## Example Guide
8. Implement the exploit code in the generated Solidity file (e.g., `IncidentName_exp.sol`) by replacing the placeholder code in testExploit with your exploit POC logic.
1. **Install Dependencies**: Make sure you have Python and the required packages (`toml` and `forge-std`) installed.

2. **Run the Python Script**: Execute the Python script by running `python script.py` in your terminal or command prompt.

3. **Select Network**: When prompted, choose the network you want to use for the exploit. The script will display a list of available networks, and you can select one by entering the corresponding number. If the network you want is not listed, you can add a new network by providing its name and RPC URL.

4. **Enter Required Information**: After selecting the network, the script will prompt you to enter the following information:

- File name (e.g., `Example_exp.sol`)
- Timestamp string (e.g., `Mar-21-2024 02:51:33 PM`)
- Lost amount
- Additional details
- Link reference
- Attacker's address
- Attack contract address
- Vulnerable contract address
- Attack transaction hash
- Post-mortem URL
- Twitter guy URL
- Hacking god URL

5. **Create POC File**: The script will ask if you want to create a new Solidity file for the proof-of-concept (POC). If you choose "yes", it will generate a new file in the `src/test/` directory with the provided information and a template for the exploit code.

6. **Update README.md**: The script will update the `README.md` file with a new entry containing the provided information.

7. **Implement Exploit Code**: Open the generated Solidity file (e.g., `Example_exp.sol`) and implement the exploit code in the `//implement exploit code here` section.

8. **Run the Exploit**: In your terminal or command prompt, navigate to the project directory and run the following command to test the exploit:

```sh
forge test --contracts ./src/test/Example_exp.sol -vvv
9. Test the exploit by running the following command:
```bash
forge test --contracts ./src/test/IncidentName_exp.sol -vvv
```
Replace `Example_exp.sol` with the actual file name of the generated Solidity file.

## Example Output
10. Commit your changes and push them to your forked repository:
```bash
git add .
git commit -m "feat: Add POC for IncidentName"
git push origin main
```
With the example data filled in for the `mainnet` network, the tool will add this to the readme allong with the exploit to past defi incidents,like how it already is done before:
11. Open a pull request from your forked repository to the main DeFiHackLabs repository. Provide a clear description of the incident you added.
```markdown
### 20240321 Example - Lost 100 ETH
12. Our maintainers will review your pull request. They may provide feedback or request further changes. Once your pull request is approved, it will be merged into the main repository.
### Lost: 100 ETH

```sh
forge test --contracts ./src/test/Example_exp.sol -vvv
```
#### Contract
[Example_exp.sol](src/test/Example_exp.sol)
### Link reference

https://example.com/incident-report

---

The generated Solidity file (`Example_exp.sol`) might look like this:

```js
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.15;
import "forge-std/Test.sol";

// @KeyInfo - Total Lost : 100 ETH
// Attacker : https://etherscan.io/address/0xcafebabe
// Attack Contract : https://etherscan.io/address/attackcontractaddrhere
// Vulnerable Contract : https://etherscan.io/address/vulcontractaddrhere
// Attack Tx : https://etherscan.io/tx/0x123456789
// @Info
// Vulnerable Contract Code : https://etherscan.io/address/vulcontractaddrhere#code
// @Analysis
// Post-mortem : postmortemurlhere
// Twitter Guy : twitterguyhere
// Hacking God : hackinggodhere

contract ExploitExample is Test {
uint256 blocknumToForkFrom = 1234567;

function setUp() public {
vm.createSelectFork("mainnet", blocknumToForkFrom);
}
## Important Notes
function testExploit() public {
// Implement exploit code here
- Make sure to follow the formatting guidelines and provide accurate information when adding a new incident entry.
- Do not include the UTC offset when copying the timestamp from the transaction details page on the blockchain explorer.
- If you encounter any issues or have questions, please open an issue on the [DeFiHackLabs repository](https://github.com/SunWeb3Sec/DeFiHackLabs/issues) or reach out to our maintainers.
// Log balances after exploit
emit log_named_decimal_uint(" Attacker ETH Balance After exploit", address(this).balance, 18);
}
}
```
We appreciate your contribution to the DeFiHackLabs project. Your efforts help us maintain a valuable resource for the DeFi community to learn from past incidents and improve the security of DeFi protocols. Thank you for your support!

0 comments on commit 417916c

Please sign in to comment.