binaryninja-api

Public API, examples, documentation and issues for Binary Ninja

1,027

237

1,027

1,680

View on GitHub

Top Related Projects

radare2

21,578

UNIX-like reverse engineering framework and command-line toolset

rizin

2,888

UNIX-like reverse engineering framework and command-line toolset.

Capstone disassembly/disassembler framework for ARM, ARM64 (ARMv8), Alpha, BPF, Ethereum VM, HPPA, LoongArch, M68K, M680X, Mips, MOS65XX, PPC, RISC-V(rv32G/rv64G), SH, Sparc, SystemZ, TMS320C64X, TriCore, Webassembly, XCore and X86.

angr

7,919

A powerful and user-friendly binary analysis platform!

ghidra

56,604

Ghidra is a software reverse engineering (SRE) framework

Quick Overview

The Vector35/binaryninja-api repository contains the Python API for Binary Ninja, a powerful reverse engineering platform. This API allows users to extend Binary Ninja's functionality, automate tasks, and create custom plugins for binary analysis and manipulation.

Pros

Extensive functionality for binary analysis and manipulation
Well-documented with comprehensive examples
Active development and community support
Seamless integration with Binary Ninja's GUI

Cons

Requires a Binary Ninja license for full functionality
Steep learning curve for beginners in reverse engineering
Limited standalone usage outside of Binary Ninja
Some advanced features may require additional programming skills

Code Examples

Basic function analysis:

from binaryninja import *

bv = BinaryViewType.get_view_of_file("/path/to/binary")
for func in bv.functions:
    print(f"Function: {func.name} at {hex(func.start)}")

Disassembling instructions:

from binaryninja import *

bv = BinaryViewType.get_view_of_file("/path/to/binary")
func = bv.get_function_at(bv.entry_point)
for block in func.low_level_il:
    for instr in block:
        print(instr.disassembly)

Creating a custom analysis plugin:

from binaryninja import *

class CustomAnalysisPlugin(PluginCommand):
    name = "Custom Analysis"
    description = "Performs custom analysis on the binary"

    def run(self, bv):
        for func in bv.functions:
            # Perform custom analysis here
            print(f"Analyzing {func.name}")

CustomAnalysisPlugin.register()

Getting Started

Install Binary Ninja and obtain a license
Install the Binary Ninja Python API:
```
pip install binaryninja
```
Create a Python script and import the API:
```
from binaryninja import *
```

Open a binary file and start analyzing:

bv = BinaryViewType.get_view_of_file("/path/to/binary")
print(f"Binary: {bv.file.filename}")
print(f"Architecture: {bv.arch.name}")

For more detailed information and advanced usage, refer to the official Binary Ninja documentation and API reference.

Competitor Comparisons

radare2

21,578

UNIX-like reverse engineering framework and command-line toolset

Pros of radare2

Open-source and free to use
Extensive command-line interface for advanced users
Large community and active development

Cons of radare2

Steeper learning curve due to complex interface
Less polished GUI compared to Binary Ninja

Code Comparison

radare2:

r_core_cmd(core, "aaa", 0);
r_core_cmd(core, "pdf", 0);

binaryninja-api:

bv = binaryninja.BinaryViewType.get_view_of_file(filename)
bv.update_analysis_and_wait()
for func in bv.functions:
    print(func.get_disassembly_text())

The radare2 example shows command-line usage for analysis and disassembly, while the binaryninja-api example demonstrates a more programmatic approach using Python. radare2 offers a powerful CLI, but Binary Ninja provides a more intuitive API for scripting and automation.

Both tools are powerful for reverse engineering and binary analysis, with radare2 being more flexible and customizable, while Binary Ninja offers a more user-friendly experience with its API and GUI. The choice between them often depends on personal preference and specific use cases.

rizin

2,888

UNIX-like reverse engineering framework and command-line toolset.

Pros of rizin

Open-source and free to use, allowing for community contributions and modifications
Supports a wide range of architectures and file formats
Provides a powerful command-line interface for advanced users

Cons of rizin

Less user-friendly interface compared to Binary Ninja's GUI
May have a steeper learning curve for beginners
Documentation can be less comprehensive or up-to-date

Code Comparison

rizin:

