Binary Ninja Python API Reference¶

Welcome to the Binary Ninja API documentation. The below methods are availablefrom the root of thebinaryninja package, but most of the API is organizedinto the modules shown in the left side-bar.

These pages are intended as an API Reference. For a deeper explanation of howdifferent parts of Binary Ninja work, explanations of concepts, or if you’renew to Binary Ninja, you’ll want to check out ourUser Guide.

If you’re new to our API, we also have aDeveloper Guidewhich covers many of the concepts developers should know. There’s also aCookbook which contains manyexamples 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.

exceptionUIPluginInHeadlessError[source]¶

Bases:Exception

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

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

classCoreVersionInfo[source]¶

Bases:object

Structure representing the Binary Ninja Version.

Usecore_version_info to look up the current version of Binary Ninja loaded.

Example:

>>>frombinaryninjaimportcore_version_info,CoreVersionInfo>>># Check if the current version meets minimum requirements for a plugin>>>ifcore_version_info()>=CoreVersionInfo(5,1,8104):...print("Using new API available in 5.1.8104 and later")>>># Parse and compare against a version string>>>ifcore_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

bundled_plugin_path()→str|None[source]¶

bundled_plugin_path returns a string containing the current plugin path inside theinstall 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 documentationpycharm 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 debuggeris connected! Not recommended for use in startup.py

Note

See the user documentationvscode 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_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:

>>>importos>>>core_set_license(os.environ['BNLICENSE'])#Do this before creating any BinaryViews>>>withload("/bin/ls")asbv:...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 fora 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_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']) – a file or byte stream to load into a virtual memory space

• update_analysis (bool) – whether or not to runupdate_analysis_and_wait after opening aBinaryView, defaults toTrue

• 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 aBinaryView object for the given filename

Return type:

BinaryView

Raises:

Exception – When a BinaryView could not be created

Note

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

Warning

The progress_func willonly be called for BNDB files, not for any other file format due to adesign limitation.

Example:

>>>frombinaryninjaimport*>>>withload("/bin/ls")asbv:...print(len(list(bv.functions)))...134

>>>withload(bytes.fromhex('5054ebfe'),options={'loader.platform':'x86'})asbv:...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 theuser 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 theuser directory

Returns:

current user plugin path

Return type:

str, or None on failure