BinDiff Documentation

BinDiff matches functions by analyzing the abstract structure of an executable rather than concrete assembly instructions.

The process follows these steps:

1. Signature Generation: Every function receives a signature based on its normalized flow graph (number of basic blocks, edges, and calls to sub-functions).
2. Initial Global Matching: BinDiff identifies functions that share unique characteristics across both binaries.
3. Drill Down: If an attribute is ambiguous (appears multiple times), BinDiff narrows the search by only considering equivalent sets of functions for that attribute.
4. Call Graph Expansion: Once a match is found, BinDiff examines the parents (callers) and children (callees) of that match to find new matches.
5. Basic Block Matching: Finally, BinDiff performs matching at the basic block level for newly matched functions.

To start using BinDiff immediately without building from source, download the prebuilt installation packages from the official releases page.

Note: BinDiff requires a separate disassembler to function. It includes out-of-the-box support for:

• IDA Pro
• Binary Ninja
• Ghidra

BinDiff 7 includes beta support for Ghidra and Binary Ninja:

• Ghidra: The BinExport Ghidra extension is included in the package. You must manually export files from Ghidra to be able to bindiff them.
• Binary Ninja: A BinExport plugin for Binary Ninja is included (beta). You can use the third-party BD Viewer or export files manually to bindiff them.

BinDiff uses CMake and Ninja to build its native C++ components.

Prerequisites

• BinExport 12: The companion plugin (required).
• Boost: 1.83.0 or higher.
• CMake: 3.14 or higher.
• Ninja: For build execution.
• Compiler:
  • Linux/macOS: GCC 15 or a recent Clang.
  • Windows: Visual Studio 2022 compiler and the Windows 11 SDK.
• Git: 1.8 or higher.

Build Steps (Linux Example)

1. Configure and generate build files:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release

2. Build and run tests:

cmake --build build --config Release
(cd build; ctest --build-config Release --output-on-failure)

3. Install:

cmake --install build --config Release

If you do not have an IDA Pro license or wish to exclude IDA integration from your build, use the -DBINEXPORT_ENABLE_IDAPRO=OFF flag during the CMake configuration step.

cmake -S . -B build/out -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DBINEXPORT_ENABLE_IDAPRO=OFF

The Java-based visual user interface requires Gradle 6.x, Java 11 LTS, and the commercial yFiles graph visualization library (specifically the 2.x branch).

Setup

1. Install Gradle 6.x.
2. Set the YFILES_DIR environment variable to the directory containing y.jar and ysvg.jar.

Build Commands

Windows:

set YFILES_DIR=<path\to\yfiles_2.17>
cd java
gradle shadowJar

Linux or macOS:

export YFILES_DIR=<path/to/yfiles_2.17>
cd java
gradle shadowJar

Running the GUI

After building, the self-contained artifact bindiff-ui-all.jar is located in java/ui/build/libs/. Run it using:

java -jar bindiff-ui-all.jar

BinDiff is a binary comparison tool designed to identify differences and similarities in disassembled code. It is primarily used for:

• Identifying and isolating vulnerability fixes in vendor-supplied patches.
• Analyzing multiple versions of the same binary.
• Transferring analysis results between binaries to avoid duplicate work (e.g., in malware analysis).
• Retaining knowledge across teams of binary analysts by standardizing analysis results.

BinDiff provides an experimental extension for the Ghidra disassembler. This extension is open source and allows for BinDiff functionality within the Ghidra environment, similar to the IDA Pro plugin.

To build and use the Ghidra extension, you must access the source code and specific instructions located in the binexport repository on GitHub.

https://github.com/google/binexport/tree/main/java