r_core_cmd0(core, "aaa");
RAnalFunction *fcn = r_anal_get_fcn_at(core->anal, addr, 0);
if (fcn) {
    r_cons_printf("Function found at 0x%08" PFMT64x "\n", fcn->addr);
}

binaryninja-api:

bv = BinaryViewType.get_view_of_file(filename)
bv.update_analysis_and_wait()
function = bv.get_function_at(addr)
if function:
    print(f"Function found at 0x{function.start:x}")

Both repositories provide powerful reverse engineering capabilities, but rizin offers more flexibility as an open-source tool, while Binary Ninja API provides a more polished and user-friendly experience for developers.

capstone

7,975

Pros of Capstone

Open-source and free to use
Supports a wide range of architectures (x86, ARM, MIPS, etc.)
Lightweight and easily integrable into various projects

Cons of Capstone

Limited to disassembly only, lacks advanced analysis features
Requires more manual work for complex reverse engineering tasks
Less frequent updates and community support compared to Binary Ninja API

Code Comparison

Capstone (disassembling x86 code):

from capstone import *

CODE = b"\x55\x48\x8b\x05\xb8\x13\x00\x00"
md = Cs(CS_ARCH_X86, CS_MODE_64)
for i in md.disasm(CODE, 0x1000):
    print("0x%x:\t%s\t%s" %(i.address, i.mnemonic, i.op_str))

Binary Ninja API (disassembling and analyzing x86 code):

from binaryninja import *

bv = BinaryViewType.get_view_of_file("path/to/binary")
for func in bv.functions:
    for block in func.low_level_il:
        for instr in block:
            print(f"{instr.address:#x}: {instr}")

The Binary Ninja API provides more comprehensive analysis capabilities, including function detection and intermediate language representation, while Capstone focuses solely on disassembly.

angr

7,919

A powerful and user-friendly binary analysis platform!

Pros of angr

Open-source and free to use, allowing for community contributions and modifications
More comprehensive analysis capabilities, including symbolic execution and program slicing
Supports a wider range of architectures and file formats

Cons of angr

Steeper learning curve and more complex setup process
Can be slower and more resource-intensive for certain analyses
Less user-friendly interface compared to Binary Ninja's GUI

Code Comparison

angr:

import angr

proj = angr.Project('binary')
state = proj.factory.entry_state()
simgr = proj.factory.simulation_manager(state)
simgr.explore(find=0x400000)

binaryninja-api:

from binaryninja import *

bv = BinaryViewType.get_view_of_file("binary")
func = bv.get_function_at(bv.entry_point)
for block in func.basic_blocks:
    print(block.disassembly_text)

The angr code demonstrates setting up a project, creating an initial state, and exploring the binary to find a specific address. The binaryninja-api code shows how to load a binary, get the entry point function, and iterate through its basic blocks for disassembly.

ghidra

56,604

Ghidra is a software reverse engineering (SRE) framework

Pros of Ghidra

Open-source and free to use, allowing for community contributions and modifications
Extensive feature set, including a powerful decompiler and support for a wide range of architectures
Developed by the NSA, benefiting from their expertise in reverse engineering and security analysis

Cons of Ghidra

Steeper learning curve due to its complexity and extensive feature set
Can be resource-intensive, especially for large binaries or complex analysis tasks
Less frequent updates compared to commercial alternatives

Code Comparison

Ghidra (Java):

public class SimpleScript extends GhidraScript {
    @Override
    public void run() throws Exception {
        println("Hello from Ghidra!");
    }
}

Binary Ninja API (Python):

from binaryninja import *

def analyze(bv):
    print("Hello from Binary Ninja!")

PluginCommand.register("My Plugin", "Description", analyze)

Both APIs allow for script creation and plugin development, but Ghidra uses Java while Binary Ninja primarily uses Python. Ghidra's scripting interface is more tightly integrated with its Java-based architecture, while Binary Ninja's API offers a more Pythonic approach, which may be more familiar to some developers.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Binary Ninja API

This repository contains documentation and source code of the C++, Python, and Rust APIs for the Binary Ninja reverse engineering platform.

Documentation

Online documentation is available for the following APIs:

Usage and Build Instructions

In order to build the Binary Ninja API, you will need to use the specific revision that matches the hash from the file api_REVISION.txt. This file should be located in the root install folder for Linux and Windows or the Contents/Resources sub-folder of the app on macOS. The easiest way to do this is by cloning this repository (or adding it as a submodule) and doing something like git checkout $(cat api_REVISION.txt | awk -F/ '{print $NF}'). Documentation for how to set this up with something like cmake can be found here.

