SmartBugs and the case for running many analysers behind one interface

Why run twenty-eight tools on one contract

SmartBugs is an extensible platform with a uniform interface to tools that analyse blockchain programs for weaknesses and other properties, described in the paper SmartBugs 2.0: An Execution Framework for Weakness Detection in Ethereum Smart Contracts, published in the proceedings of the 38th IEEE and ACM International Conference on Automated Software Engineering.

The premise is that a single analyser gives you a single opinion, and that a single opinion on a smart contract is a weak basis for a security decision. The framework exists to run many of them and make the results comparable.

The headline figures are 28 supported tools and 3 modes for analysing Solidity source code, deployment bytecode and runtime code. The tool table in the README is the real content, and it maps each tool to the modes it supports. Mythril covers all three, and so do Maian, HoneyBadger, Osiris and Securify. Most others cover only source, and a handful, such as Ethainter, eThor, MadMax, Pakala, teEther, Vandal and Conkas, are runtime-code only.

The audience is a security researcher or an auditor who wants to see several tools agree, or disagree, about the same contract.

Adding a tool is a Docker image and a config file

The modular integration of analysers is the feature that makes the framework extensible rather than merely a bundler. All it takes to add a new tool is a Docker image encapsulating the tool and a few lines in a config file, and to make the output accessible in a standardised format, a small Python script.

That is a low bar, and it explains why the table includes both production tools and research prototypes. A tool author is expected to integrate their own tool with optimal settings rather than waiting for a third party to do so, and the README asks them to issue a pull request.

The Python script is the contract. Every tool's output goes through it, and the scripts parse and normalise the output of the tools to allow for an automated analysis of the results across tools. Without that normalisation step, a framework like this would produce a pile of reports in different formats that a human still has to read and reconcile, which is the part that does not scale to a portfolio of contracts.

The result output is available in SARIF format, for integration into GitHub workflows. SARIF is the static analysis results interchange format, so the output is a file that code scanning tooling can ingest directly, which is what makes the framework usable in a continuous integration pipeline rather than only on a laptop.

Docker per tool, and the compiler that comes with it

Two implementation details carry most of the framework's weight.

The first is that each tool runs in its own Docker container, which is what makes the uniformity possible. A tool that needs a specific Python version, a specific EVM build or a specific native library can have it, because the container image encapsulates all of that. The docker dependency in the package metadata is at 7.0.0 or later, and the platform independence claim in the README, that SmartBugs has been tested with Linux, MacOS and Windows, is a claim about Docker rather than about the framework's own code.

The second is the automatic download of an appropriate Solidity compiler matching the contract under analysis, and injection into the Docker image. This is more significant than it sounds. Solidity analysis tools are sensitive to the compiler version, because the compiler determines the bytecode and the metadata hash embedded in it, and a tool configured for the wrong version can produce wrong results or refuse to run. Fetching the right compiler per contract and putting it in the image is the kind of step that is easy to get wrong by hand and tedious to get right across a batch.

The execution model is parallel, randomised and restartable, described as being for the optimal use of resources when performing a bulk analysis. If execution is interrupted, it can be resumed by running SmartBugs with the same parameters again. That combination is what makes a full analysis of a contract with twenty-eight tools across three input modes practical rather than theoretical.

The tool table is also a warning

The README opens with two notes aimed at different audiences, and the second one is the important one.

For tool authors, the message is to integrate your own tool rather than waiting for a third party to do so, with optimal settings, and to open a pull request.

For users, the warning is that alongside maintained tools like Mythril, Oyente+, Semgrep, Slither and Solhint, SmartBugs also offers unmaintained academic research prototypes which may be incompatible with current Solidity and EVM versions.

That warning is not decorative, and the notes at the bottom of the table show why. Oyente+ is an update of the now unmaintained Oyente tool, and Oyente is limited to outdated EVM versions, roughly corresponding to Solidity 0.4.x, because it does not handle EVM operations introduced later. Several entries in the table are pinned to a commit hash rather than a release, such as Conkas at #4e0f256, HoneyBadger at #ff30c9a and Semgrep at a specific version pair, which is another way of seeing that these are the versions the framework was tested against, not necessarily the current ones.

The samples directory tells the same story from the other direction. It holds example contracts for 0.4.x, 0.5.17, 0.6.12, 0.7.6 and 0.8.24, one directory per Solidity generation, plus a vulnerabilities.json. A framework that supports five Solidity generations and twenty-eight tools is a compatibility surface, and the unmaintained entries are where a bulk run will fail first.

The package and the development workflow

The package is a single Python distribution built with poetry-core, named smartbugs at version 2.2.0, with the description An extensible framework for analyzing Ethereum smart contracts using multiple security analysis tools. The module is sb and the console entry point is:

[tool.poetry.scripts]
smartbugs = "sb.cli:main"

The runtime dependencies are short and tell you the shape of the tool: docker for the containers, PyYAML for the tool configuration, Requests and urllib3 for the network, semantic_version for version comparisons, colorama for terminal output, pycryptodome for the crypto, py-cpuinfo for hardware information and packaging for version handling.

Python 3.10 to 3.12 are the supported versions, and the project is classified as Development Status 4 - Beta with Intended Audience covering both Developers and Science/Research.

The Makefile wraps the development commands. The setup target runs a shell script that creates the virtual environment, and the individual targets cover unit tests, integration tests, formatting with Black, linting with Ruff and type checking with Mypy. The coverage floor is set in the Makefile at a minimum of 90, with a term-missing report format. The other top-level directories tell you the rest: tools/ for the tool configurations, templates/ for the output normalisation scripts, samples/ for the example contracts, solc_select/ for the compiler selection logic, and results2csv plus reparse for result conversion.

What it is not, and the licence inconsistency

Two things are worth stating before anyone builds on this.

The first is scope. SmartBugs is an execution framework for comparing analysers, not a static analyser. It does not find vulnerabilities on its own, it does not rank them, and it does not tell you which finding to trust when Mythril and a 2019 research prototype disagree about the same line. The output is a normalised set of results and a SARIF file; the judgement is still yours. If your goal is a green check in a pull request, this is the wrong tool, and something like a single analyser invoked directly would be simpler and faster.

The second is the licence, and here the repository contradicts itself. The repository listing shows the licence as Apache-2.0 and the README carries an Apache-2.0 licence badge pointing at the LICENSE file. The package metadata in pyproject.toml says license = "MIT" and the classifier reads License :: OSI Approved :: MIT License, and the README's own licence line refers to the MIT badge. MIT and Apache-2.0 differ in their patent grant, so this is not a cosmetic difference, and a team shipping SmartBugs inside a commercial security product should resolve it with the maintainers rather than guess. No legal advice is offered here beyond pointing at the discrepancy.

On maintenance, the repository is not archived and the last push was on 2026-10-16, with SmartBugs 2.2.0 released on 2026-10-15 and 2.1.6 and 2.1.5 in the preceding week. The framework is being worked on.

Editorial conclusion

SmartBugs is a good fit for a security team that wants to compare several analysers on the same contract rather than trusting one tool's verdict, because the uniform interface, the standardised output and the SARIF export make a multi-tool run something you can act on rather than a pile of incompatible reports. It is a poor fit for a team that wants a single fast check in a pull request, since every tool runs in a container and the framework is not a linter, and a poor fit if you cannot run Docker. Before adopting, read the tool table rather than the feature list, because the framework warns that alongside maintained tools it also offers unmaintained academic research prototypes which may be incompatible with current Solidity and EVM versions, and check the licence question, since the repository badge says Apache-2.0 while the package metadata says MIT.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. smartbugs/smartbugs on GitHub