Binary Ninja Python API Reference¶

Welcome to the Binary Ninja API documentation. The below methods are available from the root of the binaryninja package, but most of the API is organized into the modules shown in the left side-bar.

These pages are intended as an API Reference. For a deeper explanation of how different parts of Binary Ninja work, explanations of concepts, or if you’re new to Binary Ninja, you’ll want to check out our User Guide.

If you’re new to our API, we also have a Developer Guide which covers many of the concepts developers should know. There’s also a Cookbook which contains many examples to get you started using our API.

You can also scroll to the end to view a class list of all available classes.

The search bar on the side works both online and offline.

exception UIPluginInHeadlessError[source]¶

Bases: Exception

Error thrown when trying to load a UI plugin in a headless Binary Ninja installation.

__init__(*args, **kwargs)[source]¶

class CoreVersionInfo[source]¶

Bases: object

Structure representing the Binary Ninja Version.

Use core_version_info to look up the current version of Binary Ninja loaded.

Example:

>>> from binaryninja import core_version_info, CoreVersionInfo
>>> # Check if the current version meets minimum requirements for a plugin
>>> if core_version_info() >= CoreVersionInfo(5, 1, 8104):
...     print("Using new API available in 5.1.8104 and later")
>>> # Parse and compare against a version string
>>> if core_version_info() >= CoreVersionInfo("4.2.0"):
...     print("Version 4.2.0 or later detected")
>>> # Get individual version components
>>> version = core_version_info()
>>> print(f"Running Binary Ninja {version.major}.{version.minor}.{version.build}")

__init__(major, minor=None, build=None, channel=None)[source]¶

build: int¶

Build version number, e.g. 4.0.5000-dev would be 5000

channel: str¶

Release channel name, e.g. “dev” or “Stable”

major: int¶

Major version number, e.g. 4.0.5000-dev would be 4

minor: int¶

Minor version number, e.g. 4.0.5000-dev would be 0

class LicenseAddon[source]¶

Bases: object

A verified add-on attached to the active license.

__init__(id: str, license_serial: str, product: str, created: str, created_timestamp: int, expiration: str, expiration_timestamp: int, signature: str) → None¶

Parameters:

• id (str)

• license_serial (str)

• product (str)

• created (str)

• created_timestamp (int)

• expiration (str)

• expiration_timestamp (int)

• signature (str)

Return type:

None

created: str¶

created_timestamp: int¶

expiration: str¶

expiration_timestamp: int¶

id: str¶

license_serial: str¶

product: str¶

signature: str¶

bundled_plugin_path() → str | None[source]¶

bundled_plugin_path returns a string containing the current plugin path inside the install path

Returns:

current bundled plugin path

Return type:

str, or None on failure

connect_pycharm_debugger(port=5678)[source]¶

Connect to PyCharm (Professional Edition) for debugging.

Note

See the user documentation pycharm note for step-by-step instructions on how to set up Python debugging.

Parameters:

port – Port number for connecting to the debugger.

connect_vscode_debugger(port=5678)[source]¶

Connect to Visual Studio Code for debugging. This function blocks until the debugger is connected! Not recommended for use in startup.py

Note

See the user documentation vscode note for step-by-step instructions on how to set up Python debugging.

Parameters:

port – Port number for connecting to the debugger.

core_build_id() → int[source]¶

core_build_id returns a integer containing the current build id

Returns:

current build id

Return type:

int

core_expires() → struct_time[source]¶

License Expiration

Return type:

struct_time

core_license_addons() → List[LicenseAddon][source]¶

License addons from the license file

Return type:

List[LicenseAddon]

core_license_count() → int[source]¶

License count from the license file

Return type:

int

core_product() → str | None[source]¶

Product string from the license file

Return type:

str | None

core_product_type() → str | None[source]¶

Product type from the license file

Return type:

str | None

core_serial() → str | None[source]¶

core_serial returns a string containing the current serial number

Returns:

current serial

Return type:

str, or None on failure

core_set_license(licenseData: str) → None[source]¶

core_set_license is used to initialize the core with a license file that doesn’t necessarily reside on a file system. This is especially useful for headless environments such as docker where loading the license file via an environment variable allows for greater security of the license file itself.

Parameters:

