Package: gtirb
GTIRBThe GrammaTech Intermediate Representation for Binaries (GTIRB) is a
machine code analysis and rewriting data structure.  It is intended to
facilitate the communication of binary IR between programs performing
binary disassembly, analysis, transformation, and pretty printing.
GTIRB is modeled on LLVM-IR, and seeks to serve a similar
functionality of encouraging communication and interoperability
between tools.The remainder of this file describes various aspects of GTIRB:StructureInstallingBuildingUsageStructureGTIRB has the following structure.  Solid lines denote inheritance.
Dotted lines denote reference by UUID.IRAn instance of GTIRB may include multiple modules (Module) which
represent loadable objects such as executables or libraries, an
inter-procedural control flow graph (IPCFG), and Auxiliary Data tables
(AuxData) which can hold arbitrary analysis results in user-defined
formats which can easily reference other elements of the IR.  Each
module holds information such as symbols (Symbol) and sections which
themselves hold the actual bytes and data and code blocks of the
module.  The CFG consists of basic blocks (Block) and control flow
edges between these blocks.  Each data or code block references a
range of bytes in a byte interval (ByteInterval).  A section may
hold one large byte interval holding all blocks---if the relative
positions of blocks in that section are defined---or may hold one byte
interval per block---if the relative positions of blocks is not
defined, e.g. for the code blocks in the.textsection during
program rewriting.  Each symbol holds a pointer to the block or datum
it references.InstructionsGTIRB explicitly does NOT represent instructions or instruction
semantics but does provide symbolic operand information and access to
the bytes.  There are manyintermediate languages(IL)s for
representation of instruction semantics (e.g.,BAP'sBIL,Angr'sVex, orGhidra's P-code).  GTIRB works with these
or any other IL by storing instructions generally and efficiently asraw machine-code bytesand separately storing the symbolic and
control flow information.  The popularCapstone/Keystonedecoder/encoder provide an excellent option to read and write
instructions from/to GTIRB's machine-code byte representation without
committing to any particular semantic IL.  By supporting multiple ILs
and separate storage of analysis results in auxiliary data tables
GTIRB enables collaboration between independent binary analysis and
rewriting teams and tools.Auxiliary DataGTIRB provides for the sharing of additional information,
e.g. analysis results, in the form ofAuxDataobjects.  These can
store maps and vectors of basic GTIRB types in a portable way. TheGTIRB manualdescribes the structure for common types of auxiliary
data such as function boundary information, type information, or
results of common analyses inStandard AuxData Schemata.UUIDsEvery element of GTIRB---e.g., modules (Module), symbols (Symbol),
and blocks (Block)---has a universally unique identifier (UUID).
UUIDs allow both first-class IR components and AuxData tables to
reference elements of the IR.Instructions and symbolic operands can be addressed by the classOffsetwhich encapsulates a UUID (that refers to the instruction's
block) and an offset.InstallingPackages currently exist for easily installing GTIRB (and attendant
tooling including theddisasmdisassembler andgtirb-pprinterpretty printer) on Windows, and Ubuntu 20. See below for
instructions. Additionally, a public Docker image exists atgrammatech/ddisasmwith all of these tools installed. GTIRB is
versioned with Major.Minor.Patch versioning where Major version
increments will require significant source changes but should be very
rare, Minor version increments may require small source changes, and
Patch version increments shouldn't break any downstream builds. We do
not yet provide ABI compatibility across any version changes.Python APIThe latest stable GTIRB Python API may be installed from PyPI using pip:pipinstallgtirbThe latest unstable version of the Python API can be installed from a
prebuilt wheel:pipinstallhttps://download.grammatech.com/gtirb/files/python/gtirb-unstable-py3-none-any.whlIt is critical that the choice of astableorunstablepackage matches the
installed ddisasm and gtirb-pprinter packages.WindowsWindows releases are packaged as .zip files and are available athttps://download.grammatech.com/gtirb/files/windows-release/.UbuntuPackages for Ubuntu 20 are available in the GTIRB apt repository and may
be installed per the following instructions.First, add GrammaTech's APT key.wget-O-https://download.grammatech.com/gtirb/files/apt-repo/conf/apt.gpg.key|apt-keyadd-Next update your sources.list file.echo"deb [arch=amd64] https://download.grammatech.com/gtirb/files/apt-repo [distribution] [component]"|sudotee-a/etc/apt/sources.listWhere:[distribution]isfocal(currently, only Ubuntu 20 packages are available)[component]is eitherstable, which holds the last versioned release, orunstable, which holds the HEAD of the repository.Finally update your package database and install the core GTIRB tools:sudoapt-getupdate
sudoapt-getinstallgtirb-pprinterddisasmWarning:  There is a problem with the packages in the stable repository
that will cause conflicts if you tryapt-get upgrade.  In this case,
uninstall and reinstall the packages you got from the GTIRB repository.  You
may need to usedpkg --removeto remove the metapackages (e.g.ddisasm)
before removing the concrete versioned packages (e.g.ddisasm-1.5.1).BuildingGTIRB's C++ API should successfully build in 64-bits with GCC, Clang,
and Visual Studio compilers supporting at least C++17.  GTIRB uses
CMake which must be installed with at least version 3.10.The common build process looks like this:mkdirbuildcdbuild# Note: You may wish to add some -D arguments to the next command. See below.cmake<path/to/gtirb>
cmake--build.# Run the test suite.ctestFor customizing the GTIRB build, you can get a list of customization options by
navigating to your build directory and running:cmake-LHRequirementsTo build and install GTIRB, the following requirements should be installed:CMake, version 3.10.0 or higher.Ubuntu 18 provides this version via the APT packagecmake.Ubuntu 16 and earlier provide out of date versions; build from
source on those versions.Protobuf, version
3.0.0 or later.Ubuntu 18 provides this version via the APT packageslibprotobuf-devandprotobuf-compiler.Ubuntu 16 and earlier provide out of date versions; build from
source on those versions.Boost(non-standard Ubuntu package from launchpad.net), version 1.67 or later.Ubuntu 18 only has version 1.65 in the standard repository.  See Ubuntu instructions above.UsageGTIRB is designed to be serialized usingGoogle protocol buffers(i.e.,protobuf), enablingeasy and efficient use from any
programming language.GTIRB may also be used through a dedicated API implemented in multiple
languages. The APIs provide efficient data structures suitable for use
by binary analysis and rewriting applications; seebelowfor details.Using Serialized GTIRB DataGTIRB uses a serialized format that consists of an 8-byte signature
followed by serializedprotobufdata. The protobuf data allows
for exploration and manipulation in the language of your choice.
TheGoogle protocol buffershomepage lists the languages in which
protocol buffers can be used directly; users of other languages can
convert the protobuf-formatted data to JSON format and then use the
JSON data in their applications.Theprotodirectory in this repository contains the protocol buffer
message type definitions for GTIRB. You can inspect these.protofiles to determine the structure of the various GTIRB message
types. The top-level message type isIR.For more details, seeUsing Serialized GTIRB Data.GTIRB API ImplementationsThe GTIRB API is currently available in C++, Python, and Common Lisp.
There is apartialJava API which is not ready for external use.
For language-independent API information, seeGTIRB
Components. For information about the
different API implementations, see:C++ APIPython APICommon Lisp APIJava APIincomplete