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

• 20 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.

• Linux, MacOS or Windows; other Unixes probably as well
• Docker
• Python3 (version 3.6 and above, 3.10+ recommended)

1. Install Docker and Python3.

   Make sure that the user running SmartBugs is allowed to interact with the Docker daemon, by adding the user to the docker group:

   sudo usermod -a -G docker $USER

   For adding another user, replace $USER by the respective user-id. The group membership becomes active with the next log-in.

2. Clone SmartBugs's repository:

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

3. Install Python dependencies in a virtual environment:

   cd smartbugs
   install/setup-venv.sh

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

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

   The command which smartbugs should now display the path to the command.

See our wiki page on running SmartBugs in Windows.

SmartBugs provides a command-line interface. Run it without arguments for a short description. For details, see the wiki.

./smartbugs
usage: smartbugs [-c FILE] [-t TOOL [TOOL ...]] [-f PATTERN [PATTERN ...]] [--main] [--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.

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

./smartbugs -t mythril -f samples/*.sol --processes 2 --mem-limit 4g --timeout 600

The options tell SmartBugs to run two processes in parallel, with a memory limit of 4GB and max. 10 minutes computation time per task. By default, the results are placed in the local directory results.

reparse can be used to parse analysis results and extract relevant information, without rerunning the analysis. This may be useful either when you did not specify the option --json or --sarif during analysis, or when you want to parse old 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 SimpleDAO.sol with all available tools and write the parsed output to results.csv. reparse is necessary in this example, since smartbugs is called without the options --json and --sarif, so SmartBugs doesn't parse during the analysis. results2csv collects the outputs in the folder results and writes for each analysed contract one line of comma-separated values to standard output (redirected to results.csv). The option -p tells results2csv to format the lists of findings, errors etc. as Postgres arrays; without the option, the csv file is suitable for spreadsheet programs.

./smartbugs -t all -f samples/SimpleDAO.sol
./reparse results
./results2csv -p results > results.csv

• 10 contracts: The folder samples contains a few selected Solidity source files with the corresponding deployment and runtime bytecodes, to test the installation.

• 143 contracts: SB Curated is a curated dataset of vulnerable Solidity smart contracts.

• 3103/2529/2473 contracts as source/deployment/runtime code: Consolidated Ground Truth (CGT) is a unified and consolidated ground truth with 20,455 manually checked assessments (positive and negative) of security-related properties.

• 47,398 contracts: SmartBugs Wild Dataset is a repository with smart contracts extracted from the Ethereum network.

• 248,328 contracts: Skelcodes is a repository of deployment and runtime codes, with an indication if the source code is available on Etherscan. By the way the contracts were selected, they faithfully represent, in most respects, the 45 million contracts successfully deployed up to block 14,000,000.

If you use SmartBugs or any of the datasets above, you may want to cite one of the following papers.

• SmartBugs 2.0: Monika di Angelo, Thomas Durieux, João F. Ferreira, Gernot Salzer: "SmartBugs 2.0: An Execution Framework for Weakness Detection in Ethereum Smart Contracts", in Proc. 38th IEEE/ACM International Conference on Automated Software Engineering (ASE 2023), 2023, to appear.

@inproceedings{diAngeloEtAl2023ASE,
  title = {{SmartBugs} 2.0: An Execution Framework for Weakness Detection in {Ethereum} Smart Contracts},
  author={di Angelo, Monika and Durieux, Thomas and Ferreira, Jo{\~a}o F. and Salzer, Gernot},
  booktitle={Proceedings of the 38th IEEE/ACM International Conference on Automated Software Engineering (ASE 2023)},
  year={2023},
  note={to appear}
}

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

@inproceedings{FerreiraEtAl2020ASE,
  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}
}

• SmartBugs Wild Dataset: Durieux, T., Ferreira, J.F., Abreu, R. and Cruz, P.: "Empirical review of automated analysis tools on 47,587 Ethereum smart contracts:, in Proceedings of the ACM/IEEE 42nd International Conference on Software Engineering (ICSE 2020), pages 530-541, 2020. The paper analyzes the contracts in the wild dataset using SmartBugs v1.0. The results are available in a separate repository.

@inproceedings{DurieuxEtAl2020ICSE,
  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}
}

• Skelcodes: Monika di Angelo, Thomas Durieux, João F. Ferreira, Gernot Salzer: "Evolution of Automated Weakness Detection in Ethereum Bytecode: a Comprehensive Study", in Empirical Software Engineering, Springer, 2023, to appear.

@article{diAngeloEtAl2023EMSE,
  title = {Evolution of Automated Weakness Detection in {Ethereum} Bytecode: a Comprehensive Study},
  author={di Angelo, Monika and Durieux, Thomas and Ferreira, Jo{\~a}o F. and Salzer, Gernot},
  journal={Empirical Software Engineering},
  year={2023),
  note={to appear}
}

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

🙌 ETH Donations: 0xA4FBA2908162646197aca90b84B095BE4D16Ae53 🙌

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