binaryninja.binaryview.BinaryView

class BinaryView(file_metadata=None, parent_view=None, handle=None)[source]

class BinaryView implements a view on binary data, and presents a queryable interface of a binary file. One key job of BinaryView is file format parsing which allows Binary Ninja to read, write, insert, remove portions of the file given a virtual address. For the purposes of this documentation we define a virtual address as the memory address that the various pieces of the physical file will be loaded at.

A binary file does not have to have just one BinaryView, thus much of the interface to manipulate disassembly exists within or is accessed through a BinaryView. All files are guaranteed to have at least the Raw BinaryView. The Raw BinaryView is simply a hex editor, but is helpful for manipulating binary files via their absolute addresses.

BinaryViews are plugins and thus registered with Binary Ninja at startup, and thus should never be instantiated directly as this is already done. The list of available BinaryViews can be seen in the BinaryViewType class which provides an iterator and map of the various installed BinaryViews:

>>> list(BinaryViewType)
[<view type: 'Raw'>, <view type: 'ELF'>, <view type: 'Mach-O'>, <view type: 'PE'>]
>>> BinaryViewType['ELF']
<view type: 'ELF'>

To open a file with a given BinaryView the following code can be used:

>>> bv = BinaryViewType['Mach-O'].open("/bin/ls")
>>> bv
<BinaryView: '/bin/ls', start 0x100000000, len 0xa000>

By convention in the rest of this document we will use bv to mean an open BinaryView of an executable file. When a BinaryView is open on an executable view, analysis does not automatically run, this can be done by running the update_analysis_and_wait() method which disassembles the executable and returns when all disassembly is finished:

>>> bv.update_analysis_and_wait()
>>>

Since BinaryNinja’s analysis is multi-threaded (depending on version) this can also be done in the background by using the update_analysis() method instead.

By standard python convention methods which start with ‘_’ should be considered private and should not be called externally. Additionally, methods which begin with perform_ should not be called either and are used explicitly for subclassing the BinaryView.

Note

An important note on the *_user_*() methods. Binary Ninja makes a distinction between edits performed by the user and actions performed by auto analysis. Auto analysis actions that can quickly be recalculated are not saved to the database. Auto analysis actions that take a long time and all user edits are stored in the database (e.g. remove_user_function() rather than remove_function()). Thus use _user_ methods if saving to the database is desired.

__init__(file_metadata=None, parent_view=None, handle=None)[source]

Initialize self. See help(type(self)) for accurate signature.

Methods

__init__([file_metadata, parent_view, handle])

Initialize self.

abort_analysis()

abort_analysis will abort the currently running analysis.

add_analysis_completion_event(callback)

add_analysis_completion_event sets up a call back function to be called when analysis has been completed.

add_analysis_option(name)

add_analysis_option adds an analysis option.

add_auto_section(name, start, length[, …])

add_auto_segment(start, length, data_offset, …)

add_entry_point(addr[, plat])

add_entry_point adds an virtual address to start analysis from for a given plat.

add_function(addr[, plat])

add_function add a new function of the given plat at the virtual address addr

add_undo_action(action)

add_user_section(name, start, length[, …])

add_user_segment(start, length, data_offset, …)

always_branch(addr[, arch])

always_branch convert the instruction of architecture arch at the virtual address addr to an unconditional branch.

begin_undo_actions()

begin_undo_actions start recording actions taken so the can be undone at some point.

commit_undo_actions()

commit_undo_actions commit the actions taken since the last commit to the undo database.

convert_to_nop(addr[, arch])

convert_to_nop converts the instruction at virtual address addr to a nop of the provided architecture.

create_database(filename[, progress_func])

create_database writes the current database (.bndb) file out to the specified file.

create_user_function(addr[, plat])

create_user_function add a new user function of the given plat at the virtual address addr

define_auto_symbol(sym)

define_auto_symbol adds a symbol to the internal list of automatically discovered Symbol objects in a given namespace.

define_auto_symbol_and_var_or_function(sym, …)

define_auto_symbol_and_var_or_function

define_data_var(addr, var_type)

