Skip to content

Cairo/Starknet security toolkit (bytecode analyzer, disassembler, decompiler, symbolic execution, SBMC)

License

Notifications You must be signed in to change notification settings

FuzzingLabs/thoth

Repository files navigation

Thoth, the Cairo/Starknet security toolkit (analyzer, disassembler and decompiler)

Thoth (pronounced "taut" or "toss") is a Cairo/Starknet security toolkit including analyzers, disassemblers & decompilers written in Python 3. Thoth's features include the generation of the call graph, the control-flow graph (CFG) and the data-flow graph for a given Sierra file or Cairo/Starknet compilation artifact. It also includes some really advanced tools like a Symbolic execution engine and Symbolic bounded model checker.

Learn more about Thoth internals here: Demo video, StarkNetCC 2022 slides

Features

Installation

sudo apt install graphviz
git clone https://github.com/FuzzingLabs/thoth && cd thoth
pip install .
thoth -h

Decompile the contract's compilation artifact (JSON)

# Remote contrat deployed on starknet (mainnet/goerli)
thoth remote --address 0x0323D18E2401DDe9aFFE1908e9863cbfE523791690F32a2ff6aa66959841D31D --network mainnet -d
# Local contract compiled locally (JSON file)
thoth local tests/json_files/cairo_0/cairo_test_addition_if.json -d

Example 1 with strings:

source code

decompiler code

Example 2 with function call:

source code

decompiler code

Print the contract's call graph

The call flow graph represents calling relationships between functions of the contract. We tried to provide a maximum of information, such as the entry-point functions, the imports, decorators, etc.

thoth local tests/json_files/cairo_0/cairo_array_sum.json -call -view
# For a specific output format (pdf/svg/png):
thoth local tests/json_files/cairo_0/cairo_array_sum.json -call -view -format png

The output file (pdf/svg/png) and the dot file are inside the output-callgraph folder. If needed, you can also visualize dot files online using this website. The legend can be found here.

A more complexe callgraph:

Run the static analysis

The static analysis is performed using analyzers which can be either informative or security/optimization related.

Analyzer Command-Line argument Description Impact Precision Category Bytecode Sierra
ERC20 erc20 Detect if a contract is an ERC20 Token Informational High Analytics ✔️
ERC721 erc721 Detect if a contract is an ERC721 Token Informational High Analytics ✔️
Strings strings Detect strings inside a contract Informational High Analytics ✔️ ✔️
Functions functions Retrieve informations about the contract's functions Informational High Analytics ✔️ ✔️
Statistics statistics General statistics about the contract Informational High Analytics ✔️ ✔️
Test cases generator tests Automatically generate test cases for each function of the contract Informational High Analytics ✔️
Assignations assignations List of variables assignations Informational High Optimization ✔️
Integer overflow int_overflow Detect direct integer overflow/underflow High (direct) / Medium (indirect) Medium Security ✔️ ✔️
Function naming function_naming Detect functions names that are not in snake case Informational High Security ✔️
Variable naming variable_naming Detect variables names that are not in snake case Informational High Security ✔️
Delegate calls detector delegate_call Detect delegate calls Informational High Security ✔️
Dead code detector dead_code Detect dead code Informational High Security ✔️
Unused arguments detector unused_arguments Detect unused arguments Informational High Security ✔️
User defined function call detector user_defined Detect calls of user defined functions Informational High Security ✔️

Run all the analyzers

thoth local tests/json_files/cairo_0/cairo_array_sum.json -a

Selects which analyzers to run

thoth local tests/json_files/cairo_0/cairo_array_sum.json -a erc20 erc721

Only run a specific category of analyzers

thoth local tests/json_files/cairo_0/cairo_array_sum.json -a security
thoth local tests/json_files/cairo_0/cairo_array_sum.json -a optimization
thoth local tests/json_files/cairo_0/cairo_array_sum.json -a analytics

Print a list of all the available analyzers

thoth local tests/json_files/cairo_0/cairo_array_sum.json --analyzers-help

Use the symbolic execution

You can find a detailed documentation for the symbolic execution here.

Print the contract's data-flow graph (DFG)

thoth local tests/json_files/cairo_0/cairo_double_function_and_if.json -dfg -view
# For a specific output format (pdf/svg/png):
thoth local tests/json_files/cairo_0/cairo_double_function_and_if.json -dfg -view -format png
# For tainting visualization:
thoth remote --address 0x069e40D2c88F479c86aB3E379Da958c75724eC1d5b7285E14e7bA44FD2f746A8 -n mainnet  -dfg -view --taint

The output file (pdf/svg/png) and the dot file are inside the output-dfg folder.

Disassemble the contract's compilation artifact (JSON)

# Remote contrat deployed on starknet (mainnet/goerli)
thoth remote --address 0x0323D18E2401DDe9aFFE1908e9863cbfE523791690F32a2ff6aa66959841D31D --network mainnet -b
# Local contract compiled locally (JSON file)
thoth local tests/json_files/cairo_0/cairo_array_sum.json -b
# To get a pretty colored version:
thoth local tests/json_files/cairo_0/cairo_array_sum.json -b -color
# To get a verbose version with more details about decoded bytecodes:
thoth local tests/json_files/cairo_0/cairo_array_sum.json -vvv

Print the contract's control-flow graph (CFG)

thoth local tests/json_files/cairo_0/cairo_double_function_and_if.json -cfg -view
# For a specific function:
thoth local tests/json_files/cairo_0/cairo_double_function_and_if.json -cfg -view -function "__main__.main"
# For a specific output format (pdf/svg/png):
thoth local tests/json_files/cairo_0/cairo_double_function_and_if.json -cfg -view -format png

The output file (pdf/svg/png) and the dot file are inside the output-cfg folder.

Generate inputs for the Cairo fuzzer

You can generate inputs for the Cairo fuzzer using this command

thoth local ./tests/json_files/cairo_0/cairo_test_symbolic_execution_2.json -a fuzzer

F.A.Q

How to find a Cairo/Starknet compilation artifact (json file)?

Thoth supports cairo and starknet compilation artifact (json file) generated after compilation using cairo-compile or starknet-compile. Thoth also supports the json file returned by: starknet get_full_contract.

How to run the tests?

python3 tests/test.py

How to build the documentation?

# Install sphinx
apt-get install python3-sphinx

#Create the docs folder
mkdir docs & cd docs

#Init the folder
sphinx-quickstart docs

#Modify the `conf.py` file by adding
import thoth

#Generate the .rst files before the .html files
sphinx-apidoc -f -o . ..

#Generate the .html files
make html

#Run a python http server
cd _build/html; python3 -m http.server

Why my bytecode is empty?

First, verify that your JSON is correct and that it contains a data section. Second, verify that your JSON is not a contract interface. Finally, it is possible that your contract does not generate bytecodes, for example:

%lang starknet

from starkware.cairo.common.cairo_builtins import HashBuiltin

@storage_var
func balance() -> (res : felt):
end

Acknowledgments

Thoth is inspired by a lot of different security tools developed by friends such as: Octopus, Slither, Mythril, etc.

License

Thoth is licensed and distributed under the AGPLv3 license. Contact us if you're looking for an exception to the terms.