From b3be6a12bb75c77beb8ab6dcd38cfd136c3ad691 Mon Sep 17 00:00:00 2001 From: akshaynexus Date: Sun, 24 Mar 2024 03:08:43 +0300 Subject: [PATCH] doc: make the documentation better --- CONTRIBUTING.md | 191 +++++++++++++++++------------------------------- 1 file changed, 69 insertions(+), 122 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8594a9e5..e2d56793 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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! \ No newline at end of file