define_data_var defines a non-user data variable var_type at the virtual address addr.

define_imported_function(import_addr_sym, func)

define_imported_function defines an imported Function func with a ImportedFunctionSymbol type.

define_type(type_id, default_name, type_obj)

define_type registers a Type type_obj of the given name in the global list of types for the current BinaryView.

define_user_data_var(addr, var_type)

define_user_data_var defines a user data variable var_type at the virtual address addr.

define_user_symbol(sym)

define_user_symbol adds a symbol to the internal list of user added Symbol objects.

define_user_type(name, type_obj)

define_user_type registers a Type type_obj of the given name in the global list of user types for the current BinaryView.

eval(expression[, here])

Evaluates an string expression to an integer value.

external_namespace()

External namespace for the current BinaryView

find_next_constant(start, constant[, settings])

find_next_constant searches for integer constant constant occurring in the linear view output starting at the virtual address start until the end of the BinaryView.

find_next_data(start, data[, flags])

find_next_data searches for the bytes data starting at the virtual address start until the end of the BinaryView.

find_next_text(start, text[, settings, flags])

find_next_text searches for string text occurring in the linear view output starting at the virtual address start until the end of the BinaryView.

get_address_for_data_offset(offset)

get_address_input(prompt, title[, …])

get_ascii_string_at(addr[, min_length, …])

get_ascii_string_at returns the string found at addr

get_basic_blocks_at(addr)

get_basic_blocks_at get a list of BasicBlock objects which exist at the provided virtual address.

get_basic_blocks_starting_at(addr)

get_basic_blocks_starting_at get a list of BasicBlock objects which start at the provided virtual address.

get_code_refs(addr[, length])

get_code_refs returns a list of ReferenceSource objects (xrefs or cross-references) that point to the provided virtual address.

get_data_refs(addr[, length])

get_data_refs returns a list of virtual addresses of data which references addr.

get_data_refs_from(addr[, length])

get_data_refs_from returns a list of virtual addresses referenced by the address addr.

get_data_var_at(addr)

get_data_var_at returns the data type at a given virtual address.

get_disassembly(addr[, arch])

get_disassembly simple helper function for printing disassembly of a given address

get_entropy(addr, length[, block_size])

get_entropy returns the shannon entropy given the start addr, length in bytes, and optionally in block_size chunks.

get_function_at(addr[, plat])

get_function_at gets a Function object for the function that starts at virtual address addr:

get_functions_at(addr)

get_functions_at get a list of binaryninja.Function objects (one for each valid plat) at the given virtual address.

get_functions_containing(addr)

get_functions_containing returns a list of functions which contain the given address or None on failure.

get_instruction_length(addr[, arch])

get_instruction_length returns the number of bytes in the instruction of Architecture arch at the virtual address addr

get_linear_disassembly(settings)

get_linear_disassembly gets an iterator for all lines in the linear disassembly of the view for the given disassembly settings.

get_linear_disassembly_position_at(addr, …)

get_linear_disassembly_position_at instantiates a LinearDisassemblyPosition object for use in get_previous_linear_disassembly_lines() or get_next_linear_disassembly_lines().

get_modification(addr[, length])

get_modification returns the modified bytes of up to length bytes from virtual address addr, or if length is None returns the ModificationStatus.

get_next_basic_block_start_after(addr)

get_next_basic_block_start_after returns the virtual address of the BasicBlock that occurs after the virtual

get_next_data_after(addr)

get_next_data_after retrieves the virtual address of the next non-code byte.

get_next_data_var_after(addr)

get_next_data_var_after retrieves the next DataVariable, or None.

get_next_data_var_start_after(addr)

get_next_data_var_start_after retrieves the next virtual address of the next DataVariable

get_next_disassembly([arch])

get_next_disassembly simple helper function for printing disassembly of the next instruction.

get_next_function_start_after(addr)

get_next_function_start_after returns the virtual address of the Function that occurs after the virtual address addr

get_next_linear_disassembly_lines(pos, settings)