To write Binary Ninja plugins using C++, you'll need to build the C++ API. Building the API library is done similarly to most CMake-based projects; the basic steps are outlined as follows:

# Get the source
git clone https://github.com/Vector35/binaryninja-api.git
cd binaryninja-api
git submodule update --init --recursive

# Configure an out-of-source build setup
cmake -S . -B build # (additional arguments go here if needed)

# Compile
cmake --build build -j8

In addition to the default build setup, you may want to:

Build examples. To build the API examples, pass -DBN_API_BUILD_EXAMPLES=ON to CMake when configuring the build. After the build succeeds, you can install the built plugins by running the install target. When using the "Unix Makefiles" build generator, this looks like: make install.
Build UI plugins. You will need Qt 6.8.2 installed to build UI plugins. We use a slightly modified build configuration internally that has some ABI-compatible fixes and changes to defaults, but a stock build can also work. Note that it is not recommended to use pre-built configurations from Homebrew. Either using the official installer or building from our repo is recommended.
Build headlessly. If you are using a headless Binary Ninja distribution or you do not wish to build UI plugins, pass -DHEADLESS=ON to CMake when configuring the build.

Troubleshooting

If Binary Ninja is installed at a different location than the platform default (defined in CMakeLists.txt), you will likely get an error stating "Binary Ninja Core Not Found." Specify the path to your Binary Ninja installation with by passing -DBN_INSTALL_DIR=/path/to/binaryninja to CMake when configuring the build setup.
Since Binary Ninja is a 64-bit only product, ensure that you are using a 64-bit compiling and linking environment. Errors on Windows like LNK1107 might indicate that your bits don't match.

Examples

There are many examples available. The Python examples folder demonstrates many different applications of the Python API, while C++ examples include:

background_task is a plugin that demonstrates managing a background task.*
bin-info is a standalone executable that prints some information about a given binary to the terminal.*
breakpoint is a plugin that allows you to select a region within an x86 binary and use the context menu to fill it with breakpoint bytes.
command-line disassm demonstrates how to dump disassembly to the command line.*
llil-parser parses Low-Level IL, demonstrating how to match types and use a visitor class.*
mlil-parser parses Medium-Level IL, demonstrating how to match types and use a visitor class.*
print_syscalls is a standalone executable that prints the syscalls used in a given binary.*
triage is a fully featured plugin that is shipped and enabled by default, demonstrating how to do a wide variety of tasks including extending the UI through QT.
workflows is a collection of plugins that demonstrate using Workflows to extend the analysis pipeline.
x86 extension creates an architecture extension which shows how to modify the behavior of the build-in architectures without creating a complete replacement.

* Requires license supporting headless API access.

Issues

The issue tracker for this repository tracks not only issues with the source code contained here but also the broader Binary Ninja product.

Branches

This repository has two primary branches dev and master.

The dev branch has the latest updates and tracks the latest development build of Binary Ninja; pull requests should be made against this branch. The master branch tracks the stable build of Binary Ninja. If you have just installed Binary Ninja for the first time, you are likely on the stable release channel.

Contributing

Public contributions are welcome to this repository. Most of the API and documentation in this repository is licensed under an MIT license, however, the API interfaces with a closed-source commercial application, Binary Ninja. Additionally, the Rust API is licensed under a Apache 2.0 license.

If you're interested in contributing when you submit your first PR, you'll receive a notice from CLA Assistant that allows you to sign our Contribution License Agreement online.

Platforms

This repository contains all of our Platform plugins available here:

Architectures

This repository contains all the Architecture plugins available in Personal and Commercial editions of Binary Ninja. You can find each architecture here:

BinaryViewTypes

This repository contains all of our Binary View Type plugins available here:

DebugInfo

Other Plugins

Related Repositories

In addition to this main API repository being open source Vector35 also has open sourced the Debugger and the Objective-C plugins open source as well:

Licensing

Some components may be released under compatible but slightly different open source licenses and will have their own LICENSE file as appropriate.

Remaining components are released under an MIT license.

Note that .lib files are included the native binary builds of Binary Ninja for windows. Those lib files are also released under the same license as this repository and may be distributed accordingly.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot