{"id":13730043,"url":"https://github.com/GrammaTech/gtirb","last_synced_at":"2025-05-08T02:31:07.601Z","repository":{"id":41125028,"uuid":"136977182","full_name":"GrammaTech/gtirb","owner":"GrammaTech","description":"Intermediate Representation for Binary analysis and transformation","archived":false,"fork":false,"pushed_at":"2025-04-28T14:01:53.000Z","size":22027,"stargazers_count":332,"open_issues_count":13,"forks_count":38,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-04-28T15:23:11.973Z","etag":null,"topics":["analysis","binary","binary-analysis","binary-rewriting","disassembler","gtirb","intermediate-representation","reverse-engineering"],"latest_commit_sha":null,"homepage":"https://grammatech.github.io/gtirb/","language":"C++","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/GrammaTech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null}},"created_at":"2018-06-11T20:25:41.000Z","updated_at":"2025-04-28T14:01:58.000Z","dependencies_parsed_at":"2023-09-25T23:18:34.554Z","dependency_job_id":"caf25ab2-e7e1-4fbe-80e1-b2512417244d","html_url":"https://github.com/GrammaTech/gtirb","commit_stats":{"total_commits":2876,"total_committers":37,"mean_commits":77.72972972972973,"dds":0.7666898470097357,"last_synced_commit":"003f0e32ccc1998f96fe799bcf61ecf8bc066309"},"previous_names":[],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrammaTech%2Fgtirb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrammaTech%2Fgtirb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrammaTech%2Fgtirb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrammaTech%2Fgtirb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GrammaTech","download_url":"https://codeload.github.com/GrammaTech/gtirb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252986696,"owners_count":21836206,"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","binary","binary-analysis","binary-rewriting","disassembler","gtirb","intermediate-representation","reverse-engineering"],"created_at":"2024-08-03T02:01:09.093Z","updated_at":"2025-05-08T02:31:07.592Z","avatar_url":"https://github.com/GrammaTech.png","language":"C++","readme":"# GTIRB\n\nThe GrammaTech Intermediate Representation for Binaries (GTIRB) is a\nmachine code analysis and rewriting data structure.  It is intended to\nfacilitate the communication of binary IR between programs performing\nbinary disassembly, analysis, transformation, and pretty printing.\nGTIRB is modeled on LLVM-IR, and seeks to serve a similar\nfunctionality of encouraging communication and interoperability\nbetween tools.\n\nThe remainder of this file describes various aspects of GTIRB:\n- [Structure](#structure)\n- [Installing](#installing)\n- [Building](#building)\n- [Usage](#usage)\n\n# Structure\n\nGTIRB has the following structure.  Solid lines denote inheritance.\nDotted lines denote reference by UUID.\n\n![GTIRB Data Structure](.gtirb.svg)\n\n## IR\n\nAn instance of GTIRB may include multiple modules (`Module`) which\nrepresent loadable objects such as executables or libraries, an\ninter-procedural control flow graph (`IPCFG`), and Auxiliary Data tables\n(`AuxData`) which can hold arbitrary analysis results in user-defined\nformats which can easily reference other elements of the IR.  Each\nmodule holds information such as symbols (`Symbol`) and sections which\nthemselves hold the actual bytes and data and code blocks of the\nmodule.  The CFG consists of basic blocks (`Block`) and control flow\nedges between these blocks.  Each data or code block references a\nrange of bytes in a byte interval (`ByteInterval`).  A section may\nhold one large byte interval holding all blocks---if the relative\npositions of blocks in that section are defined---or may hold one byte\ninterval per block---if the relative positions of blocks is not\ndefined, e.g. for the code blocks in the `.text` section during\nprogram rewriting.  Each symbol holds a pointer to the block or datum\nit references.\n\n\n## Instructions\n\nGTIRB explicitly does NOT represent instructions or instruction\nsemantics but does provide symbolic operand information and access to\nthe bytes.  There are many *intermediate languages* (IL)s for\nrepresentation of instruction semantics (e.g., [BAP][]'s [BIL][],\n[Angr][]'s [Vex][], or [Ghidra][]'s P-code).  GTIRB works with these\nor any other IL by storing instructions generally and efficiently as\n*raw machine-code bytes* and separately storing the symbolic and\ncontrol flow information.  The popular [Capstone][]/[Keystone][]\ndecoder/encoder provide an excellent option to read and write\ninstructions from/to GTIRB's machine-code byte representation without\ncommitting to any particular semantic IL.  By supporting multiple ILs\nand separate storage of analysis results in auxiliary data tables\nGTIRB enables collaboration between independent binary analysis and\nrewriting teams and tools.\n\n[BAP]: https://github.com/BinaryAnalysisPlatform/bap\n[BIL]: https://github.com/BinaryAnalysisPlatform/bil/releases/download/v0.1/bil.pdf\n[Angr]: http://angr.io\n[Vex]: https://github.com/angr/pyvex\n[Ghidra]: https://www.nsa.gov/resources/everyone/ghidra/\n[Capstone]: https://www.capstone-engine.org\n[Keystone]: https://www.keystone-engine.org\n\n\n## Auxiliary Data\n\nGTIRB provides for the sharing of additional information,\ne.g. analysis results, in the form of `AuxData` objects.  These can\nstore maps and vectors of basic GTIRB types in a portable way. The\n[GTIRB manual][] describes the structure for common types of auxiliary\ndata such as function boundary information, type information, or\nresults of common analyses in [Standard AuxData Schemata][].\n\n[GTIRB manual]: https://grammatech.github.io/gtirb/\n[Standard AuxData Schemata]: https://grammatech.github.io/gtirb/md__aux_data.html\n\n\n## UUIDs\n\nEvery element of GTIRB---e.g., modules (`Module`), symbols (`Symbol`),\nand blocks (`Block`)---has a universally unique identifier (UUID).\nUUIDs allow both first-class IR components and AuxData tables to\nreference elements of the IR.\n\nInstructions and symbolic operands can be addressed by the class\n`Offset` which encapsulates a UUID (that refers to the instruction's\nblock) and an offset.\n\n\n# Installing\n\nPackages currently exist for easily installing GTIRB (and attendant\ntooling including the [ddisasm][] disassembler and [gtirb-pprinter][]\npretty printer) on Windows, and Ubuntu 20. See below for\ninstructions. Additionally, a public Docker image exists at\n[grammatech/ddisasm][] with all of these tools installed. GTIRB is\nversioned with Major.Minor.Patch versioning where Major version\nincrements will require significant source changes but should be very\nrare, Minor version increments may require small source changes, and\nPatch version increments shouldn't break any downstream builds. We do\nnot yet provide ABI compatibility across any version changes.\n\n[ddisasm]: https://github.com/GrammaTech/ddisasm\n[gtirb-pprinter]: https://github.com/GrammaTech/gtirb-pprinter\n[grammatech/ddisasm]: https://hub.docker.com/r/grammatech/ddisasm\n\n\n## Python API\n\nThe latest stable GTIRB Python API may be installed from PyPI using pip:\n\n```sh\npip install gtirb\n```\n\nThe latest unstable version of the Python API can be installed from a\nprebuilt wheel:\n\n```sh\npip install https://download.grammatech.com/gtirb/files/python/gtirb-0.dev-py3-none-any.whl\n```\n\nIt is critical that the choice of a `stable` or `unstable` package matches the\ninstalled ddisasm and gtirb-pprinter packages.\n\n## Windows\n\nWindows releases are packaged as .zip files and are available at\nhttps://download.grammatech.com/gtirb/files/windows-release/.\n\n## Ubuntu\n\nPackages for Ubuntu 20 are available in the GTIRB apt repository and may\nbe installed per the following instructions.\n\nFirst, add GrammaTech's APT key.\n```sh\nwget -O - https://download.grammatech.com/gtirb/files/apt-repo/conf/apt.gpg.key | apt-key add -\n```\n\nNext update your sources.list file.\n```sh\necho \"deb [arch=amd64] https://download.grammatech.com/gtirb/files/apt-repo [distribution] [component]\"| sudo tee -a /etc/apt/sources.list\n```\nWhere:\n- `[distribution]` is `focal` (currently, only Ubuntu 20 packages are available)\n- `[component]` is either `stable`, which holds the last versioned release, or\n`unstable`, which holds the HEAD of the repository.\n\nFinally update your package database and install the core GTIRB tools:\n```sh\nsudo apt-get update\nsudo apt-get install gtirb-pprinter ddisasm\n```\n\n**Warning**:  Stable versions gtirb-2.0.0, gtirb-pprinter-2.1.0, ddisasm-1.8.0\nand OLDER rely on metapackages which cause conflicts if you try `apt-get upgrade`\n(see https://github.com/GrammaTech/gtirb/issues/63).  In this case,\nuninstall and reinstall the packages you got from the GTIRB repository.  You\nmay need to use `dpkg --remove` to remove the metapackages (e.g. `ddisasm`)\nbefore removing the concrete versioned packages (e.g. `ddisasm-1.5.1`).\nNEWER stable versions no longer rely on metapackages and can be upgraded\nwithout problems.\n\n# Building\n\nGTIRB's C++ API should successfully build in 64-bits with GCC, Clang,\nand Visual Studio compilers supporting at least C++17.  GTIRB uses\nCMake which must be installed with at least version 3.10.\n\nThe common build process looks like this:\n```sh\nmkdir build\ncd build\n# Note: You may wish to add some -D arguments to the next command. See below.\ncmake \u003cpath/to/gtirb\u003e\ncmake --build .\n# Run the test suite.\nctest\n```\n\nFor customizing the GTIRB build, you can get a list of customization options by\nnavigating to your build directory and running:\n\n```sh\ncmake -LH\n```\n\n## Requirements\n\nTo build and install GTIRB, the following requirements should be installed:\n\n- [CMake][], version 3.10.0 or higher.\n   - Ubuntu 18 provides this version via the APT package `cmake`.\n   - Ubuntu 16 and earlier provide out of date versions; build from\n     source on those versions.\n- [Protobuf][], version\n  3.0.0 or later.\n  - Ubuntu 18 provides this version via the APT packages\n    `libprotobuf-dev` and `protobuf-compiler`.\n  - Ubuntu 16 and earlier provide out of date versions; build from\n    source on those versions.\n- Boost [(non-standard Ubuntu package from launchpad.net)][], version 1.68 or later.\n  - Ubuntu 18 only has version 1.65 in the standard repository.  See Ubuntu instructions above.\n\n[CMake]: https://cmake.org/\n[Protobuf]: https://developers.google.com/protocol-buffers/\n[(non-standard Ubuntu package from launchpad.net)]: https://launchpad.net/~mhier/+archive/ubuntu/libboost-latest\n\n\n# Usage\n\nGTIRB is designed to be serialized using [Google protocol buffers][]\n(i.e., [protobuf][]), enabling [easy and efficient use from any\nprogramming language](#using-serialized-gtirb-data).\n\nGTIRB may also be used through a dedicated API implemented in multiple\nlanguages. The APIs provide efficient data structures suitable for use\nby binary analysis and rewriting applications; see\n[below](#gtirb-api-implementations) for details.\n\n[Google protocol buffers]: https://developers.google.com/protocol-buffers/\n[protobuf]: https://github.com/google/protobuf/wiki\n\n\n## Using Serialized GTIRB Data\n\nGTIRB uses a serialized format that consists of an 8-byte signature\nfollowed by serialized [protobuf][] data. The protobuf data allows\nfor exploration and manipulation in the language of your choice.\nThe [Google protocol buffers][] homepage lists the languages in which\nprotocol buffers can be used directly; users of other languages can\nconvert the protobuf-formatted data to JSON format and then use the\nJSON data in their applications.\n\nThe `proto` directory in this repository contains the protocol buffer\nmessage type definitions for GTIRB. You can inspect these `.proto`\nfiles to determine the structure of the various GTIRB message\ntypes. The top-level message type is `IR`.\n\nFor more details, see [Using Serialized GTIRB Data](PROTOBUF.md).\n\n\n## GTIRB API Implementations\n\nThe GTIRB API is currently available in C++, Python, and Common Lisp.\nThere is a *partial* Java API which is not ready for external use.\nFor language-independent API information, see [GTIRB\nComponents](doc/general/ComponentsIndex.md). For information about the\ndifferent API implementations, see:\n\n  - [C++ API](doc/cpp/README.md)\n  - [Python API](python/README.md)\n  - [Common Lisp API](cl/README.md)\n  - Java API **incomplete**\n","funding_links":[],"categories":["Decompilers/ Disassemblers","Code-gen","C++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGrammaTech%2Fgtirb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGrammaTech%2Fgtirb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGrammaTech%2Fgtirb/lists"}