binaryninja.binaryview.BinaryView¶
-
class
binaryninja.binaryview.
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. TheRaw
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. Additionanlly, 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 thanremove_function()
). Thus use_user_
methods if saving to the database is desired.Methods
__init__
([file_metadata, parent_view, handle])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. Analysis options elaborate the analysis phase. The user mustadd_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 givenplat
at the virtual addressaddr
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 architecturearch
at the virtual addressaddr
to anbegin_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 addressaddr
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 givenplat
at the virtual addressaddr
define_auto_symbol
(sym)define_auto_symbol
adds a symbol to the internal list of automatically discovered Symbol objects.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 variablevar_type
at the virtual addressaddr
.define_imported_function
(import_addr_sym, func)define_imported_function
defines an imported Functionfunc
with a ImportedFunctionSymbol type.define_type
(type_id, default_name, type_obj)define_type
registers aType
type_obj
of the givenname
in the global list of types fordefine_user_data_var
(addr, var_type)define_user_data_var
defines a user data variablevar_type
at the virtual addressaddr
.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 aType
type_obj
of the givenname
in the global list of userfind_next_data
(start, data[, flags])find_next_data
searchs for the bytes in data starting at the virtual addressstart
either, case-sensitive,get_address_for_data_offset
(offset)get_address_input
(prompt, title[, ...])get_basic_blocks_at
(addr)get_basic_blocks_at
get a list ofBasicBlock
objects which exist at the provided virtual address.get_basic_blocks_starting_at
(addr)get_basic_blocks_starting_at
get a list ofBasicBlock
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_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 addressget_function_at
(addr[, plat])get_function_at
gets a Function object for the function that starts at virtual addressaddr
:get_functions_at
(addr)get_functions_at
get a list of binaryninja.Function objects (one for each valid plat) at the givenget_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 Architecturearch
at the virtualget_linear_disassembly
(settings)get_linear_disassembly
gets an iterator for all lines in the linear disassembly of the view for the givenget_linear_disassembly_position_at
(addr, ...)get_linear_disassembly_position_at
instantiates aLinearDisassemblyPosition
object for use inget_modification
(addr[, length])get_modification
returns the modified bytes of up tolength
bytes from virtual addressaddr
, or ifget_next_basic_block_start_after
(addr)get_next_basic_block_start_after
returns the virtual address of the BasicBlock that occurs after the virtualget_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 virtual address of the nextDataVariable
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 addressget_next_linear_disassembly_lines
(pos, settings)get_next_linear_disassembly_lines
retrieves a list ofLinearDisassemblyLine
objects for theget_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 theget_previous_data_before
(addr)get_previous_data_before
get_previous_data_var_before
(addr)get_previous_data_var_before
get_previous_function_start_before
(addr)get_previous_function_start_before
returns the virtual address of the Function that occurs prior to theget_previous_linear_disassembly_lines
(pos, ...)get_previous_linear_disassembly_lines
retrieves a list ofLinearDisassemblyLine
objects for theget_recent_basic_block_at
(addr)get_recent_function_at
(addr)get_section_by_name
(name)get_sections_at
(addr)get_segment_at
(addr)get_strings
([start, length])get_strings
returns a list of strings defined in the binary in the optional virtual address range:get_symbol_at
(addr)get_symbol_at
returns the Symbol at the provided virtual address.get_symbol_by_raw_name
(name)get_symbol_by_raw_name
retrieves a Symbol object for the given a raw (mangled) name.get_symbols
([start, length])get_symbols
retrieves the list of all Symbol objects in the optionally provided range.get_symbols_by_name
(name)get_symbols_by_name
retrieves a list of Symbol objects for the given symbol name.get_symbols_of_type
(sym_type[, start, length])get_symbols_of_type
retrieves a list of all Symbol objects of the provided symbol type in the optionallyget_type_by_id
(id)get_type_by_id
returns the defined type whose unique identifier corresponds with the providedid
get_type_by_name
(name)get_type_by_name
returns the defined type whose name corresponds with the providedname
get_type_id
(name)get_type_id
returns the unique indentifier of the defined type whose name corresponds with theget_type_name_by_id
(id)get_type_name_by_id
returns the defined type name whose unique identifier corresponds with the providedid
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 indata
to the virtual addressaddr
.invert_branch
(addr[, arch])invert_branch
convert the branch instruction of architecturearch
at the virtual addressaddr
to theis_always_branch_patch_available
(addr[, arch])is_always_branch_patch_available
queries the architecture plugin to determine if theis_invert_branch_patch_available
(addr[, arch])is_invert_branch_patch_available
queries the architecture plugin to determine if the instruction ataddr
is_never_branch_patch_available
(addr[, arch])is_never_branch_patch_available
queries the architecture plugin to determine if the instruction at theis_offset_code_semantics
(addr)is_offset_code_semantics
checks if an virtual addressaddr
is semantically valid for code.is_offset_executable
(addr)is_offset_executable
checks if an virtual addressaddr
is valid for executing.is_offset_readable
(addr)is_offset_readable
checks if an virtual addressaddr
is valid for reading.is_offset_writable
(addr)is_offset_writable
checks if an virtual addressaddr
is valid for writing.is_offset_writable_semantics
(addr)is_offset_writable_semantics
checks if an virtual addressaddr
is semantically writable. Some sectionsis_skip_and_return_value_patch_available
(addr)is_skip_and_return_value_patch_available
queries the architecture plugin to determine if theis_skip_and_return_zero_patch_available
(addr)is_skip_and_return_zero_patch_available
queries the architecture plugin to determine if theis_type_auto_defined
(name)is_type_auto_defined
queries the user type list of name. If name is not in the user type list then the nameis_valid_offset
(addr)is_valid_offset
checks if an virtual addressaddr
is valid .navigate
(view, offset)never_branch
(addr[, arch])never_branch
convert the branch instruction of architecturearch
at the virtual addressaddr
tonew
([data, file_metadata])notify_data_inserted
(offset, length)notify_data_removed
(offset, length)notify_data_written
(offset, length)open
(src[, file_metadata])parse_type_string
(text)parse_type_string
converts C-style string into aType
.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 byperform_get_modification
(addr)perform_get_modification
implements query to the whether the virtual addressaddr
is modified.perform_get_next_valid_offset
(addr)perform_get_next_valid_offset
implements a query for the next valid readable, writable, or executable virtualperform_get_start
()perform_get_start
implements a query for the first readable, writable, or executable virtual address inperform_insert
(addr, data)perform_insert
implements a mapping between a virtual address and an absolute file offset, insertingperform_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 addressaddr
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 addressaddr
is writable.perform_is_relocatable
()perform_is_relocatable
implements a check which returns true if the BinaryView is relocatable. Defaults toperform_is_valid_offset
(addr)perform_is_valid_offset
implements a check if an virtual addressaddr
is valid.perform_read
(addr, length)perform_read
implements a mapping between a virtual address and an absolute file offset, readingperform_remove
(addr, length)perform_remove
implements a mapping between a virtual address and an absolute file offset, removingperform_save
(accessor)perform_write
(addr, data)perform_write
implements a mapping between a virtual address and an absolute file offset, writingquery_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 mostlength
bytes from virtual addressaddr
.reanalyze
()reanalyze
causes all functions to be reanalyzed. This function does not wait for the analysis to finish.redo
()redo
redo the last commited action in the undo database.register
()register_notification
(notify)register_notification provides a mechanism for receiving callbacks for various analysis events. A full register_platform_types
(platform)register_platform_types
ensures that the platform-specific types for aPlatform
are availableremove
(addr, length)remove
removes at mostlength
bytes from virtual addressaddr
.remove_auto_section
(name)remove_auto_segment
(start, length)remove_function
(func)remove_function
removes the functionfunc
from the list of functionsremove_metadata
(key)remove_metadata removes the metadata associated with key from the current BinaryView. remove_user_function
(func)remove_user_function
removes the user functionfunc
from the list of functionsremove_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 currentBinaryView
save
(dest)save
saves the original binary file to the provided destinationdest
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_html_report
(title, contents[, plaintext])show_markdown_report
(title, contents[, ...])show_plain_text_report
(title, contents)skip_and_return_value
(addr, value[, arch])skip_and_return_value
convert thecall
instruction of architecturearch
at the virtual addressstore_metadata
(key, md)store_metadata stores an object for the given key in the current BinaryView. Objects stored using 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 addressaddr
.undefine_type
(type_id)undefine_type
removes aType
from the global list of types for the currentBinaryView
undefine_user_data_var
(addr)undefine_user_data_var
removes the user data variable at the virtual addressaddr
.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 aType
from the global list of user types for the currentundo
()undo
undo the last commited action in the undo database.unregister_notification
(notify)unregister_notification unregisters the BinaryDataNotification
object passed toupdate_analysis
()update_analysis
asynchronously starts the analysis running and returns immediately. Analysis of BinaryViewsupdate_analysis_and_wait
()update_analysis_and_wait
blocking call to update the analysis, this call returns when the analysis iswrite
(addr, data)write
writes the bytes indata
to the virtual addressaddr
.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
Relevant analysis information with list of functions under active 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) 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
next_address
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) 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) types
List of defined types (read-only) view
view_type
View type (read-only)