get_next_linear_disassembly_lines retrieves a list of LinearDisassemblyLine objects for the next disassembly lines, and updates the LinearDisassemblyPosition passed in.

get_previous_basic_block_end_before(addr)

get_previous_basic_block_end_before

get_previous_basic_block_start_before(addr)

get_previous_basic_block_start_before returns the virtual address of the BasicBlock that occurs prior to the provided virtual address

get_previous_data_before(addr)

get_previous_data_before

get_previous_data_var_before(addr)

get_previous_data_var_before retrieves the previous DataVariable, or None.

get_previous_data_var_start_before(addr)

get_previous_data_var_start_before

get_previous_function_start_before(addr)

get_previous_function_start_before returns the virtual address of the Function that occurs prior to the virtual address provided

get_previous_linear_disassembly_lines(pos, …)

get_previous_linear_disassembly_lines retrieves a list of LinearDisassemblyLine objects for the previous disassembly lines, and updates the LinearDisassemblyPosition passed in.

get_recent_basic_block_at(addr)

get_recent_function_at(addr)

get_section_by_name(name)

get_sections_at(addr)

get_segment_at(addr)

get_string_at(addr[, partial])

get_string_at returns the string that falls on given virtual address.

get_strings([start, length])

get_strings returns a list of strings defined in the binary in the optional virtual address range: start-(start+length)

get_symbol_at(addr[, namespace])

get_symbol_at returns the Symbol at the provided virtual address.

get_symbol_by_raw_name(name[, namespace])

get_symbol_by_raw_name retrieves a Symbol object for the given a raw (mangled) name.

get_symbols([start, length, namespace])

get_symbols retrieves the list of all Symbol objects in the optionally provided range.

get_symbols_by_name(name[, namespace])

get_symbols_by_name retrieves a list of Symbol objects for the given symbol name.

get_symbols_of_type(sym_type[, start, …])

get_symbols_of_type retrieves a list of all Symbol objects of the provided symbol type in the optionally

get_type_by_id(id)

get_type_by_id returns the defined type whose unique identifier corresponds with the provided id

get_type_by_name(name)

get_type_by_name returns the defined type whose name corresponds with the provided name

get_type_id(name)

get_type_id returns the unique identifier of the defined type whose name corresponds with the provided name

get_type_name_by_id(id)

get_type_name_by_id returns the defined type name whose unique identifier corresponds with the provided id

get_unique_section_names(name_list)

get_view_of_type(name)

get_view_of_type returns the BinaryView associated with the provided name if it exists.

init()

insert(addr, data)

insert inserts the bytes in data to the virtual address addr.

internal_namespace()

Internal namespace for the current BinaryView

invert_branch(addr[, arch])

invert_branch convert the branch instruction of architecture arch at the virtual address addr to the inverse branch.

is_always_branch_patch_available(addr[, arch])

is_always_branch_patch_available queries the architecture plugin to determine if the instruction at addr can be made to always branch.

is_invert_branch_patch_available(addr[, arch])

is_invert_branch_patch_available queries the architecture plugin to determine if the instruction at addr is a branch that can be inverted.

is_never_branch_patch_available(addr[, arch])

is_never_branch_patch_available queries the architecture plugin to determine if the instruction at the instruction at addr can be made to never branch.

is_offset_code_semantics(addr)

is_offset_code_semantics checks if an virtual address addr is semantically valid for code.

is_offset_executable(addr)

is_offset_executable checks if an virtual address addr is valid for executing.

is_offset_extern_semantics(addr)

is_offset_extern_semantics checks if an virtual address addr is semantically valid for external references.

is_offset_readable(addr)

is_offset_readable checks if an virtual address addr is valid for reading.

is_offset_writable(addr)

is_offset_writable checks if an virtual address addr is valid for writing.

is_offset_writable_semantics(addr)

is_offset_writable_semantics checks if an virtual address addr is semantically writable.

is_skip_and_return_value_patch_available(addr)

is_skip_and_return_value_patch_available queries the architecture plugin to determine if the instruction at addr is similar to an x86 “call” instruction which can be made to return a value.

is_skip_and_return_zero_patch_available(addr)

