Oyente

This repository is currently maintained by Xiao Liang Yu (@yxliang01). If you encounter any bugs or usage issues, please feel free to create an issue on our issue tracker.

An Analysis Tool for Smart Contracts, Support 0.8.0 Solidity and above NOW.

Oyente is an smart contract vulnerability detection tool based on symbolic execution. Currently, the version of Oyente released by the author theoretically supports smart contracts written in Solidity up to version 0.4.19 and disassemblers up to EVM version 1.7.3. However, in practical testing, it can detect vulnerabilities in smart contract written in Solidity up to version 0.5.16.

The current version of Oyente is unable to detect smart contracts written in Solidity versions higher than 0.5.16. This limitation arises because the newer versions of the Solidity language solc compiler have some differences in API calls and design compared to the older versions. Additionally, higher versions of Solidity correspond to EVM virtual machines that incorporate more opcodes.

Therefore, we have extended the version compatibility of the original Oyente to support all Solidity versions up to the latest available version as of June 2023, which was 0.8.19.

What have we done?

• We have introduced symbolic execution schemes for 7 new instructions to enhance support for the new opcode instructions in the latest version of the virtual machine, including SHL, SHR, SAR, EXTCODEHASH, CREATE2, CHAINID, and SELFBALANCE.

• We made slight adjustments to the regular expressions used by the Solidity compiler (solc) to parse binary contract content, aligning them with the compilation adjustments made in versions of solc higher than 0.5.16.

• We conducted reverse engineering of the EVM bytecode compiled from the Solidity smart contract dataset and summarized a set of common bytecode patterns to remove non-runtime code generated by the solc compiler using the solc --bin-runtime compilation method.

• Solc version 0.8.0 and above utilize a different structure for the abstract syntax tree (AST). Consequently, we have developed additional analysis methods specifically tailored for the new abstract syntax tree of Solidity programming language version 0.8.0 and above. These methods enable vulnerability detection in smart contracts written in 0.8.0 and higher versions of Solidity.

Test

The dataset we utilized is sourced from ConsenSys open-source smart contract dataset, containing over 100,000 smart contracts written in various versions of Solidity ranging from 0.4.2 to 0.8.19. From this dataset, we selected the most abundant contracts for each of the 0.4, 0.5, 0.6, 0.7, and 0.8 versions (specifically 0.4.24, 0.5.17, 0.6.12, 0.7.6, and 0.8.7). We then sampled approximately 1500 smart contract files based on a 5% confidence interval and a 95% confidence level.

These smart contracts were tested under EVM version 1.7.3 and various versions of Solidity. The test results are as follows:

The number of detected smart contract vulnerabilities is as follows:

The EVM Code Coverage is as follows:

Quick Start

A container with required dependencies configured can be found here. The image is however outdated. We are working on pushing the latest image to dockerhub for your convenience. If you experience any issue with this image, please try to build a new docker image by pulling this codebase before open an issue.

To open the container, install docker and run:

docker pull luongnguyen/oyente && docker run -i -t luongnguyen/oyente

To evaluate the greeter contract inside the container, run:

cd /oyente/oyente && python oyente.py -s greeter.sol

and you are done!

Note - If need the version of Oyente referred to in the paper, run the container from here

To run the web interface, execute docker run -w /oyente/web -p 3000:3000 oyente:latest ./bin/rails server

Custom Docker image build

docker build -t oyente .
docker run -it -p 3000:3000 -e "OYENTE=/oyente/oyente" oyente:latest

Open a web browser to http://localhost:3000 for the graphical interface.

Installation

Execute a python virtualenv

python -m virtualenv env
source env/bin/activate

Install Oyente via pip:

$ pip2 install oyente

Dependencies:

The following require a Linux system to fufill. macOS instructions forthcoming.

solc evm

Full installation

Install the following dependencies

solc

$ sudo add-apt-repository ppa:ethereum/ethereum
$ sudo apt-get update
$ sudo apt-get install solc

evm from go-ethereum

1. https://geth.ethereum.org/downloads/ or
2. By from PPA if your using Ubuntu

$ sudo apt-get install software-properties-common
$ sudo add-apt-repository -y ppa:ethereum/ethereum
$ sudo apt-get update
$ sudo apt-get install ethereum

z3 Theorem Prover version 4.5.0.

Download the source code of version z3-4.5.0

Install z3 using Python bindings

$ python scripts/mk_make.py --python
$ cd build
$ make
$ sudo make install

Requests library

pip install requests

web3 library

pip install web3

Evaluating Ethereum Contracts

#evaluate a local solidity contract
python oyente.py -s <contract filename>

#evaluate a local solidity with option -a to verify assertions in the contract
python oyente.py -a -s <contract filename>

#evaluate a local evm contract
python oyente.py -s <contract filename> -b

#evaluate a remote contract
python oyente.py -ru https://gist.githubusercontent.com/loiluu/d0eb34d473e421df12b38c12a7423a61/raw/2415b3fb782f5d286777e0bcebc57812ce3786da/puzzle.sol

And that's it! Run python oyente.py --help for a list of options.

Paper

The accompanying paper explaining the bugs detected by the tool can be found here.

Miscellaneous Utilities

A collection of the utilities that were developed for the paper are in misc_utils. Use them at your own risk - they have mostly been disposable.

1. generate-graphs.py - Contains a number of functions to get statistics from contracts.
2. get_source.py - The get_contract_code function can be used to retrieve contract source from EtherScan
3. transaction_scrape.py - Contains functions to retrieve up-to-date transaction information for a particular contract.

Benchmarks

Note: This is an improved version of the tool used for the paper. Benchmarks are not for direct comparison.

To run the benchmarks, it is best to use the docker container as it includes the blockchain snapshot necessary. In the container, run batch_run.py after activating the virtualenv. Results are in results.json once the benchmark completes.

The benchmarks take a long time and a lot of RAM in any but the largest of clusters, beware.

Some analytics regarding the number of contracts tested, number of contracts analysed etc. is collected when running this benchmark.

Contributing

Checkout out our contribution guide and the code structure here.