Crate binaryninja

Expand description

§binaryninja-rs

Official Rust bindings for Binary Ninja.

Getting Started
Examples
Documentation
Offline Documentation

§WARNING

These bindings are still actively under development. Compatibility will break and conventions will change! It is encouraged that you reference a specific commit to avoid having your plugin/application break when the API changes. To specify a specific commit, see the cargo documentation here.

If you are worried about breaking changes, avoid modules with warnings about instability!

MSRV: The Rust version specified in the Cargo.toml.

§Example

use binaryninja::headless::Session;
use binaryninja::binary_view::{BinaryViewBase, BinaryViewExt};

fn main() {
    let headless_session = Session::new().expect("Failed to initialize session");
    let bv = headless_session
        .load("/bin/cat")
        .expect("Couldn't open `/bin/cat`");
    
    println!("Filename:  `{}`", bv.file().filename());
    println!("File size: `{:#x}`", bv.len());
    println!("Function count: {}", bv.functions().len());
    
    for func in &bv.functions() {
        println!("{}:", func.symbol().full_name());
    }
}

More examples can be found in here.

§Getting Started

§Requirements

Having BinaryNinja installed (and your license registered)
- For headless operation you must have a headless supporting license.
Clang
Rust

§Link to Binary Ninja

Writing a standalone executable or a plugin requires that you link to binaryninjacore directly. The process of locating that however is done for you within the binaryninjacore-sys crate. Because linker arguments are not transitive for executables, you must specify them within your build.rs.

Cargo.toml:

[dependencies]
binaryninja = { git = "https://github.com/Vector35/binaryninja-api.git", branch = "dev"}
# Locates binaryninjacore on your system.
binaryninjacore-sys = { git = "https://github.com/Vector35/binaryninja-api.git", branch = "dev"}

build.rs:

fn main() {
    let link_path =
        std::env::var_os("DEP_BINARYNINJACORE_PATH").expect("DEP_BINARYNINJACORE_PATH not specified");
    
    println!("cargo::rustc-link-lib=dylib=binaryninjacore");
    println!("cargo::rustc-link-search={}", link_path.to_str().unwrap());
    
    #[cfg(target_os = "linux")]
    {
        println!(
            "cargo::rustc-link-arg=-Wl,-rpath,{0},-L{0}",
            link_path.to_string_lossy()
        );
    }

    #[cfg(target_os = "macos")]
    {
        let crate_name = std::env::var("CARGO_PKG_NAME").expect("CARGO_PKG_NAME not set");
        let lib_name = crate_name.replace('-', "_");
        println!("cargo::rustc-link-arg=-Wl,-install_name,@rpath/lib{}.dylib", lib_name);
    }
}

§Write a Plugin

Plugins are loaded at runtime and as such will have their own initialization routine.

Cargo.toml:

[lib]
crate-type = ["cdylib"]

lib.rs:

#[allow(non_snake_case)]
#[no_mangle]
pub extern "C" fn CorePluginInit() -> bool {
    // Initialize logging
    // Register custom architectures, workflows, demanglers, 
    // function recognizers, platforms and views!
    true
}

Examples for writing a plugin can be found here.

§Write a Standalone Executable

If you have a headless supporting license, you are able to use Binary Ninja as a regular dynamically loaded library.

Standalone executables must initialize the core themselves. binaryninja::headless::init() to initialize the core, and binaryninja::headless::shutdown() to shutdown the core. Prefer using binaryninja::headless::Session as it will shut down for you once it is dropped.

main.rs:

fn main() {
  // You must initialize the core to use Binary Ninja.
  let session = binaryninja::headless::Session::new().expect("Failed to initialize!");
  // Once `session` is dropped, the core will be shutdown!
}

§Offline Documentation

Offline documentation can be generated like any other rust crate, using cargo doc.

git clone https://github.com/Vector35/binaryninja-api
cd binaryninja-api
cargo doc --no-deps --open -p binaryninja

§Contributing

If you’re thinking of contributing to the Rust API, we encourage you to join the #rust-api channel in our Slack, especially for large-effort PRs.

§Testing

When contributing new APIs or refactoring existing APIs, it is vital that you test your code! If you do not have a headless supported license, you should still be able to write them and open your PR. Once open, a maintainer will approve tests to run and from there you can refine the test so that it passes in CI.