is_skip_and_return_zero_patch_available queries the architecture plugin to determine if the instruction at addr is similar to an x86 “call” instruction which can be made to return zero.

is_type_auto_defined(name)

is_type_auto_defined queries the user type list of name.

is_valid_offset(addr)

is_valid_offset checks if an virtual address addr is valid .

navigate(view, offset)

never_branch(addr[, arch])

never_branch convert the branch instruction of architecture arch at the virtual address addr to a fall through.

new([data, file_metadata])

notify_data_inserted(offset, length)

notify_data_removed(offset, length)

notify_data_written(offset, length)

open(src[, file_metadata])

parse_expression(expression[, here])

Evaluates an string expression to an integer value.

parse_type_string(text)

parse_type_string converts C-style string into a Type.

perform_get_address_size()

perform_get_default_endianness()

perform_get_default_endianness implements a check which returns true if the BinaryView is executable.

perform_get_entry_point()

perform_get_entry_point implements a query for the initial entry point for code execution.

perform_get_length()

perform_get_length implements a query for the size of the virtual address range used by the BinaryView.

perform_get_modification(addr)

perform_get_modification implements query to the whether the virtual address addr is modified.

perform_get_next_valid_offset(addr)

perform_get_next_valid_offset implements a query for the next valid readable, writable, or executable virtual memory address.

perform_get_start()

perform_get_start implements a query for the first readable, writable, or executable virtual address in the BinaryView.

perform_insert(addr, data)

perform_insert implements a mapping between a virtual address and an absolute file offset, inserting the bytes data to rebased address addr.

perform_is_executable()

perform_is_executable implements a check which returns true if the BinaryView is executable.

perform_is_offset_executable(addr)

perform_is_offset_executable implements a check if a virtual address addr is executable.

perform_is_offset_readable(offset)

perform_is_offset_readable implements a check if an virtual address is readable.

perform_is_offset_writable(addr)

perform_is_offset_writable implements a check if a virtual address addr is writable.

perform_is_relocatable()

perform_is_relocatable implements a check which returns true if the BinaryView is relocatable.

perform_is_valid_offset(addr)

perform_is_valid_offset implements a check if an virtual address addr is valid.

perform_read(addr, length)

perform_read implements a mapping between a virtual address and an absolute file offset, reading length bytes from the rebased address addr.

perform_remove(addr, length)

perform_remove implements a mapping between a virtual address and an absolute file offset, removing length bytes from the rebased address addr.

perform_save(accessor)

perform_write(addr, data)

perform_write implements a mapping between a virtual address and an absolute file offset, writing the bytes data to rebased address addr.

query_metadata(key)

query_metadata retrieves a metadata associated with the given key stored in the current BinaryView.

read(addr, length)

read returns the data reads at most length bytes from virtual address addr.

reanalyze()

reanalyze causes all functions to be reanalyzed.

redo()

redo redo the last committed action in the undo database.

register()

register_notification(notify)

register_notification provides a mechanism for receiving callbacks for various analysis events.

register_platform_types(platform)

register_platform_types ensures that the platform-specific types for a Platform are available for the current BinaryView.

relocation_ranges_at(addr)

List of relocation range tuples for a given address

remove(addr, length)

remove removes at most length bytes from virtual address addr.

remove_auto_section(name)

remove_auto_segment(start, length)

remove_function(func)

remove_function removes the function func from the list of functions

remove_metadata(key)

remove_metadata removes the metadata associated with key from the current BinaryView.

remove_user_function(func)

remove_user_function removes the user function func from the list of functions

remove_user_section(name)

remove_user_segment(start, length)

rename_type(old_name, new_name)

rename_type renames a type in the global list of types for the current BinaryView

save(dest)

save saves the original binary file to the provided destination dest along with any modifications.

save_auto_snapshot([progress_func])

save_auto_snapshot saves the current database to the already created file.

set_default_session_data(name, value)

set_default_session_data saves a variable to the BinaryView.

show_graph_report(title, graph)

show_html_report(title, contents[, plaintext])

