{"id":13760165,"url":"https://github.com/agustingianni/retools","last_synced_at":"2025-05-10T10:31:52.213Z","repository":{"id":66966857,"uuid":"99044630","full_name":"agustingianni/retools","owner":"agustingianni","description":"retools: a reverse engineering toolkit for normies","archived":false,"fork":false,"pushed_at":"2017-12-28T14:48:57.000Z","size":17700,"stargazers_count":85,"open_issues_count":0,"forks_count":8,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-11-16T17:41:02.718Z","etag":null,"topics":["arm","armv7","armv8","binary","disassembler","disassembly","emulator","engineering","framework","macho","re","research","reverse","vulndev","vulnerability"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agustingianni.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":"2017-08-01T21:28:01.000Z","updated_at":"2024-07-24T04:17:59.000Z","dependencies_parsed_at":"2023-04-22T21:37:20.481Z","dependency_job_id":null,"html_url":"https://github.com/agustingianni/retools","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/agustingianni%2Fretools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agustingianni%2Fretools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agustingianni%2Fretools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agustingianni%2Fretools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agustingianni","download_url":"https://codeload.github.com/agustingianni/retools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253401483,"owners_count":21902681,"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":["arm","armv7","armv8","binary","disassembler","disassembly","emulator","engineering","framework","macho","re","research","reverse","vulndev","vulnerability"],"created_at":"2024-08-03T13:01:04.601Z","updated_at":"2025-05-10T10:31:51.149Z","avatar_url":"https://github.com/agustingianni.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# retools: a reverse engineering toolkit for normies\n\nCollection of tools (disassembler, emulator, binary parser) aimed at reverse enginering tasks, more specifically, bug finding related. Currently we target ARMv7 and Mach-O though in the future more architectures and formats are planned.\n\n`retools` is somewhat unique in that most of the semantics for relevant instructions are parsed out of the specification PDFs as opposed to being generated by hand. Currently the disassembler, emulator, and binary parsers are partially done, with a symbolic execution engine and instrumentation/hooking framework to come as I get more time.\n\n[![Build Status](https://travis-ci.org/agustingianni/retools.svg?branch=master)](https://travis-ci.org/agustingianni/retools)\n\n# About the framework\n`retools` has been designed to be modular, that is, we have divided each major subsystem in a separate library that can be used in most of the cases independently of other parts of the framework.\n\n## libdisassembly\nMulti architecture decoding/disassembling library. It supports, for now, the `ARMv7` (and below) architecture.\nThe decoding/disasembling procedures for the `ARMv7` architecture are generated automatically from the architecture manual.\n\n## libemulation\nEmulation library that allows its clients to emulate instructions. The emulation code has been automatically generated in the same fashion as `libdisassembly`.\n\n## libbinary\nLibrary that allows its clients to read/write/parse binary executables in a generic way that is independent of the underliying file format of the binary.\nAs of now we only support `mach-o` binaries, both `fat` and `slim` binaries.\n\n### Example\nIn this example we will use the `binary_info` tool to inspect some generic details about a macho binary. `binary_info` is meant to be an example of how to use `libbinary`.\n\n```\n$ ./build/src/tools/binary_info/binary_info /bin/ps\n\nCurrent binary:\n  Linker: /usr/lib/dyld\n\n  Version: 168.0.0.0.0\n\n  UID: 55137f9f2fd933e6b9f39d4c7c65681c\n\n  Entry points:\n    entry: 0x51ac\n    ...\n\n  Libraries:\n    lib: /usr/lib/libSystem.B.dylib\n\n  Strings:\n    val: no valid keywords; valid keywords:\n    val:        ps [-L]\n    ...\n\n  Symbols:\n    sym: __mh_execute_header @ 0x100000000\n    ...\n  Segment:\n    address : 0x0\n    size    : 0x100000000\n    perm    : ---\n  Segment:\n    address : 0x100000000\n    size    : 0x6000\n    perm    : r-x\n  Segment:\n    address : 0x100006000\n    size    : 0x3000\n    perm    : rw-\n  Segment:\n    address : 0x100009000\n    size    : 0x4000\n    perm    : r--\n```\n\n## libsymbolic\nThe main idea of `libsymbolic` is to have an accurate and complete representation of the working architecture (say, ARM, x86, etc.) in a way that can be queried and used in the construction of reverse engineering tools.\n\nAs of now, `libsymbolic` is a *placeholder* for the automaticaly generated formal specification of the architecture.\n\n## libinstrumentation\n*Placeholder* for an instrumentation library.\n\n# Installation\nThere are two recommended ways you can install this framework, we recommend using `vagrant` if you are just curious about testing the tools and having a look at the code. Otherwise compiling the code should not be difficult on a semi-modern linux system.\n\n## Requirements\n\n`retools` is supported and has been tested on `macOS` and `Linux`. A `Windows` build may be possible if you don't mind not building the `libdebug` part of the framework because as of now, it depends on `lldb` being present.\n\nSoftware dependencies:\n\n- `pyparsing`\n- `capstone`\n- `unicorn`\n- `darm`\n- `cmake`\n- `Boost.Python`\n- `lldb`\n\nAll the dependencies should be handled by the `bootstrap.sh` script.\n\n### Vagrant\nUse vagrant with the provided `Vagrant` file. It will automatically create an Ubuntu VM and will run `bootstrap.sh` to install all the required files for compilation. Once the VM is created, you will find `retools` code at `$HOME/retools`. Move to that directory and then follow the *compilation* instructions that follow.\n\n### Compilation\n\n```\n# Clone the repository.\n$ git clone https://github.com/agustingianni/retools.git\n\n# Move to the cloned directory.\n$ cd retools/\n\n# Bootstrap installation (skip if using vagrant).\n$ bash bootstrap.sh\n\n# Compile sources.\n$ mkdir build\n$ cd build/\n$ cmake ..\n$ make -j8\n```\n\n# Documentation / Presentations\n- ARM Disassembling with a twist / Ekoparty 2016 [PDF](https://drive.google.com/file/d/0B0l-Qo3D3sAoMEhkcFBFVzRiNEk/view)\n- ARM Disassembling with a twist / Ekoparty 2016 [VID](https://vimeo.com/147629533)\n- ARM Architecture Reference Manual ARMv7-A and ARMv7-R edition\n [PDF](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0406c/index.html)\n\n# Licensing\nSee [LICENSE](LICENSE)\n\n# Contact\nFeel free to contact via e-mail to agustin.gianni@gmail.com or twitter @agustingianni.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagustingianni%2Fretools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagustingianni%2Fretools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagustingianni%2Fretools/lists"}