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

Important

This repository is no longer maintained. If you have any questions or need further assistance, please contact FuzzingLabs.

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

• Remote & Local: Thoth can both analyze contracts deployed on Mainnet/Goerli and compiled locally on your machine.
• Decompiler: Thoth can convert assembly into decompiled code with SSA (Static Single Assignment)
• Call Flow analysis: Thoth can generate a Call Flow Graph
• Static analysis: Thoth can run various analyzers of different types (security/optimization/analytics) on the contract
• Symbolic execution: Thoth can use the symbolic execution to find the right variables values to get through a specific path in a function and also automatically generate test cases for a function.
• Data Flow analysis: Thoth can generate a Data Flow Graph (DFG) for each function
• Disassembler: Thoth can translate bytecode into assembly representation
• Control Flow analysis: Thoth can generate a Control Flow Graph (CFG)
• Cairo Fuzzer inputs generation: Thoth can generate inputs for the Cairo fuzzer
• Sierra files analysis : Thoth can analyze Sierra files
• Sierra files symbolic execution : Thoth allows symbolic execution on sierra files
• Symbolic bounded model checker : Thoth can be used as a Symbolic bounded model checker
• Use it with a Scarb project : Thoth can be used in a project created with the Scarb toolchain

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)thothremote--address0x0323D18E2401DDe9aFFE1908e9863cbfE523791690F32a2ff6aa66959841D31D--networkmainnet-d# Local contract compiled locally (JSON file)thothlocaltests/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.

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

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

thothlocaltests/json_files/cairo_0/cairo_array_sum.json-a

Selects which analyzers to run

thothlocaltests/json_files/cairo_0/cairo_array_sum.json-aerc20erc721

Only run a specific category of analyzers

thothlocaltests/json_files/cairo_0/cairo_array_sum.json-asecuritythothlocaltests/json_files/cairo_0/cairo_array_sum.json-aoptimizationthothlocaltests/json_files/cairo_0/cairo_array_sum.json-aanalytics

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)

thothlocaltests/json_files/cairo_0/cairo_double_function_and_if.json-dfg-view# For a specific output format (pdf/svg/png):thothlocaltests/json_files/cairo_0/cairo_double_function_and_if.json-dfg-view-formatpng# For tainting visualization:thothremote--address0x069e40D2c88F479c86aB3E379Da958c75724eC1d5b7285E14e7bA44FD2f746A8-nmainnet-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)thothremote--address0x0323D18E2401DDe9aFFE1908e9863cbfE523791690F32a2ff6aa66959841D31D--networkmainnet-b# Local contract compiled locally (JSON file)thothlocaltests/json_files/cairo_0/cairo_array_sum.json-b# To get a pretty colored version:thothlocaltests/json_files/cairo_0/cairo_array_sum.json-b-color# To get a verbose version with more details about decoded bytecodes:thothlocaltests/json_files/cairo_0/cairo_array_sum.json-vvv

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

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

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

Use it with a Scarb project

Add these lines to your Scarb.toml :

[[target.starknet-contract]]sierra = truecasm = true

Then build the project using Scarb :

scarb build

You can now run Thoth with the --scarb flag :

// Run the disassembler
thoth local --scarb -b
// Run the analyzer
thoth local --scarb -a
// Generate the control-flow graph
thoth local --scarb --cfg
// Generate the callgraph
thoth local --scarb --call

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 sphinxapt-getinstallpython3-sphinx#Create the docs foldermkdirdocs&cddocs#Init the foldersphinx-quickstartdocs#Modify the `conf.py` file by addingimportthoth#Generate the .rst files before the .html filessphinx-apidoc-f-o . ..
#Generate the .html filesmakehtml#Run a python http servercd_build/html; python3-mhttp.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:

%langstarknetfromstarkware.cairo.common.cairo_builtins importHashBuiltin@storage_varfuncbalance() -> (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.