BinExport

Copyright 2011-2024 Google LLC.

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
• Installation
  • IDA Pro
  • Binary Ninja
  • Ghidra
• Usage
• How to build
  • Preparing the build environment
  • Linux
  • macOS
  • Windows

Introduction

BinExport is the exporter component of BinDiff. 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.

An experimental version for the open source software reverse engineering suite Ghidra is available in the java/BinExport directory.

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

Installation

IDA Pro

Download the binaries from the releases page and copy them into the IDA Pro plugins directory. These are the default paths:

| OS | Plugin path | | ------- | ------------------------------------------- | | Linux | /opt/idapro-8.2/plugins | | macOS | /Applications/IDA Pro 8.2/idabin/plugins | | Windows | %ProgramFiles%\IDA 8.2\plugins |

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

| OS | Plugin | | ----------- | ------------------------------------ | | 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:

   

Binary Ninja

Download the binaries from the 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:

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

Ghidra

1. Download the binaries from the 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. 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:

   

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:

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:

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:

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:

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

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

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

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

$ ./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 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 3.14 or higher
• Suggested: Ninja for speedy builds
• GCC 9 or a recent version of Clang on Linux/macOS. On Windows, use the Visual Studio 2019 compiler and the Windows SDK for Windows 10.
• Git 1.8 or higher
• IDA Pro only: IDA SDK 8.2 or higher (unpack into third_party/idasdk)
• Dependencies that will be downloaded:
  • Abseil, GoogleTest and Protocol Buffers (25.2)
  • Binary Ninja SDK

Linux

Prerequisites

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

This should install all the necessary packages:

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

Install the latest stable version of CMake:

wget https://github.com/Kitware/CMake/releases/download/v3.25.1/cmake-3.25.1-linux-x86_64.sh
mkdir ${HOME}/cmake
sh cmake-3.25.1-linux-x86_64.sh --prefix=${HOME}/cmake --exclude-subdir
export PATH=${HOME}/cmake/bin:$