SmartBugs: A Framework to Analyze Solidity Smart Contracts

SmartBugs is an execution framework aiming at simplifying the execution of analysis tools on datasets of smart contracts.

Features

A plugin system to easily add new analysis tools, based on Docker images;
Parallel execution of the tools to speed up the execution time;
An output mechanism that normalizes the way the tools are outputting the results, and simplifies the process of the output across tools.

Supported Tools

HoneyBadger
Maian
Manticore
Mythril
Osiris
Oyente
Securify
Slither
Smartcheck
Solhint

Requirements

Unix-based system
Docker
Python3

Installation

Once you have Docker and Python3 installed your system, follow the steps:

Clone SmartBugs's repository:

git clone https://github.com/smartbugs/smartbugs.git

Install all the Python requirements:

pip3 install -r requirements.txt

Alternative Installation Methods

We provide a Vagrant box that you can use to experiment with SmartBugs

Usage

SmartBugs provides a command-line interface that can be used as follows:

smartBugs.py [-h, --help]
              --list tools          # list all the tools available
              --list dataset        # list all the datasets available
              --dataset DATASET     # the name of the dataset to analyze (e.g. reentrancy)
              --file FILES          # the paths to the folder(s) or the Solidity contract(s) to analyze
              --tool TOOLS          # the list of tools to use for the analysis (all to use all of them) 
              --info TOOL           # show information about tool
              --skip-existing       # skip the execution that already has results
              --processes PROCESSES # the number of process to use during the analysis (by default 1)

For example, we can analyse all contracts labelled with type reentrancy with the tool oyente by executing:

python3 smartBugs.py --tool oyente --dataset reentrancy

To analyze a specific file (or folder), we can use the option --file. For example, to run all the tools on the file dataset/reentrancy/simple_dao.sol, we can run:

python3 smartBugs.py --tool all --file dataset/reentrancy/simple_dao.sol

By default, results will be placed in the directory results.

Known Limitations

When running a tool the user must be aware of the solc compatibility. Due to the major changes introduced in solidity v0.5.0, we provide the option to pass another docker image to run contracts with solidity version below v0.5.0. However, please note that there may still be problems with the solidity compiler when compiling older versions of solidity code.

Smart Contracts dataset

We make available two smart contract datasets with SmartBugs:

SB Curated: a curated dataset with 143 annotated contracts that can be used to evaluate the accuracy of analysis tools .
SB Wild: a dataset with 47,518 unique contract from the Ethereum network (for details on 3 how they were collected, see the ICSE 2020 paper)

SB Curated

SB Curated provides a collection of vulnerable Solidity smart contracts organized according to the DASP taxonomy. It is available in the dataset repository.

Vulnerability	Description	Level
Reentrancy	Reentrant function calls make a contract to behave in an unexpected way	Solidity
Access Control	Failure to use function modifiers or use of tx.origin	Solidity
Arithmetic	Integer over/underflows	Solidity
Unchecked Low Level Calls	call(), callcode(), delegatecall() or send() fails and it is not checked	Solidity
Denial Of Service	The contract is overwhelmed with time-consuming computations	Solidity
Bad Randomness	Malicious miner biases the outcome	Blockchain
Front Running	Two dependent transactions that invoke the same contract are included in one block	Blockchain
Time Manipulation	The timestamp of the block is manipulated by the miner	Blockchain
Short Addresses	EVM itself accepts incorrectly padded arguments	EVM
Unknown Unknowns	Vulnerabilities not identified in DASP 10	N.A

SB Wild

SB Wild is available in a separated repository due to its size: https://github.com/smartbugs/smartbugs-wild

Work that uses SmartBugs

SmartBugs was used to analyze 47,587 smart contracts. These contracts are available in a separate repository. The results are also in their own repository.
... you are more than welcome to add your own work here!

License

The license in the file LICENSE applies to all the files in this repository, except for all the smart contracts in the dataset folder. The smart contracts in this folder are publicly available, were obtained using the Etherscan APIs, and retain their original licenses. Please contact us for any additional questions.

weidutech/smartbugs