{"id":13631900,"url":"https://github.com/FuzzingLabs/thoth","last_synced_at":"2025-04-18T01:32:16.700Z","repository":{"id":46242560,"uuid":"505834193","full_name":"FuzzingLabs/thoth","owner":"FuzzingLabs","description":"Cairo/Starknet security toolkit (bytecode analyzer, disassembler, decompiler, symbolic execution, SBMC)","archived":false,"fork":false,"pushed_at":"2023-11-13T18:07:00.000Z","size":5893,"stargazers_count":240,"open_issues_count":8,"forks_count":21,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-08-01T22:50:48.838Z","etag":null,"topics":["analysis","cairo-lang","callflow","cfg","decompiler","disassembler","reversing","security","sierra","starknet","symbolic-execution"],"latest_commit_sha":null,"homepage":"https://fuzzinglabs.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FuzzingLabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-06-21T12:30:07.000Z","updated_at":"2024-07-25T15:55:37.000Z","dependencies_parsed_at":"2024-01-21T20:14:00.208Z","dependency_job_id":null,"html_url":"https://github.com/FuzzingLabs/thoth","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FuzzingLabs%2Fthoth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FuzzingLabs%2Fthoth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FuzzingLabs%2Fthoth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FuzzingLabs%2Fthoth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FuzzingLabs","download_url":"https://codeload.github.com/FuzzingLabs/thoth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223772097,"owners_count":17199967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analysis","cairo-lang","callflow","cfg","decompiler","disassembler","reversing","security","sierra","starknet","symbolic-execution"],"created_at":"2024-08-01T22:02:43.307Z","updated_at":"2024-11-09T00:30:23.706Z","avatar_url":"https://github.com/FuzzingLabs.png","language":"Python","funding_links":[],"categories":["Python","Additional developer resources","Tools"],"sub_categories":[],"readme":"# Thoth, the Cairo/Starknet security toolkit (analyzer, disassembler and decompiler)\n\u003cimg src =\"https://img.shields.io/badge/python-3.10-blue.svg\"/\u003e\n\nThoth (pronounced \"taut\" or \"toss\") is a Cairo/Starknet security toolkit including analyzers, disassemblers \u0026 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](/sierra/README.md) or Cairo/Starknet compilation artifact. It also includes some really advanced tools like a Symbolic execution engine and Symbolic bounded model checker.\n\nLearn more about Thoth internals here: [Demo video](https://www.youtube.com/watch?v=T0KvG8Zps6I), [StarkNetCC 2022 slides](https://fuzzinglabs.com/wp-content/uploads/2022/11/Thoth_cairo_analyzer_starknetcc_lisbon_2022.pdf)\n\n## Features\n- **Remote \u0026 Local**: Thoth can both analyze contracts deployed on Mainnet/Goerli and compiled locally on your machine. \n- **[Decompiler](#decompile-the-contracts-compilation-artifact-json)**: Thoth can convert assembly into decompiled code with SSA (Static Single Assignment)  \n- **[Call Flow analysis](#print-the-contracts-call-graph)**: Thoth can generate a **Call Flow Graph** \n- **[Static analysis](#run-the-static-analysis)**: Thoth can run various **analyzers** of different types (*security*/*optimization*/*analytics*) on the contract\n- **[Symbolic execution](#use-the-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.\n- **[Data Flow analysis](#print-the-contracts-data-flow-graph-dfg)**: Thoth can generate a **Data Flow Graph** (DFG) for each function\n- **[Disassembler](#disassemble-the-contracts-compilation-artifact-json)**: Thoth can translate bytecode into assembly representation\n- **[Control Flow analysis](#print-the-contracts-control-flow-graph-cfg)**: Thoth can generate a **Control Flow Graph** (CFG)\n- **[Cairo Fuzzer inputs generation](#generate-inputs-for-the-cairo-fuzzer)**: Thoth can generate inputs for the  [**Cairo fuzzer**](https://github.com/FuzzingLabs/cairo-fuzzer)\n- **[Sierra files analysis](/sierra/README.md)** : Thoth can analyze **Sierra** files \n- **[Sierra files symbolic execution](/doc/symbolic_execution.md)** : Thoth allows **symbolic execution** on sierra files\n- **[Symbolic bounded model checker](/doc/symbolic_bounded_model_checker_sierra.md)** : Thoth can be used as a **Symbolic bounded model checker**\n\n## Installation\n \n```\nsudo apt install graphviz\ngit clone https://github.com/FuzzingLabs/thoth \u0026\u0026 cd thoth\npip install .\nthoth -h\n```\n\n## Decompile the contract's compilation artifact (JSON)\n\n``` python\n# Remote contrat deployed on starknet (mainnet/goerli)\nthoth remote --address 0x0323D18E2401DDe9aFFE1908e9863cbfE523791690F32a2ff6aa66959841D31D --network mainnet -d\n# Local contract compiled locally (JSON file)\nthoth local tests/json_files/cairo_0/cairo_test_addition_if.json -d\n```\n\nExample 1 with strings:\n\u003cp align=\"center\"\u003e\n\t\u003cb\u003e source code \u003c/b\u003e\u003c/br\u003e\n\t\u003cimg src=\"/doc/images/thoth/thoth_decompile_sourcecode.png\"/\u003e\u003c/br\u003e\n\t\u003cb\u003e decompiler code \u003c/b\u003e\u003c/br\u003e\n\t\u003cimg src=\"/doc/images/thoth/thoth_decompile.png\"/\u003e\u003c/br\u003e\n\u003c/p\u003e\nExample 2 with function call:\n\u003cp align=\"center\"\u003e\n\t\u003cb\u003e source code \u003c/b\u003e\u003c/br\u003e\n\t\u003cimg src=\"/doc/images/thoth/thoth_decompile_sourcecode_2.png\"/\u003e\u003c/br\u003e\n\t\u003cb\u003e decompiler code \u003c/b\u003e\u003c/br\u003e\n\t\u003cimg src=\"/doc/images/thoth/thoth_decompile_2.png\"/\u003e\u003c/br\u003e\n\u003c/p\u003e\n\n\n## Print the contract's call graph \n\nThe 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.\n\n``` python\nthoth local tests/json_files/cairo_0/cairo_array_sum.json -call -view\n# For a specific output format (pdf/svg/png):\nthoth local tests/json_files/cairo_0/cairo_array_sum.json -call -view -format png\n```\nThe output file (pdf/svg/png) and the dot file are inside the `output-callgraph` folder.\nIf needed, you can also visualize dot files online using [this](https://dreampuf.github.io/GraphvizOnline/) website. The legend can be found [here](images/callgraph_legend.png).\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"/doc/images/thoth/thoth_callgraph_simple.png\"/\u003e\n\u003c/p\u003e\n\nA more complexe callgraph:\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"/doc/images/thoth/starknet_get_full_contract_l2_dai_bridge.gv.png\"/\u003e\n\u003c/p\u003e\n\n## Run the static analysis\n\nThe static analysis is performed using *analyzers* which can be either informative or security/optimization related.\n\n|Analyzer|Command-Line argument|Description|Impact|Precision|Category|Bytecode|Sierra|\n|---|---|---|---|---|---|---|---|\n|**ERC20**|`erc20`|Detect if a contract is an ERC20 Token|Informational|High|Analytics|✔️|❌|\n|**ERC721**|`erc721`|Detect if a contract is an ERC721 Token|Informational|High|Analytics|✔️|❌|\n|**Strings**|`strings`|Detect strings inside a contract|Informational|High|Analytics|✔️|✔️|\n|**Functions**|`functions`|Retrieve informations about the contract's functions|Informational|High|Analytics|✔️|✔️|\n|**Statistics**|`statistics`|General statistics about the contract|Informational|High|Analytics|✔️|✔️|\n|**Test cases generator**|`tests`|Automatically generate test cases for each function of the contract|Informational|High|Analytics|✔️|❌|\n|**Assignations**|`assignations`|List of variables assignations|Informational|High|Optimization|✔️|❌|\n|**Integer overflow**|`int_overflow`|Detect direct integer overflow/underflow|High (direct) / Medium (indirect)|Medium|Security|✔️|✔️|\n|**Function naming**|`function_naming`|Detect functions names that are not in snake case|Informational|High|Security|✔️|❌|\n|**Variable naming**|`variable_naming`|Detect variables names that are not in snake case|Informational|High|Security|✔️|❌|\n|**Delegate calls detector**|`delegate_call`|Detect delegate calls|Informational|High|Security|❌|✔️|\n|**Dead code detector**|`dead_code`|Detect dead code|Informational|High|Security|❌|✔️|\n|**Unused arguments detector**|`unused_arguments`|Detect unused arguments|Informational|High|Security|❌|✔️|\n|**User defined function call detector**|`user_defined`|Detect calls of user defined functions|Informational|High|Security|❌|✔️|\n\n#### Run all the analyzers\n``` python\nthoth local tests/json_files/cairo_0/cairo_array_sum.json -a\n```\n\n#### Selects which analyzers to run\n``` python\nthoth local tests/json_files/cairo_0/cairo_array_sum.json -a erc20 erc721\n```\n\n#### Only run a specific category of analyzers\n``` python\nthoth local tests/json_files/cairo_0/cairo_array_sum.json -a security\nthoth local tests/json_files/cairo_0/cairo_array_sum.json -a optimization\nthoth local tests/json_files/cairo_0/cairo_array_sum.json -a analytics\n```\n\n#### Print a list of all the available analyzers\n```\nthoth local tests/json_files/cairo_0/cairo_array_sum.json --analyzers-help\n```\n\n## Use the symbolic execution \n\nYou can find a detailed documentation for the symbolic execution [here](https://github.com/FuzzingLabs/thoth/blob/master/doc/symbolic_execution.md).\n\n## Print the contract's data-flow graph (DFG)\n\n``` python\nthoth local tests/json_files/cairo_0/cairo_double_function_and_if.json -dfg -view\n# For a specific output format (pdf/svg/png):\nthoth local tests/json_files/cairo_0/cairo_double_function_and_if.json -dfg -view -format png\n# For tainting visualization:\nthoth remote --address 0x069e40D2c88F479c86aB3E379Da958c75724eC1d5b7285E14e7bA44FD2f746A8 -n mainnet  -dfg -view --taint\n```\nThe output file (pdf/svg/png) and the dot file are inside the `output-dfg` folder.\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"/doc/images/thoth/thoth_dataflow_graph.png\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"/doc/images/thoth/thoth_dfg_tainting.png\"/\u003e\n\u003c/p\u003e\n\n## Disassemble the contract's compilation artifact (JSON)\n\n``` python\n# Remote contrat deployed on starknet (mainnet/goerli)\nthoth remote --address 0x0323D18E2401DDe9aFFE1908e9863cbfE523791690F32a2ff6aa66959841D31D --network mainnet -b\n# Local contract compiled locally (JSON file)\nthoth local tests/json_files/cairo_0/cairo_array_sum.json -b\n# To get a pretty colored version:\nthoth local tests/json_files/cairo_0/cairo_array_sum.json -b -color\n# To get a verbose version with more details about decoded bytecodes:\nthoth local tests/json_files/cairo_0/cairo_array_sum.json -vvv\n```\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"/doc/images/thoth/thoth_disas_color.png\"/\u003e\n\u003c/p\u003e\n\n## Print the contract's control-flow graph (CFG)\n\n``` python\nthoth local tests/json_files/cairo_0/cairo_double_function_and_if.json -cfg -view\n# For a specific function:\nthoth local tests/json_files/cairo_0/cairo_double_function_and_if.json -cfg -view -function \"__main__.main\"\n# For a specific output format (pdf/svg/png):\nthoth local tests/json_files/cairo_0/cairo_double_function_and_if.json -cfg -view -format png\n```\nThe output file (pdf/svg/png) and the dot file are inside the `output-cfg` folder.\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"/doc/images/thoth/cairo_double_function_and_if_cfg.png\"/\u003e\n\u003c/p\u003e\n\n## Generate inputs for the Cairo fuzzer\n\nYou can generate inputs for the [Cairo fuzzer](https://github.com/FuzzingLabs/cairo-fuzzer) using this command\n\n```\nthoth local ./tests/json_files/cairo_0/cairo_test_symbolic_execution_2.json -a fuzzer\n```\n\n# F.A.Q\n\n## How to find a Cairo/Starknet compilation artifact (json file)?\n\nThoth 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`.\n\n## How to run the tests?\n\n```\npython3 tests/test.py\n```\n\n## How to build the documentation?\n\n``` python\n# Install sphinx\napt-get install python3-sphinx\n\n#Create the docs folder\nmkdir docs \u0026 cd docs\n\n#Init the folder\nsphinx-quickstart docs\n\n#Modify the `conf.py` file by adding\nimport thoth\n\n#Generate the .rst files before the .html files\nsphinx-apidoc -f -o . ..\n\n#Generate the .html files\nmake html\n\n#Run a python http server\ncd _build/html; python3 -m http.server\n```\n\n## Why my bytecode is empty?\n\nFirst, verify that your JSON is correct and that it contains a data section.\nSecond, verify that your JSON is not a contract interface.\nFinally, it is possible that your contract does not generate bytecodes, for example:\n\n``` cairo\n%lang starknet\n\nfrom starkware.cairo.common.cairo_builtins import HashBuiltin\n\n@storage_var\nfunc balance() -\u003e (res : felt):\nend\n```\n\n# Acknowledgments\n\nThoth is inspired by a lot of different security tools developed by friends such as: [Octopus](https://github.com/FuzzingLabs/octopus), [Slither](https://github.com/crytic/slither), [Mythril](https://github.com/ConsenSys/mythril), etc.\n\n# License\n\nThoth is licensed and distributed under the AGPLv3 license. [Contact us](mailto:contact@fuzzinglabs.com) if you're looking for an exception to the terms.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFuzzingLabs%2Fthoth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFuzzingLabs%2Fthoth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFuzzingLabs%2Fthoth/lists"}