regast

[!WARNING] regast has not been maintained since March 2023. If you're trying to run it, it will most probably throw an error during the parsing stage.

Nevertheless, feel free to look through the code to get an idea of how to implement your own static analyzer.

regast is a static analyzer for identifying security vulnerabilities and gas optimizations in Solidity codebases.

It is heavily inspired by tools such as Slither, solstat and 4naly3er, but has the following differences:

• No compilation: regast is able to run directly without compilation, making it viable for codebases that are difficult to compile.
• Easy to customize: regast is designed for users to easily write and run their own custom detectors.

Table of Contents

• regast
  • Table of Contents
  • Installation
  • Usage
  • Detectors
    • Included detectors
    • Writing custom detectors
  • Sample Reports
  • Implementation
    • Repository structure

Installation

regast requires Python 3.10 or above.

First, clone this repository and its submodules:

git clone --recurse-submodules https://github.com/MiloTruck/regast.git
cd regast

Install regast using either pip or setuptools:

# Using pip
pip3 install .

# Using setuptools
python3 setup.py install

After installation, the repository can be deleted:

cd ..
rm -r regast

Usage

The regast command can be used on either .sol file or a folder containing Solidity files:

$ regast --help
usage: __main__.py [-h] [-d <detector>] [-c <classifications>] [-s <scope>] [-r <filename>] <contract>

Scan for vulnerabilities based on regex or AST queries.

positional arguments:
  <contract>            .sol file or folder containing .sol files to scan

options:
  -h, --help            show this help message and exit
  -d <detector>, --detectors <detector>
                        .py file or folder containing .py files which implement detectors
  -c <classifications>, --classifications <classifications>
                        Comma-separated list of classifications: GAS, NC, LOW, MEDIUM, HIGH
  -s <scope>, --scope <scope>
                        Text file containing a list of contracts in scope
  -r <filename>, --report <filename>
                        Generate a markdown report in <filename>.md

Detectors

Included detectors

Below are the currently implemented detectors which regast runs by default. Most of the detectors from 4naly3er and solstat will be included in the future.

Writing custom detectors

For information on how to write custom detectors, please refer to docs/writing-custom-detectors.md.

Sample Reports

regast is able to generate markdown reports with the issues found. For an example, please refer to the following sample reports:

• Llama Report
• Juicebox Report

Implementation

regast is built on top of tree-sitter-python, which provides Python bindings for the tree-sitter parsing library. The grammar for Solidity is taken from tree-sitter-solidity.

tree-sitter first converts Solidity source code into multiple abstract syntax trees (AST). regast then parses each node in these ASTs into corresponding Python classes. After the parsing is completed, individual detectors query the AST through these Python classes to identify common vulnerability patterns.

Repository structure

Most of regast's code are in the following directories:

• regast/core contains Python classes which represents parts of the AST.
• regast/detectors contains detectors which regast runs by default.
• regast/parsing contains the logic for parsing the AST from tree-sitter into Python classes.