Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/inspexco/poctous
https://github.com/inspexco/poctous
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/inspexco/poctous
- Owner: InspexCo
- Created: 2023-12-01T10:43:32.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-02-01T07:33:45.000Z (11 months ago)
- Last Synced: 2024-08-10T09:05:10.387Z (5 months ago)
- Language: JavaScript
- Size: 94.7 KB
- Stars: 11
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# POCtoUS
[](http://creativecommons.org/licenses/by-sa/4.0/)
POCtoUS is pronounced like 'Octopus'🐙 but in reverse. It is a script that aims to help create an environment for analyzing a transaction on the blockchain by leveraging the power of an incredible tool, [Foundry](https://github.com/foundry-rs/foundry).
The tool will create a foundry test file of a given transaction hash. The tool will try to imitate the attacker's attack contract. It also downloads and flattens the contract source code of every related address.
For now, the code looks really messy. We want to express the ideas first, then re-organize them after consider it worth doing.
## Usage
The script can be executed anywhere using `poctopus`.
```bash
poctous [txHash] [-f force pulling the rpc] [-r url of the rpc] [-k API key of the block explorer] [-e (optional) endpoint of the block explorers API] [--auto-merge enable auto-merge feature] [--maximize download all un-related verified contract]
```
For example
```bash=
poctous 0xc42fe1ce2516e125a386d198703b2422aa0190b25ef6a7b0a1d3c6f5d199ffad -r https://eth.llamarpc.com -k ABC1234567
```
The script will create a folder `POC` at the current directory that contains basic necessities for doing the POC.
* Some contracts downloading may fail. If you experience some oddity in the POC file, you can run the script again to re-download the failed files. This might help in some cases.
Normally, the script will pull the data from the RPC once and cache the pulled data. On the next executions, it will use the data from the cache file. You can use the `-f` flag to force the script to pull the data from the RPC instead of using the cache.
### Run the test file
The POC files are forge test files. They can be run with the ol' classic `forge test` command. You can add `--match-contract` flag to specify the POC contract that you want to test specifically.
In the test file, we specified that the test would fork from `Anvil` environment. We suggest running the `anvil` beforehand, which would be good for the testing.
```
anvil -f --no-mining
```
### Required Environment
The script requires the RPC and the API key of the chain's block explorer to operate. They can be specified using the `-r` and `-k` flags when executing the script.
```bash=
poctous 0xc42fe1ce2516e125a386d198703b2422aa0190b25ef6a7b0a1d3c6f5d199ffad \
-r https://eth.llamarpc.com \
-k ABC1234567
```
The `-e` flag is totally an optional. The script will check the chain from the RPC and use default block explorer from the predefined list. When you need to use the script on another chain that does not in the `Predefined endpoint chain` list, you need to specify the endpoint through the `-e` flag.
## Predefined endpoint chain
- Ethereum Mainnet (https://api.etherscan.io/api)
- Goerli (https://api-goerli.etherscan.io/api)
- OP Mainnet (https://api-optimistic.etherscan.io/api)
- BNB Smart Chain Mainnet (https://api.bscscan.com/api)
- BNB Smart Chain Testnet (https://api-testnet.bscscan.com/api)
- Arbitrum One (https://api.arbiscan.io/api)
## File structure
The script will create a `POC` folder that have the `forge init` setup.
#### Sourcecode
The script will download all verified contract the are interacted on the transaction. The downloaded sourcecode will be flattened and have the abis and interfaces extracted. They will be stored under the `src_poc` folder and each `transaction` folder.
#### Test file
The testfile (POC) is a forge test file. It will be created under the `test` folder. You can run the test file like any other forge test file by using `forge test` command.
```
POC
├── README.md
├── cache
├── foundry.toml
├── lib
├── out
├── script
├── src
├── src_poc
│ └── 0xabcdef // First 4 bytes of the tx
│ ├── (Contracts replate to the tx)
│ │ ├── (ContractName).abi.json
│ │ ├── (ContractName).interface.sol
│ │ └── (ContractName).sol
│ ├── interface.aggregate.sol // the interface that being used by the POC
│ └── lib.constant.sol // the constrant value of the addresses
└── test
└── CopiedCall(0xabcdef).t.sol // The POC file (almost) ready to be tested
```
## Installation
Users can install POCtoUS from npm registry directly.
```bash
npm install -g @inspex/poctous
```
Or clone the repository then install it locally.
```bash
git clone https://github.com/InspexCo/POCtoUS.git
cd poctous
npm install -g
```
## Example
To demonstrate the tool, we choose a transaction that have had an attack occurred, `0xc42fe1ce2516e125a386d198703b2422aa0190b25ef6a7b0a1d3c6f5d199ffad`.
In this transaction, there are callbacks. It is good example to show the quirky side of the tool that might confuse a new user.
### 1. Run the tool
We assume that you have already cloned and completed the npm install step. The tool can be run anywhere, and the `POC` folder will be created in that directory.
In this example, we will run the tool at the root of the repository path using the following command.
```bash=!
src/main.js 0xc42fe1ce2516e125a386d198703b2422aa0190b25ef6a7b0a1d3c6f5d199ffad \
-r https://eth.llamarpc.com \
-k {YOUR_BLOCK_EXPLORER_API_KEY}
```
If there are no errors, the log should appear as follows. The tool will attempt to retrieve the source code of every address called in the transaction from the respective block explorer's API endpoint. The download process might take time, and some downloads may fail. Failed contract downloads may or may not impact the generated POC file. You can rerun the tool to attempt downloading the failed contracts again.
There are three files being generated from the tool:
- `test/CopiedCall(0xc42fe1ce25).t.sol` This is the POC file that can be run with `forge test`.
- `src_poc/0xc42fe1ce/lib.constant.sol` A file that contains the named addresses' address.
- `src_poc/0xc42fe1ce/interface.aggregate.sol` A file that collects the interfaces that being used by the POC file.
### 2. Look at the POC file
The tool has completed its duty. It ain't much, but it's an honest work. The POC file might be runnable for less complex transactions, but in most cases, it will require cleanup. It's our responsibility to tidy up the POC file.
The `C_A_0x9d9820_13d` contract imitates the attacker's exploiting contract. Each function includes comments explaining how it's called and who the caller is. Additionally, there's a comment indicating when a function is duplicated. Handling these aspects will be our next step.
The addresses are replaced by constant variables sourced from the lib.constant.sol file to improve the readability of the POC file. The names are gathered from the block explorer's verified contracts.
- If the name has `A_` as a prefix, it means that the addresses are not verified or be an EOA address.
- If the name has `C_` as a prefix, it means that the addresses are contracts that being generated by the tool that meant to represent the respective addresses.
The test contract locates at the bottom of the POC file. It has only one test function `testMimicContractCall()`.
- The `EOA` state is the address of the attacker. It is not necessary to prank being the attacker; you can remove the `vm.deal()` and `vm.startPrank()` from the test.
- The `target` state is the address of the original attacking contract. The address of the state will be overwritten by our imitated contract (a contract that has `C_` as a prefix).
The `setUp()` function will call the `vm.createSelectFork()` function to use the environment from `Anvil`. You can change this line if you want to use other ways to fork the chain to test.
The `testMimicContractCall()` function will deploy the imitated contract and call it with the call data. The function signature can be changed by the tool if the called cannot be decoded.
### 3. Clean the POC file
The imitated contract has one problem; it contains numerous functions with identical signatures. A function is generated for each call made to the contract. For instance, in this scenario, the attacking contract has three calls to the `onERC1155Received()` function, resulting in the creation of three such functions.
The first and second functions are identical, including their inputs. The third function, however, differs as it lacks a call to the deposit() function. To merge them into a single function, we need to establish a condition for branching the execution. Alternatively, using a more straightforward approach, just count them.
### 4. Setup Anvil (Optional)
Since the attack occurred in the past, we need to fork that block to have the environment as same as the real attacking. We use `Anvil` as the default value for the forking chain. If you wish the change, you can edit the endpoint in the `foundy.toml` file.
Anvil can be started by simply using `anvil` command. Since we want to fork block, we have to add the `-f` flag and the RPC to the command.
### 5. Do anything with education purpose
Now the test file is ready. You can do anything you want with the POC file. Since we are doing this for educational purposes, we will run the POC using the `forge test -vvvv` command to understand how the transaction works.
The result of the testing is `FAIL`. Why? Because the entire process of the attack doesn't start and end within one transaction. This is a crucial point I want to emphasize to users of the tool: the tool generates a POC from a single transaction only. Simulating the complete attack may require information spanning multiple transactions.
## Feature
### Auto-merge
```
--auto-merge
// Automatically merge the duplicated functions in imitated contracts
```
From the example, we have encountered a problem that there are duplicated functions in the imitated contract and the users have to manually merge them.
By adding the `--auto-merge` flag, the tool will automatically merge any duplicated functions into one single function in the most naive approach.
### Maximize
```
--maximize
// Download all the verified contract sourcecode that appear in the transaction
```
Normally, the script will download the source code of the contract that being balled by the generated contracts from the script. In the case that you want to use the source code of some contracts that appear in the transaction for further analyzing the POC, you can use this flag, `--maximize`, to have the script download all source code of verified contract that appear in the transaction.
## Limitation
- The functions that are being called multiple times will be generated multiple times too. The user needs to merge them into one function or relying on the `auto-merge` feature of the script.
- It can only generate a contract for one transaction at a time. The simulation of multiple transaction attacks will likely fail.
- Some calls that we cannot decode will become low-level calls in which the parameters will not be dynamically altered.
- A call that contains a complex data type will not likely be able to be decoded.
- The RPC must support the `debug_traceTransaction` method.
- The script will download ALL verified contracts of the address that appear at least once in the transaction though the POC does not need some of them.
## Common errors/issues
- An error after `Pulling data` process.
They are common errors about the RPC pulling transaction data. The error code are commonly be `-32000` and `-32600`.
- Try changing the RPC that supports `debug_traceTransaction` method and the RPC must have the data of the block of the transaction, preferably an RPC from an archive node.
- Function with same name and parameter types defined twice.
It is an intended behavior of the tool (for now). It happens when the functions are called multiple time. It likely happens on a reentrancy attack.
- The user has to merge them into one function. By merging, the user has to guess how to correctly return the right return value of each call; we have a hint of a call as a comment before the functions.
- In the new version, you can use the `--auto-merge` flag to let the tool automatically merge the functions.