SmartBugs: A Framework for Analysing Ethereum Smart Contracts

SmartBugs is an extensible platform with a uniform interface to tools that analyse blockchain programs for weaknesses and other properties.

Features

17 supported tools, 3 modes for analysing Solidity source code, deployment bytecode, and runtime code.
A modular approach to integrating analysers. All it takes to add a new tool is a Docker image encapsulating the tool and a few lines in a config file. To make the output accessible in a standardised format, add a small Python script.
Parallel, randomised execution of the tasks for the optimal use of resources when performing a bulk analysis.
Standardised output format. Scripts parse and normalise the output of the tools to allow for an automated analysis of the results across tools.
Automatic download of an appropriate Solidity compiler matching the contract under analysis, and injection into the Docker image.
Output of results in SARIF format, for integration into Github workflows.

Supported Tools

	version	Solidity	bytecode	runtime code
Conkas	#6aee098	✔️		✔️
Ethainter				✔️
eThor	2021 (CCS 2020)			✔️
HoneyBadger		✔️		✔️
MadMax	#6e9a6e9			✔️
Maian	#4bab09a	✔️	✔️	✔️
Manticore	0.3.7	✔️
Mythril	0.23.5	✔️	✔️	✔️
Osiris		✔️		✔️
Oyente	#480e725	✔️		✔️
Pakala	#c84ef38 v1.1.10			✔️
Securify		✔️		✔️
Slither		✔️
Smartcheck		✔️
Solhint	2.1.0	✔️
teEther	#04adf56			✔️
Vandal	#d2b0043			✔️

Requirements

Unix-based system (Windows users might want to read our wiki page on running SmartBugs in Windows)
Docker
Python3 (version 3.6 and above, 3.10+ recommended)

Installation

Unix/Linux

Install Docker and Python3.
Clone SmartBugs's repository:

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

Install Python dependencies in a virtual environment:

cd smartbugs
install/setup-venv.sh

Optionally, add the executables to the command search path, e.g. by adding links to $HOME/bin.

ln -s "`pwd`/smartbugs" "$HOME/bin"
ln -s "`pwd`/reparse" "$HOME/bin"
ln -s "`pwd`/results2csv" "$HOME/bin"

Windows

See our wiki page on running SmartBugs in Windows.

Usage

SmartBugs provides a command-line interface. Run it without arguments for a short description.

./smartbugs
usage: smartbugs [-c FILE] [-t TOOL [TOOL ...]] [-f PATTERN [PATTERN ...]] [--runtime]
                 [--processes N] [--timeout N] [--cpu-quota N] [--mem-limit MEM]
                 [--runid ID] [--results DIR] [--log FILE] [--overwrite] [--json] [--sarif] [--quiet] 
                 [--version] [-h]

For details, see SmartBugs' wiki.

To analyse the Solidity files in the samples directory with Mythril, use the command

./smartbugs -t mythril -f samples/*.sol

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

Utility programs

reparse can be used to parse the analysis results anew, without rerunning the analaysis. This may be useful either when you forgot to specify the options --json or --sarif during analysis, or when you want to parse the analysis results with an updated parser.

./reparse
usage: reparse [-h] [--sarif] [--processes N] [-v] DIR [DIR ...]
...

results2csv generates a csv file from the results, suitable e.g. for a database.

./results2csv
usage: results2csv [-h] [-p] [-v] [-f FIELD [FIELD ...]] [-x FIELD [FIELD ...]] DIR [DIR ...]
...

The following commands analyse simple_dao.sol with all available tools and write the parsed output to results.csv. The option --json tells SmartBugs to write the parsed output to json files (one per contract). results2csv collects the outputs in directory results and writes one line per analysis task to

./smartbugs -t all -f samples/simple_dao.sol --json
./results2csv results > results.csv

Further Information

For documentation, see the wiki.
Sample contracts: The folder samples contains a few selected Solidity source files with the corresponding deployment and runtime bytecodes, for first experiments.
SB Curated is a curated dataset of vulnerable Solidity smart contracts.
SmartBugs Wild Dataset is a repository with 47,398 smart contracts extracted from the Ethereum network.

Academic Usage

If you use SmartBugs or any of its datasets, please cite:

Durieux, T., Ferreira, J.F., Abreu, R. and Cruz, P., 2020. Empirical review of automated analysis tools on 47,587 Ethereum smart contracts. In Proceedings of the ACM/IEEE 42nd International Conference on Software Engineering (pp. 530-541).

@inproceedings{durieux2020empirical,
  title={Empirical review of automated analysis tools on 47,587 Ethereum smart contracts},
  author={Durieux, Thomas and Ferreira, Jo{\~a}o F. and Abreu, Rui and Cruz, Pedro},
  booktitle={Proceedings of the ACM/IEEE 42nd International conference on software engineering},
  pages={530--541},
  year={2020}
}

Ferreira, J.F., Cruz, P., Durieux, T. and Abreu, R., 2020. SmartBugs: A framework to analyze solidity smart contracts. In Proceedings of the 35th IEEE/ACM International Conference on Automated Software Engineering (pp. 1349-1352).

@inproceedings{ferreira2020smartbugs,
  title={SmartBugs: A framework to analyze solidity smart contracts},
  author={Ferreira, Jo{\~a}o F and Cruz, Pedro and Durieux, Thomas and Abreu, Rui},
  booktitle={Proceedings of the 35th IEEE/ACM International Conference on Automated Software Engineering},
  pages={1349--1352},
  year={2020}
}

Work that uses SmartBugs

SmartBugs was used to analyze 47,587 smart contracts (work published at ICSE 2020). These contracts are available in a separate repository. The results are also in their own repository. The version of SmartBugs used in this study was SmartBugs v1.0.
SmartBugs was used to evaluate a simple extension of Smartcheck (work published at ASE 2020, Tool Demo Track)
... you are more than welcome to add your own work here!

Support and Donate

You can show your appreciation for the project and support future development by donating.

🙌 ETH Donations: 0xA4FBA2908162646197aca90b84B095BE4D16Ae53 🙌

License

The license applies to all files in the repository, with the exception of the smart contracts in the dataset folder. The files there were obtained from Etherscan and retain their original licenses.

bre7 / smartbugs