licenseData (str) – string containing the full contents of a license file

Return type:

None

Example:

>>> import os
>>> core_set_license(os.environ['BNLICENSE']) #Do this before creating any BinaryViews
>>> with load("/bin/ls") as bv:
...             print(len(list(bv.functions)))
128

core_ui_enabled() → bool[source]¶

Indicates that a UI exists and the UI has invoked BNInitUI

Return type:

bool

core_version() → str | None[source]¶

core_version returns a string containing the current version

Returns:

current version

Return type:

str, or None on failure

core_version_info() → CoreVersionInfo[source]¶

core_version_info returns a CoreVersionInfo containing the current version information

Returns:

current version information

Return type:

CoreVersionInfo

disable_default_log() → None[source]¶

Disable default logging in headless mode for the current session. By default, logging in headless operation is controlled by the ‘python.log.minLevel’ settings.

Return type:

None

fuzzy_match_single(target, query) → int | None[source]¶

Fuzzy match a string against a query string. Returns a score that is higher for a more confident match, or None if the query does not match the target string.

Parameters:

• target – Target (larger) string

• query – Query (smaller) string

Returns:

Confidence of match, or None if the string doesn’t match

Return type:

int | None

get_install_directory()[source]¶

get_install_directory returns a string pointing to the installed binary currently running

get_memory_usage_info() → Mapping[str, int][source]¶

Get counts of various Binary Ninja objects in memory.

Returns:

Dictionary of {class name: count} for objects in memory

Return type:

Mapping[str, int]

get_stat_histograms() → Mapping[str, dict][source]¶

Get per-tag bit-length histograms gathered by StatCollector instrumentation.

Each entry maps a tag name to {"total": int, "buckets": [int; 65]} where buckets[k] counts samples whose value has bit_width == k (k in 0..64) and total is the sum of the sampled values. Empty unless a StatCollector was instantiated somewhere in the core during analysis.

Returns:

Dictionary of {tag name: {“total”: int, “buckets”: list[int]}}

Return type:

Mapping[str, dict]

get_system_cache_directory() → str | None[source]¶

Returns Binary Ninja’s system cache directory on the system.

Supported default locations:

• macOS: ~/Library/Caches/Binary Ninja

• Linux: $XDG_CACHE_HOME/Binary Ninja or ~/.cache/Binary Ninja

• Windows: %LOCALAPPDATA%/Binary Ninja/cache

Returns:

Returns a string containing the system cache directory, or None on failure.

Return type:

str | None

get_unique_identifier()[source]¶

Generate a GUID

Returns:

A GUID string

load(*args, **kwargs) → BinaryView[source]¶

Opens a BinaryView object.

Parameters:

• source (Union[str, bytes, bytearray, 'databuffer.DataBuffer', 'os.PathLike', 'project.ProjectFile']) – a file or byte stream to load into a virtual memory space

• update_analysis (bool) – whether or not to run update_analysis_and_wait after opening a BinaryView, defaults to True

• progress_func (callback) – optional function to be called with the current progress and total count for BNDB files only

• options (dict) – a dictionary in the form {setting identifier string : object value}

Returns:

returns a BinaryView object for the given filename

Return type:

BinaryView

Raises:

Exception – When a BinaryView could not be created

Note

The progress_func callback must return True to continue the load operation, False will abort the load operation.

Warning

The progress_func will only be called for BNDB files, not for any other file format due to a design limitation.

Example:

>>> from binaryninja import *
>>> with load("/bin/ls") as bv:
...     print(len(list(bv.functions)))
...
134

>>> with load(bytes.fromhex('5054ebfe'), options={'loader.platform' : 'x86'}) as bv:
...     print(len(list(bv.functions)))
...
1

Return type:

BinaryView

shutdown()[source]¶

shutdown cleanly shuts down the core, stopping all workers and closing all log files.

Note

This will be called automatically on script exit if you import the binaryninja module.

user_directory() → str | None[source]¶

user_directory returns a string containing the path to the user directory

Returns:

current user path

Return type:

str, or None on failure

user_plugin_path() → str | None[source]¶

user_plugin_path returns a string containing the current plugin path inside the user directory

Returns:

current user plugin path

Return type:

str, or None on failure