google

google/binexport

Export disassemblies into Protocol Buffers

1.2kstars 250forks 30contributors C++

README.md

# BinExport

[![Linux Build Status](https://github.com/google/binexport/workflows/linux-build/badge.svg)](https://github.com/google/binexport/actions?query=workflow%3Alinux-build)
[![Coverity Scan Build Status](https://scan.coverity.com/projects/8977/badge.svg)](https://scan.coverity.com/projects/google-binexport)

Disclaimer: This is not an official Google product (experimental or otherwise),
it is just code that happens to be owned by Google.

## Table of Contents

*   [Introduction](#introduction)
*   [Installation](#installation)
    *   [IDA Pro](#ida-pro)
    *   [Binary Ninja](#binary-ninja)
    *   [Ghidra](#ghidra)
*   [Usage](#usage)
*   [How to build](#how-to-build)
    *   [Preparing the build environment](#preparing-the-build-environment)
    *   [Linux](#linux)
    *   [macOS](#macos)
    *   [Windows](#windows)

## Introduction

BinExport is the exporter component of
[BinDiff](https://www.zynamics.com/software.html). It is a plugin/extension for
the the disassemblers IDA Pro, Binary Ninja and Ghidra that exports disassembly
data into the Protocol Buffer format that BinDiff requires.

This repository contains the complete source code necessary to build BinExport
plugin binaries for Linux, macOS and Windows.

## Installation

### IDA Pro

Note: BinExport supports IDA Pro 9.4 or higher. Support for the older 8.x series
has been discontinued.

Download the binaries from the
[releases](https://github.com/google/binexport/releases) page and copy them
into the IDA Pro plugins directory. These are the default paths:

| OS      | Plugin path                                                 |
| ------- | ----------------------------------------------------------- |
| Linux   | `/opt/ida-pro-9.4/plugins`                                  |
| macOS   | `/Applications/IDA Professional 9.4/Contents/MacOS/plugins` |
| Windows | `%ProgramFiles%\IDA 9.4\plugins`                            |

To install just for the current user, copy the files into one of these
directories instead:

| OS          | Plugin path                          |
| ----------- | ------------------------------------ |
| Linux/macOS | `~/.idapro/plugins`                  |
| Windows     | `%AppData%\Hex-Rays\IDA Pro\plugins` |

#### Verifying the installation version

1.  In IDA, select `Help`|`About programm...`
2.  Click `Addons...`
3.  If installed correctly, the following dialog box appears:

![IDA addons dialog](/doc/binexport10-ida-addons-dialog.png)

### Binary Ninja

Download the binaries from the
[releases](https://github.com/google/binexport/releases) page and copy them
into the Binary Ninja plugins directory. These are the default paths for the
current user:

| OS      | Plugin path                                           |
| ------- | ----------------------------------------------------- |
| Linux   | `~/.binaryninja/plugins`                              |
| macOS   | `~/Library/Application Support/Binary Ninja/plugins/` |
| Windows | `%AppData%\Binary Ninja\plugins`                      |

#### Verifying the installation version

1.  Start Binary Ninja
2.  Select the `Log` native dock. If this is not visible, enable it via
    `View`|`Native Docks`|`Show Log`.
3.  If installed correctly, the log window contains a line similar to this one:

```text
BinExport 12 (@internal, Jan 3 2023), (c)2004-2011 zynamics GmbH, (c)2011-2024 Google LLC.
```

### Ghidra

1.  Download the binaries from the
    [releases](https://github.com/google/binexport/releases) page.
2.  Start Ghidra, select `File`|`Install Extensions...`
3.  In the "Install Extensions" dialog, click the plus icon in the upper right
    to "Add extension".
4.  In the "Select extension" dialog, enter the path to the
    `ghidra_BinExport.zip` you downloaded in step 1 and click `OK`.
5.  Click `OK` twice to close both the "Install Extensions" dialog and the
    notice to restart Ghidra.
6.  Exit Ghidra.

#### Verifying the installation version

1.  Start Ghidra
2.  Select `File`|`Install Extensions...`
3.  If installed correctly, the "Install Extensions" dialog should list the
    "BinExport" extension next to a selected checkbox.

## Usage

The main use case is via [BinDiff](https://zynamics.com/bindiff.html). However,
BinExport can also be used to export disassembly into different formats:

*   Protocol Buffer based full export
*   Statistics text file
*   Text format for debugging

### IDA Pro

1.  Open an IDA Pro database
2.  Select `Edit`|`Plugins`|`BinExport 12`
3.  The following dialog box appears:

![BinExport plugin dialog](/doc/binexport10-plugin-dialog.png)

4.  Select the type of the file to be exported

#### IDC Scripting

The BinExport plugin registers the IDC functions below.

| IDC Function name   | Exports to           | Arguments  |
| ------------------- | -------------------- | ---------- |
| BinExportBinary     | Protocol Buffer      | filename   |
| BinExportText       | Text file dump       | filename   |
| BinExportStatistics | Statistics text file | filename   |

Alternatively, the plugin can be invoked from IDC by calling its main function
directly:

```c
static main() {
  batch(0);
  auto_wait();
  load_and_run_plugin("binexport12_ida", 2 /* kBinary */);
  qexit(0);
}
```

Note that this does provide any control over the output filename. BinExport
will always use the filename of the currently loaded database (without
extension) and append ".BinExport".

#### IDAPython

The arguments are the same as for IDC (listed above).

Example invocation of one of the registered IDC functions:

```python
import idaapi
idaapi.ida_expr.eval_idc_expr(None, ida_idaapi.BADADDR,
  'BinExportBinary("exported.BinExport");')
```

#### Plugin Options

BinExport defines the following plugin options, that can be specified on IDA's
command line:

| Option                                 | Description                                                           |
| -------------------------------------- | --------------------------------------------------------------------- |
| `-OBinExportAutoAction:<ACTION>`       | Invoke a BinExport IDC function and exit                              |
| `-OBinExportModule:<PARAM>`            | Argument for `BinExportAutoAction`                                    |
| `-OBinExportLogFile:<FILE>`            | Log messages to a file                                                |
| `-OBinExportAlsoLogToStdErr:TRUE`      | If specified, also log to standard error                              |
| `-OBinExportX86NoReturnHeuristic:TRUE` | Enable the X86-specific heuristic to identify non-returning functions |

Note: These options must come before any files.

### Binary Ninja

There is only minimal integration into the Binary Ninja UI at this time.

1.  Open or create a new analysis database
2.  Select `Tools`|`Plugins`|`BinExport`. This will start the export process.

The `.BinExport` file is placed next to the analysis database, in the same
directory.

### Ghidra

1.  Open or create a project. For new projects, import a file first using
    `File`|`Import File...`
2.  Right-click a file in the current project list and select `Export...` from
    the context menu.
3.  In the "Export" dialog, under "Format", choose
    "Binary Export (v2) for BinDiff".
4.  Under "Output File", enter the desired output file path. If the file
    extension is missing, `.BinExport` will be appended automatically.
5.  Optional: click "Options..." to set additional export options.
6.  Click "OK", then click "OK" again to dismiss the "Export Results Summary"
    dialog.

#### Scripting

The `BinExport.java` Ghidra script can be run in both headless and GUI mode.
In GUI mode, it is available under the `BinExport` category in the Script
Manager. For headless mode, a `BinExport.properties` file with the following
content (or similar, depending on the options you want to use) can be used:

```text
Choose export file Export = test.BinExport
Choose options IDA Pro Compatibility = "Subtract Imagebase;Remap mnemonics;Prepend Namespace to Function Names"
```

##### Example usage in headless mode

Create a project, import and analyze a binary:

```bash
$ ./analyzeHeadless <project_location> <project_name> -import <file>
```

Run `BinExport.java` which will generate the `.BinExport` file specified in
`BinExport.properties`:

```bash
$ ./analyzeHeadless <project_location> <project_name> -process <file> -propertiesPath <path> -preScript BinExport.java -noanalysis
```

Alternatively, use command-line arguments instead of `BinExport.properties`:

```bash
$ ./analyzeHeadless <project_location> <project_name> -process <file> -preScript BinExport.java test.BinExport "Prepend Namespace to Function Names" -noanalysis
```

## How to build

Below are build instructions for the native code plugins for IDA Pro and
Binary Ninja. To build the Java-based extension for Ghidra, please refer
to the [BinExport for Ghidra](/java) instructions.

### Preparing the build environment

There are quite a few dependencies to satisfy:

*   Boost 1.83.0 or higher (a partial copy of 1.83.0 ships in `boost_parts`)
*   [CMake](https://cmake.org/download/) 3.20 or higher
*   Suggested: [Ninja](https://ninja-build.org/) for speedy builds
*   GCC 15 or a recent version of Clang on Linux/macOS. On Windows, use the
    Visual Studio 2022 compiler and the Windows SDK for Windows 11.
*   Git 1.8 or higher
*   Dependencies that will be downloaded:
    *   Abseil, GoogleTest and Protocol Buffers (35.1)
    *   Binary Ninja SDK
    *   IDA SDK

### Linux

#### Prerequisites

The preferred build environment is Debian 11 ("Bullseye").

This should install all the necessary packages:

```bash
sudo apt update -qq
sudo apt install -qq --no-install-recommends build-essential
```

Install the latest stable version of CMake:

```bash
wget https://github.com/Kitware/CMake/releases/download/v4.4.0/cmake-4.4.0-linux-x86_64.sh
mkdir ${HOME}/cmake
sh cmake-4.4.0-linux-x86_64.sh --prefix=${HOME}/cmake --exclude-subdir
export PATH=${HOME}/cmake/bin:${PATH}
```

The following sections assume that your current working directory is at the root
of the cloned repository.

#### Build BinExport

Configure and build BinExport and run its tests:

```bash
mkdir -p build_linux && cd build_linux
cmake .. \
    -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    "-DCMAKE_INSTALL_PREFIX=${PWD}" \
    -DBINEXPORT_ENABLE_IDAPRO=ON \
    -DBINEXPORT_ENABLE_BINARYNINJA=ON
cmake --build . --config Release
ctest --build-config Release --output-on-failure
cmake --install . --config Release --strip
```

Note: If you don't want to use Ninja to perform the actual build, omit
the `-G Ninja` part.

To disable the IDA Pro build, set `-DBINEXPORT_ENABLE_IDAPRO=OFF`. Likewise, to
disable the Binary Ninja build, set `-DBINEXPORT_ENABLE_BINARYNINJA=OFF`.

This will download and build Abseil, GoogleTest, Protocol Buffers and the
Binary Ninja API. If all went well, the `build_linux/binexport-prefix`
directory should contain the file `binexport12_ida.so` (for IDA Pro) as well
as `binexport12_binaryninja.so` (for Binary Ninja).

### macOS

#### Prerequisites

The preferred build environment is macOS 26 "Tahoe" using Xcode. Older versions
should also work.

After installing the Developer Tools, make sure to install the command-line
tools as well:

```bash
sudo xcode-select --install
```

The following sections assume that your current working directory is at the root
of the cloned repository.

#### CMake

Download the latest stable version of CMake from the official site and mount its
disk image:

```bash
curl -fsSL https://github.com/Kitware/CMake/releases/download/v4.4.0/cmake-4.4.0-macos-universal.dmg \
    -o $HOME/Downloads/cmake-osx.dmg
hdiutil attach $HOME/Downloads/cmake-osx.dmg
```

At this point you will need to review and accept CMake's license agreement. Now
install CMake:

```bash
sudo cp -Rf /Volumes/cmake-4.4.0-Darwin-x86_64/CMake.app /Applications/
hdiutil detach /Volumes/cmake-4.4.0-Darwin-x86_64
sudo /Applications/CMake.app/Contents/bin/cmake-gui --install
```

The last command makes CMake available in the system path.

#### Build BinExport

Configure and build BinExport and run its tests:

```bash
mkdir -p build_mac && cd build_mac
cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    "-DCMAKE_INSTALL_PREFIX=${PWD}" \
    -DBINEXPORT_ENABLE_IDAPRO=ON \
    -DBINEXPORT_ENABLE_BINARYNINJA=ON
cmake --build . --config Release -- "-j$(sysctl -n hw.logicalcpu)"
ctest --build-config Release --output-on-failure
cmake --install . --config Release --strip
```

Note: This will use the standard CMake "Makefile Generator". You can use XCode
or Ninja as generators as well.

To disable the IDA Pro build, set `-DBINEXPORT_ENABLE_IDAPRO=OFF`. Likewise, to
disable the Binary Ninja build, set `-DBINEXPORT_ENABLE_BINARYNINJA=OFF`.

This will download and build Abseil, GoogleTest, Protocol Buffers and the
Binary Ninja API. If all went well, the `build_mac/binexport-prefix`
directory should contain the file `binexport12_ida.dylib` (for IDA Pro) as well
as `binexport12_binaryninja.dylib` (for Binary Ninja).

### Windows

The preferred build environment is Windows 10 (64-bit Intel) using the Visual
Studio 2022 compiler and the [Windows SDK for Windows
10](https://dev.windows.com/en-us/downloads/windows-10-sdk).

#### CMake

Download and install the latest stable CMake (4.4.0 at the time of writing)
from its [download page](https://cmake.org/download/). Make sure to select
"Add CMake to the system PATH for all users".

#### Git

Download and install Git from its [download
page](https://git-scm.com/download/win). Make sure to select the following
options:

*   The installation directory should be left at the default
    `%ProgramFiles%\Git\bin\git.exe`
*   "Use Git from the Windows Command Prompt" - have the setup utility add Git
    to your system path.
*   "Use Windows' default console window" - to be able to use Git from the
    regular command prompt.

#### Prepare

The following sections assume an open command prompt with the current working
directory located at the root of the cloned BinExport repository:

```bat
git clone https://github.com/google/binexport.git
cd binexport
```

#### Build BinExport

Configure and build BinExport:

```bat
if not exist build_msvc mkdir build_msvc
cd build_msvc
cmake .. ^
    -G "Visual Studio 17 2022" ^
    -DCMAKE_BUILD_TYPE=Release ^
    "-DCMAKE_INSTALL_PREFIX=%cd%" ^
    -DBINEXPORT_ENABLE_IDAPRO=ON ^
    -DBINEXPORT_ENABLE_BINARYNINJA=ON
cmake --build . --config Release -- /m /clp:NoSummary;ForceNoAlign /v:minimal
ctest --build-config Release --output-on-failure
cmake --install . --config Release --strip
```

Note: This will use the CMake "Visual Studio" generator. You can use the Ninja
generator as well.

To disable the IDA Pro build, set `-DBINEXPORT_ENABLE_IDAPRO=OFF`. Likewise, to
disable the Binary Ninja build, set `-DBINEXPORT_ENABLE_BINARYNINJA=OFF`.

This will download and build Abseil, GoogleTest, Protocol Buffers and the
Binary Ninja API. If all went well, the `build_msvc/binexport-prefix`
directory should contain the file `binexport12_ida.dll` (for IDA Pro) as well
as `binexport12_binaryninja.dll` (for Binary Ninja).

Repository info

Default branch: main
Latest version: v12-20240417-ghidra_11.0.3
Created: 03/09/2015
Last activity: 27/10/2026
License: Apache-2.0
Open issues: 44
Watchers: 52

Topics

binary-ninja binary-ninja-plugin bindiff binexport binnavi c-plus-plus database ghidra ghidra-extension ghidra-plugin ida-plugin ida-pro java protobuf reverse-engineering vxsig

Contributors

cblichmann

379 contributions

copybara-github

25 contributions

SmileyAG

7 contributions

rmngoog

6 contributions

mike-hunhoff

6 contributions