Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/enzymefinance/oyente

An Analysis Tool for Smart Contracts
https://github.com/enzymefinance/oyente

blockchain ethereum security-analyzers smart-contracts

Last synced: about 2 months ago
JSON representation

An Analysis Tool for Smart Contracts

Awesome Lists containing this project

README 

        
Oyente

======



An Analysis Tool for Smart Contracts



[![Gitter][gitter-badge]][gitter-url]

[![License: GPL v3][license-badge]][license-badge-url]

[![Build Status](https://travis-ci.org/melonproject/oyente.svg?branch=master)](https://travis-ci.org/melonproject/oyente)



*This repository is currently maintained by Xiao Liang Yu ([@yxliang01](https://github.com/yxliang01)). If you encounter any bugs or usage issues, please feel free to create an issue on [our issue tracker](https://github.com/melonproject/oyente/issues).*



## Quick Start



A container with required dependencies configured can be found [here](https://hub.docker.com/r/luongnguyen/oyente/). 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](https://github.com/melonproject/oyente/tree/290f1ae1bbb295b8e61cbf0eed93dbde6f287e69) referred to in the paper, run the container from [here](https://hub.docker.com/r/hrishioa/oyente/)



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](https://github.com/melonproject/oyente#solc)

[evm](https://github.com/melonproject/oyente#evm-from-go-ethereum)



## 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](https://github.com/ethereum/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](https://github.com/Z3Prover/z3/releases) Theorem Prover version 4.5.0.



Download the [source code of version z3-4.5.0](https://github.com/Z3Prover/z3/releases/tag/z3-4.5.0)



Install z3 using Python bindings



```

$ python scripts/mk_make.py --python

$ cd build

$ make

$ sudo make install

```



#### [Requests](https://github.com/kennethreitz/requests/) library



```

pip install requests

```



#### [web3](https://github.com/pipermerriam/web3.py) library



```

pip install web3

```



### Evaluating Ethereum Contracts



```

#evaluate a local solidity contract

python oyente.py -s 



#evaluate a local solidity with option -a to verify assertions in the contract

python oyente.py -a -s 



#evaluate a local evm contract

python oyente.py -s  -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](https://www.comp.nus.edu.sg/~prateeks/papers/Oyente.pdf).



## 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](https://etherscan.io)

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](https://github.com/melonproject/oyente/blob/master/CONTRIBUTING.md) and the code structure [here](https://github.com/melonproject/oyente/blob/master/code.md).



[gitter-badge]: https://img.shields.io/gitter/room/melonproject/oyente.js.svg?style=flat-square

[gitter-url]: https://gitter.im/melonproject/oyente?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge

[license-badge]: https://img.shields.io/badge/License-GPL%20v3-blue.svg?style=flat-square

[license-badge-url]: ./LICENSE