§Documentation

When refactoring or making new changes, make sure that the documentation for the respective APIs is up to date and not missing. Much of the APIs documentation exists only in the python bindings, so use that as a guide. If there is an API that confuses you, it will likely confuse someone else, and you should make an issue or ask for guidance in the Slack channel above.

§Attribution

This project makes use of:

Modules§

architecture: Architectures provide disassembly, lifting, and associated metadata about a CPU to inform analysis and decompilation.
background_task: Background tasks provide plugins the ability to inform the core of long-running background tasks.
base_detection
basic_block
binary_view: A view on binary data and queryable interface of a binary file.
calling_convention: Contains and provides information about different systems’ calling conventions to analysis.
collaboration: The collaboration API is unstable and as such will undergo breaking changes in the near future!
command: Provides commands for registering plugins and plugin actions.
component
confidence
custom_binary_view: An interface for providing your own BinaryViews to Binary Ninja.
data_buffer: A basic wrapper around an array of binary data
data_renderer
database
debuginfo: Parsers and providers of debug information to Binary Ninja.
demangle: Interfaces for demangling and simplifying mangled names in binaries.
disassembly
download: Interface for registering new download providers
enterprise
external_library
file_accessor
file_metadata
flowgraph: Interfaces for creating and displaying pretty CFGs in Binary Ninja.
function
function_recognizer
headless
high_level_il: WARNING This API is incomplete and subject to change in the near future!
interaction: Interfaces for asking the user for information: forms, opening files, etc.
language_representation
line_formatter
linear_view: APIs for accessing Binary Ninja’s linear view
llvm
logger: To use logging in your script, do something like:
low_level_il
main_thread
medium_level_il: WARNING This API is incomplete and subject to change in the near future!
metadata
platform: Contains all information related to the execution environment of the binary, mainly the calling conventions used
progress
project
rc: Reference counting for core Binary Ninja objects.
references
relocation
render_layer: Customize the presentation of Linear and Graph view output.
repository: Interaction with plugin repositories to install and manage plugins.
secrets_provider
section: Sections are crate::segment::Segments that are loaded into memory at run time
segment: Labeled segments in a binary file that aren’t loaded in to memory
settings: An interface for reading, writing, and creating new settings
string: String wrappers for core-owned strings and strings being passed to the core
symbol: Interfaces for the various kinds of symbols in a binary.
tags: Interfaces for creating and modifying tags in a BinaryView.
template_simplifier
type_archive
type_container
type_library
type_parser
type_printer
types
update
variable
websocket: Interface for registering new websocket providers
worker_thread
workflow

Structs§

VersionInfo

Enums§

BranchType
DataFlowQueryOption
Endianness
ILBranchDependence

Constants§

BN_FULL_CONFIDENCE
BN_INVALID_EXPR

Traits§

ObjectDestructor: The trait required for receiving core object destruction callbacks.

Functions§

CorePluginABIVersion
UIPluginABIVersion
add_optional_plugin_dependency
add_required_plugin_dependency
build_id
bundled_plugin_directory
core_abi_minimum_version
core_abi_version
install_directory
is_database
is_license_validated
is_main_thread: Returns if the running thread is the “main thread”
is_ui_enabled
license_count
license_expiration_time
license_path
licensed_user_email
load: The main way to open and load files into Binary Ninja. Make sure you’ve properly initialized the core before calling this function. See crate::headless::init()
load_view
load_view_with_progress: Equivalent to load_view but with a progress callback.
load_with_options: The main way to open and load files (with options) into Binary Ninja. Make sure you’ve properly initialized the core before calling this function. See crate::headless::init()
load_with_options_and_progress: Equivalent to load_with_options but with a progress callback.
load_with_progress: Equivalent to load but with a progress callback.
memory_info
path_relative_to_bundled_plugin_directory
path_relative_to_user_directory
path_relative_to_user_plugin_directory
plugin_abi_minimum_version
plugin_abi_version
plugin_ui_abi_minimum_version
plugin_ui_abi_version
product
product_type
repositories_directory
save_last_run: Write the installation directory of the currently running core instance to disk.
serial_number
set_bundled_plugin_directory
set_license: Set the license that will be used once the core initializes. You can reset the license by passing None.
settings_file_path
user_directory
user_plugin_directory
version
version_info

Crate binaryninjaCopy item path