{"id":13630705,"url":"https://github.com/nevillegrech/gigahorse-toolchain","last_synced_at":"2025-04-17T17:31:49.648Z","repository":{"id":39628755,"uuid":"140270526","full_name":"nevillegrech/gigahorse-toolchain","owner":"nevillegrech","description":"A binary lifter and analysis framework for Ethereum smart contracts","archived":false,"fork":false,"pushed_at":"2025-04-10T13:03:03.000Z","size":29059,"stargazers_count":322,"open_issues_count":9,"forks_count":64,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-10T14:46:13.843Z","etag":null,"topics":["blockchain-technology","decompiler","ethereum","framework","security-tools"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nevillegrech.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-09T10:35:25.000Z","updated_at":"2025-04-10T08:56:57.000Z","dependencies_parsed_at":"2023-09-30T08:44:13.812Z","dependency_job_id":"e2f73c74-88bb-4544-99be-bfe8340815d5","html_url":"https://github.com/nevillegrech/gigahorse-toolchain","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevillegrech%2Fgigahorse-toolchain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevillegrech%2Fgigahorse-toolchain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevillegrech%2Fgigahorse-toolchain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevillegrech%2Fgigahorse-toolchain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nevillegrech","download_url":"https://codeload.github.com/nevillegrech/gigahorse-toolchain/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249360009,"owners_count":21257149,"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":["blockchain-technology","decompiler","ethereum","framework","security-tools"],"created_at":"2024-08-01T22:01:56.293Z","updated_at":"2025-04-17T17:31:45.990Z","avatar_url":"https://github.com/nevillegrech.png","language":"HTML","funding_links":[],"categories":["HTML","Tools"],"sub_categories":[],"readme":"*NOTE*: you need to clone this repo using the `--recursive` flag since this repo has submodules, e.g., `git clone git@github.com:nevillegrech/gigahorse-toolchain.git --recursive`\n\n# The Gigahorse binary lifter and toolchain [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Gigahorse%20-%20Decompilation%20and%20Analysis%20for%20Ethereum%20Smart%20Contracts\u0026url=https://www.github.com/nevillegrech/gigahorse-toolchain)\nA binary lifter (and related framework) from low-level EVM code to a higher-level function-based three-address representation, similar to LLVM IR or Jimple. \n\n## Quickstart\n\n### Running/Installing Gigahorse from local clone (requires `souffle`)\nOur dependencies installation [Dockerfile](docker/dependencies/souffle24/Dockerfile) can be used as a reference for installing the dependencies of Gigahorse on a debian-based system. The Dockerfile also includes the instructions to build `souffle` 2.4.1 from source.\n\nIn summary, you need to have the following things installed on your system:\n\n- Boost libraries, required for [souffle-addon](https://github.com/plast-lab/souffle-addon) (Can be installed on Debian with `apt install libboost-all-dev`)\n\n- Z3, required for [souffle-addon](https://github.com/plast-lab/souffle-addon) (Can be installed on Debian with `apt install libz3-dev`)\n\n- Python 3.10 (Refer to standard documentation)\n\n- Souffle 2.3 or 2.4.1 (We only test using the release versions, later development versions may work but are untested by us. The easiest way to install this is to use the release from https://github.com/souffle-lang/souffle/releases/tag/2.4.1). Refer to the Souffle [documentation](https://souffle-lang.github.io) for more information.\n\nNow install the Souffle custom functors:\n\n```\n# builds all, sets libfunctors.so as a link to libsoufflenum.so\ncd souffle-addon \u0026\u0026 make WORD_SIZE=$(souffle --version | sed -n 3p | cut -c12,13)\n```\n\nYou should now be ready to run Gigahorse.\n\n### Installing Gigahorse via docker\n\nAlternatively, you can use Gigahorse via our pre-built docker images using the following instructions:\n1. For amd64:\n   ```\n   curl -s -L https://raw.githubusercontent.com/nevillegrech/gigahorse-toolchain/master/scripts/docker/install/install_amd64 | bash\n   ```\n\n   For arm64/m1 (not actively tested):\n   ```\n   curl -s -L https://raw.githubusercontent.com/nevillegrech/gigahorse-toolchain/master/scripts/docker/install/install_arm64 | bash\n   ```\n2. Then ```source ~/.bashrc```\n\n3. Check if gigahorse is available using ```gigahorse --help```\n\n## Running Gigahorse\nThe `gigahorse.py` script can be run on a contract individually or on a collection of contract bytecode files in specified directory, and it will run the binary lifter implemented in `logic/main.dl` on each contract, optionally followed by any additional client analyses specified by the user using the `-C` flag.\n\nThe default pipeline first attempts to decompile a contract using a **shrinking** context-sensitivity configuration. If that times out it performs a second attempt with the _scalable-fallback_ configuration (using a **finite-precise** context sensitivity algorithm, tuned for scalability). The _scalable-fallback_ configuration can be disabled if needed using the `--disable_scalable_fallback` flag.\n\nThe Gigahorse pipeline also includes a few rounds of inlining of small functions in order to help the subsequent client libraries get more high-level inferences. The inlining functionality can be disabled with `--disable_inline`.\n\nThe expected file format for each contract is in .hex format.\n\nExample (individual contract):\n\n```\n./gigahorse.py examples/long_running.hex\n```\n\n(For some Souffle versions, you will get an error message regarding the `libsoufflenum.so` dynamic library, during the first compilation. You can ignore this and gigahorse.py should work upon a re-run.)\n\nContracts that take too long to analyse will be skipped after a configurable timeout.\n\nThe decompilation results are placed in the directory `.temp`, whereas metadata about the execution, e.g., metrics are placed in a `results.json` file, as a list of triples in the form:\n\n```[filename, properties, flags]```\n\nHere, `properties` is a list of the detected issues with the contract in filename,\nwhere any output relations in the datalog files that are non-empty will have their\nrelation name placed in this list.\n`flags` is a list indicating auxiliary or exceptional information. It may include\n`\"ERROR\"` and `\"TIMEOUT\"`, which are self-explanatory.\n\n`gigahorse.py --help` for invocation instructions.\n\n\nExample (with client analysis):\n\n ```\n./gigahorse.py  -j \u003cnumber of jobs\u003e -C clients/visualizeout.py \u003ccontracts\u003e\n```\n\n(The clients following the `-C` flag can be a comma-separated list, with no spaces, of path-reachable or fully-qualified filenames.)\n\nGigahorse can also be used in \"bulk analysis\" mode, by replacing \u003ccontracts\u003e by a directory filled with contracts.\n\nFor additional instructions in tuning the Gigahorse framework see [Advanced.md](Advanced.md).\n\n\n## Textual representation of the lifted IR\nClient analysis `clients/visualizeout.py` can be used to provide a pretty-printed textual representation of the IR produced by Gigahorse.\nThe pretty-printed text file is named `contract.tac` and will be placed in the `out/` folder for each analyzed contract.\nFor example the output for `./gigahorse.py -C clients/visualizeout.py examples/long_running.hex` will be placed in `.temp/long_running/out/contract.tac`.\n\nA block visualized in `contract.tac` looks like:\n```\n    Begin block 0x3e\n    prev=[0xb], succ=[0x10ee, 0x49]\n    =================================\n    0x3f: v3f(0xf42fdfb) = CONST \n    0x44: v44 = EQ v3f(0xf42fdfb), v32\n    0x10c7: v10c7(0x10ee) = CONST \n    0x10c8: JUMPI v10c7(0x10ee), v44\n```\n\nKeep in mind that the pretty-printed variable identifiers do not correspond to their identifiers in the underlying datalog facts.\n\n\n## Writing client analyses\n\nClient analyses can be written in any language by reading the relational files that are written by the decompilation step (`main.dl`). This framework however provides preferential treatment for clients written in Datalog. The most notable example of client analysis for the Gigahorse framework is [MadMax](https://github.com/nevillegrech/MadMax). This uses several of the \"analysis client libraries\" under [clientlib](https://github.com/nevillegrech/gigahorse-toolchain/tree/master/clientlib). These libraries include [customizable dataflow analysis](clientlib/flows.dl), [memory modeling](clientlib/memory_modeling/README.md), [data structure reconstruction](clientlib/storage_modeling/storage_modeling.dl) and others.\n\nA common template for client analyses for decompiled bytecode is to create souffle datalog file that includes `clientlib/decompiler_imports.dl`, for instance:\n```\n#include \"clientlib/decompiler_imports.dl\"\n\n.output ...\n```\n\n\n## Uses of Gigahorse\nThe Gigahorse toolchain was originally published as:\n\n- Grech, N., Brent, L., Scholz, B., Smaragdakis, Y. (2019), Gigahorse: Thorough, Declarative Decompilation of Smart Contracts. *In 41st ACM/IEEE International Conference on Software Engineering.*\n\nSeveral novel developments to Gigahorse after the original publication have been published as:\n\n- Grech, N., Lagouvardos, S., Tsatiris, I., Smaragdakis, Y. (2022), Elipmoc: Advanced Decompilation of Ethereum Smart Contracts *Proceedings of the ACM in Programming Languages (OOPSLA).*\n\nThe analysis of EVM \"memory\" operations (`SHA3`, `xCALL`, `LOGx`, etc.) that is [bundled with Gigahorse](clientlib/memory_modeling/README.md) was published as:\n\n-  Lagouvardos, S., Grech, N., Tsatiris, I., Smaragdakis, Y. (2020) Precise Static Modelling of Ethereum \"Memory\". *Proceedings of the ACM in Programming Languages (OOPSLA).*\n\nIn addition, other research tools have been developed on top of Gigahorse, including:\n\n-  Grech, N., Kong, M., Jurisevic, A., Brent, L., Scholz, B., Smaragdakis, Y. (2018), MadMax: Surviving Out-of-Gas Conditions in Ethereum Smart Contracts. *Proceedings of the ACM on Programming Languages (OOPSLA).*\n\n-  Brent, L., Grech, N., Lagouvardos, S., Scholz, B., Smaragdakis, Y. (2020), Ethainter: A Smart Contract Security Analyzer for Composite Vulnerabilities.\n*In 41st ACM SIGPLAN Conference on Programming Language Design and Implementation.*\n\n-  Grech, N., Kong, M., Jurisevic, A., Brent, L., Scholz, B., Smaragdakis, Y. (2020),  Analyzing the Out-of-Gas World of Smart Contracts. *Communications of the ACM.*\n\n- Smaragdakis, Y., Grech, N., Lagouvardos, S., Triantafyllou, K., Tsatiris, I. (2021), Symbolic Value-Flow Static Analysis: Deep, Precise, Complete Modeling of Ethereum Smart Contracts. *Proceedings of the ACM in Programming Languages (OOPSLA).*\n\n  \n\n\n\nThe Gigahorse framework also underpins the realtime decompiler and analysis tool at [app.dedaub.com](https://app.dedaub.com).\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnevillegrech%2Fgigahorse-toolchain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnevillegrech%2Fgigahorse-toolchain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnevillegrech%2Fgigahorse-toolchain/lists"}