show_html_report displays the HTML contents in UI applications and plaintext in command-line applications.

show_markdown_report(title, contents[, …])

show_markdown_report displays the markdown contents in UI applications and plaintext in command-line applications.

show_plain_text_report(title, contents)

skip_and_return_value(addr, value[, arch])

skip_and_return_value convert the call instruction of architecture arch at the virtual address addr to the equivalent of returning a value.

store_metadata(key, md)

store_metadata stores an object for the given key in the current BinaryView.

undefine_auto_symbol(sym)

undefine_auto_symbol removes a symbol from the internal list of automatically discovered Symbol objects.

undefine_data_var(addr)

undefine_data_var removes the non-user data variable at the virtual address addr.

undefine_type(type_id)

undefine_type removes a Type from the global list of types for the current BinaryView

undefine_user_data_var(addr)

undefine_user_data_var removes the user data variable at the virtual address addr.

undefine_user_symbol(sym)

undefine_user_symbol removes a symbol from the internal list of user added Symbol objects.

undefine_user_type(name)

undefine_user_type removes a Type from the global list of user types for the current BinaryView

undo()

undo undo the last committed action in the undo database.

unregister_notification(notify)

unregister_notification unregisters the BinaryDataNotification object passed to register_notification

update_analysis()

update_analysis asynchronously starts the analysis running and returns immediately.

update_analysis_and_wait()

update_analysis_and_wait blocking call to update the analysis, this call returns when the analysis is complete.

write(addr, data)

write writes the bytes in data to the virtual address addr.

Attributes

address_size

Address size of the binary (read-only)

allocated_ranges

List of valid address ranges for this view (read-only)

analysis_changed

boolean analysis state changed of the currently running analysis (read-only)

analysis_info

Provides instantaneous analysis state information and a list of current functions under analysis (read-only).

analysis_progress

Status of current analysis (read-only)

arch

The architecture associated with the current BinaryView (read/write)

available_view_types

Available view types (read-only)

basic_blocks

A generator of all BasicBlock objects in the BinaryView

data_vars

List of data variables (read-only)

end

End offset of the binary (read-only)

endianness

Endianness of the binary (read-only)

entry_function

Entry function (read-only)

entry_point

Entry point of the binary (read-only)

executable

Whether the binary is an executable (read-only)

file

FileMetadata backing the BinaryView

functions

List of functions (read-only)

global_pointer_value

Discovered value of the global pointer register, if the binary uses one (read-only)

has_database

boolean has a database been written to disk (read-only)

has_functions

Boolean whether the binary has functions (read-only)

instructions

A generator of instruction tokens and their start addresses

linear_disassembly

Iterator for all lines in the linear disassembly of the view

llil_basic_blocks

A generator of all LowLevelILBasicBlock objects in the BinaryView

llil_instructions

A generator of llil instructions

long_name

max_function_size_for_analysis

Maximum size of function (sum of basic block sizes in bytes) for auto analysis

mlil_basic_blocks

A generator of all MediumLevelILBasicBlock objects in the BinaryView

mlil_instructions

A generator of mlil instructions

modified

boolean modification state of the BinaryView (read/write)

name

namespaces

Returns a list of namespaces for the current BinaryView

new_auto_function_analysis_suppressed

Whether or not automatically discovered functions will be analyzed

next_address

FileMetadata backing the BinaryView

notifications

FileMetadata backing the BinaryView

offset

parameters_for_analysis

parent_view

View that contains the raw data used by this view (read-only)

platform

The platform associated with the current BinaryView (read/write)

registered_view_type

relocatable

Boolean - is the binary relocatable (read-only)

relocation_ranges

List of relocation range tuples (read-only)

saved

boolean state of whether or not the file has been saved (read/write)

sections

List of sections (read-only)

segments

List of segments (read-only)

session_data

Dictionary object where plugins can store arbitrary data associated with the view

start

Start offset of the binary (read-only)

strings

List of strings (read-only)

symbols

Dict of symbols (read-only)

type_names

List of defined type names (read-only)

types

List of defined types (read-only)

view

view_type

View type (read-only)