Tool Release – Web3 Decoder Burp Suite Extension

Web3 Decoder is a Burp Suite Extension that allows to decode “web3” JSON-RPC calls that interact with smart contracts in a EVM blockchain.

As it is said that a picture is worth a thousand words, the following two screenshots shows a Raw JSON-RPC call, and its decoded function call:

Background

When auditing a DApp (Decentralized Application), its main database would usually be the state of the blockchain, and in particular, the state of a different set of smart contracts deployed in that network. The communication with these smart contract functions is made usually through the use of JSON-RPC calls to a blockchain node, that will be able to query the state of an smart contract, or send a signed transaction that modify its state.

As a pentester, a security auditor, or an enthusiast that wants to better understand what is going on on that DApp, or what smart contracts are being used and how, this is a tedious task, as JSON-RPC call data is RLP encoded. Fortunately for us, it is very common that projects publish their source code and verify their smart contracts in block explorers like Etherscan, and there is where our extension comes in handy, by consulting these block explorers, obtaining the ABI (Application Binary Interface) of the called smart contract, and decoding in a human readable format, its contents for us.

Installation

1. Clone our github repository: https://github.com/nccgroup/web3-decoder
2. (Optional). Create a virtualenv or install the application prerequisites in your system (see section below)
3. Add as a Python extension the file burp_web3_decoder.py
4. Update your block explorer API keys to be able to perform more than 1 request every 5 seconds (more information on the README.md page)
5. Start hacking!

We recommend following these instructions on the README.md page of the github repository (which we will keep updated!)

Supporting Python3 Library and Precompiled Binaries

This extension requires python3 libraries like web3.py that unfortunately are not available for python 2.7 to be used directly with Jython 2.7. As a ‘hack’, the main functionality is written in a python 3 library that is being executed by the extension through a python virtual environment (talking about dirty…)

I have created precompiled binaries of the python3 library used, for Linux, Windows and Mac OSX. The extension will use these binaries unless it is able to execute the supporting library, directly or through a python virtual environment.

For better performance or development, you can create a virtualenv, and install as follows:

git clone https://github.com/nccgroup/web3-decoder 
cd "web3-decoder"
virtualenv -p python3 venv
source venv/bin/activate
pip install -r libs/requirements.txt

How It Works

The burp extension creates a new Editor Tab when detecting a valid JSON-RPC request or response. It performs a eth_chainId JSON-RPC request to the node in use to detect which chain we are working on, and depending on the chain, selects a block explorer API, by searching in the chains.json file.

The Extension has the following capabilities

• Decode of eth_call JSON-RPC calls
• Decode of eth_sendRawTransaction JSON-RPC calls (and their inner functions)
• Decode of response results from eth_call
• Support for re-encoding of eth_call decoded functions
• Automatic download of the smart contract ABI called from etherscan APIs (if the contract is verified)
• Decode of function inputs both in eth_call and eth_sendRawTransaction
• Decode of function inputs that uses “Delegate Proxy” contracts
• Decode of function inputs called via “Multicall” contracts
• Manual addition of contract ABIs for contracts that are not verified in etherscan
• Support for other compatible networks (check the chains.json file)

As an example of use, to decode function calls, we need the ABI (Application Binary Interface) of the contract, which contains all functions that can be called in the contract and their inputs and outputs. For now, it works with verified contracts in the block explorer, or by manually adding the ABI. In future releases, we will explore the possibility of automatically generating an ABI by searching the function selectors in public databases.

The following “flow” diagram shows in a simplified way the process that the eth_decoder library follows when decoding eth_call JSON-RPC calls:

Chains Supported so far

All supported chains can be found in the chains.json file.
These are chains that have a block explorer with the same APIs as etherscan.

At the moment of writing, the following list of EVM chains were supported by this extension:

If you want to add more blockchain explorers, add them to the chains.json file, test that it works, and make a pull request! (Or if you are not sure of how to do all this, simply create an issue asking for it!)

Future Work

• Aggregate other types of Proxy / Multicall contracts
• Decode Functions without ABI based on public Ethereum signature databases such as 4byte.directory or offline panoramix 4byte signature database

I am always more than happy to consider adding new features to the extension or the supporting library, so feel free to come by the Github page and create an issue with any features that you may want! (or with any bug that you find!)