binaryview module

binaryninja.binaryview.ActiveAnalysisInfo(…)
binaryninja.binaryview.AddressRange(start, end)
binaryninja.binaryview.AnalysisCompletionEvent(…)	The AnalysisCompletionEvent object provides an asynchronous mechanism for receiving callbacks when analysis is complete.
binaryninja.binaryview.AnalysisInfo(state, …)
binaryninja.binaryview.AnalysisProgress(…)
binaryninja.binaryview.BinaryDataNotification()
binaryninja.binaryview.BinaryDataNotificationCallbacks(…)
binaryninja.binaryview.BinaryReader(view[, …])	class BinaryReader is a convenience class for reading binary data.
binaryninja.binaryview.BinaryView([…])	class BinaryView implements a view on binary data, and presents a queryable interface of a binary file.
binaryninja.binaryview.BinaryViewType(handle)
binaryninja.binaryview.BinaryWriter(view[, …])	class BinaryWriter is a convenience class for writing binary data.
binaryninja.binaryview.DataVariable(addr, …)
binaryninja.binaryview.OrderedDict(**kwds)	Dictionary that remembers insertion order
binaryninja.binaryview.Section(handle)
binaryninja.binaryview.Segment(handle)
binaryninja.binaryview.StringReference(bv, …)
binaryninja.binaryview.StructuredDataValue(…)
binaryninja.binaryview.StructuredDataView(bv, …)	class StructuredDataView is a convenience class for reading structured binary data.
binaryninja.binaryview.range(*args)	A Python2 and Python3 Compatible Range Generator
binaryninja.binaryview.with_metaclass(meta, …)	Create a base class with a metaclass.

class ActiveAnalysisInfo(func, analysis_time, update_count, submit_count)

Bases: object

class AddressRange(start, end)

Bases: object

length

class AnalysisCompletionEvent(view, callback)

Bases: object

The AnalysisCompletionEvent object provides an asynchronous mechanism for receiving callbacks when analysis is complete. The callback runs once. A completion event must be added for each new analysis in order to be notified of each analysis completion. The AnalysisCompletionEvent class takes responsibility for keeping track of the object’s lifetime.

Example:

>>> def on_complete(self):
...     print("Analysis Complete", self.view)
...
>>> evt = AnalysisCompletionEvent(bv, on_complete)
>>>

cancel()

shut down and no further analysis should be done afterward.

class AnalysisInfo(state, analysis_time, active_info)

Bases: object

class AnalysisProgress(state, count, total)

Bases: object

class BinaryDataNotification

Bases: object

data_inserted(view, offset, length)

data_removed(view, offset, length)

data_var_added(view, var)

data_var_removed(view, var)

data_var_updated(view, var)

data_written(view, offset, length)

function_added(view, func)

function_removed(view, func)

function_update_requested(view, func)

function_updated(view, func)

string_found(view, string_type, offset, length)

string_removed(view, string_type, offset, length)

type_defined(view, name, type)

type_undefined(view, name, type)

class BinaryDataNotificationCallbacks(view, notify)

Bases: object

class BinaryReader(view, endian=None)

Bases: object

class BinaryReader is a convenience class for reading binary data.

BinaryReader can be instantiated as follows and the rest of the document will start from this context

>>> from binaryninja import *
>>> bv = BinaryViewType['Mach-O'].open("/bin/ls")
>>> br = BinaryReader(bv)
>>> hex(br.read32())
'0xfeedfacfL'
>>>

Or using the optional endian parameter

>>> from binaryninja import *
>>> br = BinaryReader(bv, Endianness.BigEndian)
>>> hex(br.read32())
'0xcffaedfeL'
>>>

read(length)

read returns length bytes read from the current offset, adding length to offset.

Parameters:

length (int) – number of bytes to read.

Returns:

length bytes from current offset

Return type:

str, or None on failure

Example:

>>> br.read(8)
'\xcf\xfa\xed\xfe\x07\x00\x00\x01'
>>>

read16()

read16 returns a two byte integer from offset incrementing the offset by two, using specified endianness.

Returns:

a two byte integer at offset.

Return type:

int, or None on failure

Example:

>>> br.seek(0x100000000)
>>> hex(br.read16())
'0xfacf'
>>>

read16be()

read16be returns a two byte big endian integer from offset incrementing the offset by two.

Returns:

a two byte integer at offset.

Return type:

int, or None on failure

Example:

>>> br.seek(0x100000000)
>>> hex(br.read16be())
'0xcffa'
>>>

read16le()

read16le returns a two byte little endian integer from offset incrementing the offset by two.

Returns:

a two byte integer at offset.

Return type:

int, or None on failure

Exmaple:

>>> br.seek(0x100000000)
>>> hex(br.read16le())
'0xfacf'
>>>

read32()

read32 returns a four byte integer from offset incrementing the offset by four, using specified endianness.

Returns:

a four byte integer at offset.

Return type:

int, or None on failure

Example:

>>> br.seek(0x100000000)
>>> hex(br.read32())
'0xfeedfacfL'
>>>

read32be()

read32be returns a four byte big endian integer from offset incrementing the offset by four.

Returns:

a four byte integer at offset.

Return type:

int, or None on failure

Example:

>>> br.seek(0x100000000)
>>> hex(br.read32be())
'0xcffaedfe'
>>>

read32le()

read32le returns a four byte little endian integer from offset incrementing the offset by four.

Returns:

a four byte integer at offset.

Return type:

int, or None on failure

Example:

>>> br.seek(0x100000000)
>>> hex(br.read32le())
'0xfeedfacf'
>>>

read64()

read64 returns an eight byte integer from offset incrementing the offset by eight, using specified endianness.

Returns:

an eight byte integer at offset.

Return type:

int, or None on failure

Example:

>>> br.seek(0x100000000)
>>> hex(br.read64())
'0x1000007feedfacfL'
>>>

read64be()

read64be returns an eight byte big endian integer from offset incrementing the offset by eight.

Returns:

a eight byte integer at offset.

Return type:

int, or None on failure

Example:

>>> br.seek(0x100000000)
>>> hex(br.read64be())
'0xcffaedfe07000001L'

read64le()

read64le returns an eight byte little endian integer from offset incrementing the offset by eight.

Returns:

a eight byte integer at offset.

Return type:

int, or None on failure

Example:

>>> br.seek(0x100000000)
>>> hex(br.read64le())
'0x1000007feedfacf'
>>>

read8()

read8 returns a one byte integer from offset incrementing the offset.

Returns:

byte at offset.

Return type:

int, or None on failure

Example:

>>> br.seek(0x100000000)
>>> br.read8()
207
>>>

seek(offset)

seek update internal offset to offset.

Parameters:

offset (int) – offset to set the internal offset to

Return type:

None

Example:

>>> hex(br.offset)
'0x100000008L'
>>> br.seek(0x100000000)
>>> hex(br.offset)
'0x100000000L'
>>>

seek_relative(offset)

seek_relative updates the internal offset by offset.

Parameters:

offset (int) – offset to add to the internal offset

Return type:

None

Example:

>>> hex(br.offset)
'0x100000008L'
>>> br.seek_relative(-8)
>>> hex(br.offset)
'0x100000000L'
>>>

endianness

The Endianness to read data. (read/write)

Getter:returns the endianness of the reader Setter:sets the endianness of the reader (BigEndian or LittleEndian) Type:Endianness

eof

Is end of file (read-only)

Getter:returns boolean, true if end of file, false otherwise Type:bool

offset

The current read offset (read/write).

Getter:returns the current internal offset Setter:sets the internal offset Type:int

class BinaryView(file_metadata=None, parent_view=None, handle=None)

Bases: object

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.

abort_analysis()

abort_analysis will abort the currently running analysis.

Return type:None

add_analysis_completion_event(callback)

add_analysis_completion_event sets up a call back function to be called when analysis has been completed. This is helpful when using update_analysis which does not wait for analysis completion before returning.

The callee of this function is not responsible for maintaining the lifetime of the returned AnalysisCompletionEvent object.

Parameters:

callback (callable()) – A function to be called with no parameters when analysis has completed.

Returns:

An initialized AnalysisCompletionEvent object.

Return type:

AnalysisCompletionEvent

Example:

>>> def completionEvent():
...   print("done")
...
>>> bv.add_analysis_completion_event(completionEvent)
<binaryninja.AnalysisCompletionEvent object at 0x10a2c9f10>
>>> bv.update_analysis()
done
>>>

add_analysis_option(name)

add_analysis_option adds an analysis option. Analysis options elaborate the analysis phase. The user must start analysis by calling either update_analysis() or update_analysis_and_wait().

Parameters:

name (str) – name of the analysis option. Available options: “linearsweep” : apply linearsweep analysis during the next analysis update (run-once semantics)

Return type:

None

Example:

>>> bv.add_analysis_option("linearsweep")
>>> bv.update_analysis_and_wait()

add_auto_section(name, start, length, semantics=<SectionSemantics.DefaultSectionSemantics: 0>, type='', align=1, entry_size=1, linked_section='', info_section='', info_data=0)

add_auto_segment(start, length, data_offset, data_length, flags)

add_entry_point(addr, plat=None)

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

Parameters:

• addr (int) – virtual address to start analysis from
• plat (Platform) – Platform for the entry point analysis

Return type:

None

Example:

>>> bv.add_entry_point(0xdeadbeef)
>>>

add_function(addr, plat=None)

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

Parameters:

• addr (int) – virtual address of the function to be added
• plat (Platform) – Platform for the function to be added

Return type:

None

Example:

>>> bv.add_function(1)
>>> bv.functions
[<func: x86_64@0x1>]

add_undo_action(action)

add_user_section(name, start, length, semantics=<SectionSemantics.DefaultSectionSemantics: 0>, type='', align=1, entry_size=1, linked_section='', info_section='', info_data=0)

add_user_segment(start, length, data_offset, data_length, flags)

always_branch(addr, arch=None)

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

Note

This API performs a binary patch, analysis may need to be updated afterward. Additionally the binary file must be saved in order to preserve the changes made.

Parameters:

• addr (int) – virtual address of the instruction to be modified
• arch (Architecture) – (optional) the architecture of the instructions if different from the default

Returns:

True on success, False on failure.

Return type:

bool

Example:

>>> bv.get_disassembly(0x100012ef)
'jg      0x100012f5'
>>> bv.always_branch(0x100012ef)
True
>>> bv.get_disassembly(0x100012ef)
'jmp     0x100012f5'
>>>

begin_undo_actions()

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

Return type:

None

Example:

>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> bv.begin_undo_actions()
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.commit_undo_actions()
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>>

commit_undo_actions()

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

Return type:

None

Example:

>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> bv.begin_undo_actions()
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.commit_undo_actions()
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>>

convert_to_nop(addr, arch=None)

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

Note

This API performs a binary patch, analysis may need to be updated afterward. Additionally the binary file must be saved in order to preserve the changes made.

Parameters:

• addr (int) – virtual address of the instruction to convert to nops
• arch (Architecture) – (optional) the architecture of the instructions if different from the default

Returns:

True on success, False on failure.

Return type:

bool

Example:

>>> bv.get_disassembly(0x100012fb)
'call    0x10001629'
>>> bv.convert_to_nop(0x100012fb)
True
>>> #The above 'call' instruction is 5 bytes, a nop in x86 is 1 byte,
>>> # thus 5 nops are used:
>>> bv.get_disassembly(0x100012fb)
'nop'
>>> bv.get_next_disassembly()
'nop'
>>> bv.get_next_disassembly()
'nop'
>>> bv.get_next_disassembly()
'nop'
>>> bv.get_next_disassembly()
'nop'
>>> bv.get_next_disassembly()
'mov     byte [ebp-0x1c], al'

create_database(filename, progress_func=None)

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

Parameters:

• filename (str) – path and filename to write the bndb to, this string should have “.bndb” appended to it.
• progress_func (callable()) – optional function to be called with the current progress and total count.

Returns:

true on success, false on failure

Return type:

bool

create_user_function(addr, plat=None)

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

Parameters:

• addr (int) – virtual address of the user function to be added
• plat (Platform) – Platform for the function to be added

Return type:

None

Example:

>>> bv.create_user_function(1)
>>> bv.functions
[<func: x86_64@0x1>]

define_auto_symbol(sym)

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

Warning

If multiple symbols for the same address are defined, only the most recent symbol will ever be used.

Parameters:sym (Symbol) – the symbol to define Return type:None

define_auto_symbol_and_var_or_function(sym, sym_type, plat=None)

define_auto_symbol_and_var_or_function

Warning

If multiple symbols for the same address are defined, only the most recent symbol will ever be used.

Parameters:

• sym (Symbol) – the symbol to define
• sym_type (SymbolType) – Type of symbol being defined
• plat (Platform) – (optional) platform

Return type:

None

define_data_var(addr, var_type)

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

Parameters:

• addr (int) – virtual address to define the given data variable
• var_type (Type) – type to be defined at the given virtual address

Return type:

None

Example:

>>> t = bv.parse_type_string("int foo")
>>> t
(<type: int32_t>, 'foo')
>>> bv.define_data_var(bv.entry_point, t[0])
>>>

define_imported_function(import_addr_sym, func)

define_imported_function defines an imported Function func with a ImportedFunctionSymbol type.

Parameters:

• import_addr_sym (Symbol) – A Symbol object with type ImportedFunctionSymbol
• func (Function) – A Function object to define as an imported function

Return type:

None

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. This method should only be used for automatically generated types.

Parameters:

• type_id (str) – Unique identifier for the automatically generated type
• default_name (QualifiedName) – Name of the type to be registered
• type_obj (Type) – Type object to be registered

Returns:

Registered name of the type. May not be the same as the requested name if the user has renamed types.

Return type:

QualifiedName

Example:

>>> type, name = bv.parse_type_string("int foo")
>>> registered_name = bv.define_type(Type.generate_auto_type_id("source", name), name, type)
>>> bv.get_type_by_name(registered_name)
<type: int32_t>

define_user_data_var(addr, var_type)

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

Parameters:

• addr (int) – virtual address to define the given data variable
• var_type (binaryninja.Type) – type to be defined at the given virtual address

Return type:

None

Example:

>>> t = bv.parse_type_string("int foo")
>>> t
(<type: int32_t>, 'foo')
>>> bv.define_user_data_var(bv.entry_point, t[0])
>>>

define_user_symbol(sym)

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

Warning

If multiple symbols for the same address are defined, only the most recent symbol will ever be used.

Parameters:sym (Symbol) – the symbol to define Return type:None

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.

Parameters:

• name (QualifiedName) – Name of the user type to be registered
• type_obj (Type) – Type object to be registered

Return type:

None

Example:

>>> type, name = bv.parse_type_string("int foo")
>>> bv.define_user_type(name, type)
>>> bv.get_type_by_name(name)
<type: int32_t>

eval(expression, here=0)

Evaluates an string expression to an integer value. This is a more concise alias for the parse_expression API See parse_expression for details on usage.

classmethod external_namespace()

External namespace for the current BinaryView

find_next_constant(start, constant, settings=None)

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.

Parameters:

• start (int) – virtual address to start searching from.
• constant (int) – constant to search for

find_next_data(start, data, flags=<FindFlag.FindCaseSensitive: 0>)

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

Parameters:

• start (int) – virtual address to start searching from.
• data (str) – data to search for
• flags (FindFlag) – (optional) defaults to case-insensitive data search

find_next_text(start, text, settings=None, flags=<FindFlag.FindCaseSensitive: 0>)

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.

Parameters:

• start (int) – virtual address to start searching from.
• text (str) – text to search for
• flags (FindFlag) – (optional) defaults to case-insensitive data search

get_address_for_data_offset(offset)

get_address_input(prompt, title, current_address=None)

get_basic_blocks_at(addr)

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

Parameters:addr (int) – virtual address of BasicBlock desired Returns:a list of BasicBlock objects Return type:list(BasicBlock)

get_basic_blocks_starting_at(addr)

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

Parameters:addr (int) – virtual address of BasicBlock desired Returns:a list of BasicBlock objects Return type:list(BasicBlock)

get_code_refs(addr, length=None)

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

Parameters:

addr (int) – virtual address to query for references

Returns:

List of References for the given virtual address

Return type:

list(ReferenceSource)

Example:

>>> bv.get_code_refs(here)
[<ref: x86@0x4165ff>]
>>>

get_data_refs(addr, length=None)

get_data_refs returns a list of virtual addresses of data which references addr. Optionally specifying a length. When length is set get_data_refs returns the data which references in the range addr-addr``+``length.

Parameters:

• addr (int) – virtual address to query for references
• length (int) – optional length of query

Returns:

list of integers

Return type:

list(integer)

Example:

>>> bv.get_data_refs(here)
[4203812]
>>>

get_data_refs_from(addr, length=None)

get_data_refs_from returns a list of virtual addresses referenced by the address addr. Optionally specifying a length. When length is set get_data_refs_from returns the data referenced in the range addr-addr``+``length.

Parameters:

• addr (int) – virtual address to query for references
• length (int) – optional length of query

Returns:

list of integers

Return type:

list(integer)

Example:

>>> bv.get_data_refs_from(here)
[4200327]
>>>

get_data_var_at(addr)

get_data_var_at returns the data type at a given virtual address.

Parameters:

addr (int) – virtual address to get the data type from

Returns:

returns the DataVariable at the given virtual address, None on error.

Return type:

DataVariable

Example:

>>> t = bv.parse_type_string("int foo")
>>> bv.define_data_var(bv.entry_point, t[0])
>>> bv.get_data_var_at(bv.entry_point)
<var 0x100001174: int32_t>

get_disassembly(addr, arch=None)

get_disassembly simple helper function for printing disassembly of a given address

Parameters:

• addr (int) – virtual address of instruction
• arch (Architecture) – optional Architecture, self.arch is used if this parameter is None

Returns:

a str representation of the instruction at virtual address addr or None

Return type:

str or None

Example:

>>> bv.get_disassembly(bv.entry_point)
'push    ebp'
>>>

get_entropy(addr, length, block_size=0)

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

Parameters:

• addr (int) – virtual address
• length (int) – total length in bytes
• block_size (int) – optional block size

Returns:

list of entropy values for each chunk

Return type:

list of entropy values or an empty list

get_function_at(addr, plat=None)

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

Parameters:

• addr (int) – starting virtual address of the desired function
• plat (Platform) – plat of the desired function

Returns:

returns a Function object or None for the function at the virtual address provided

Return type:

Function

Example:

>>> bv.get_function_at(bv.entry_point)
<func: x86_64@0x100001174>
>>>

get_functions_at(addr)

get_functions_at get a list of binaryninja.Function objects (one for each valid plat) at the given virtual address. Binary Ninja does not limit the number of platforms in a given file thus there may be multiple functions defined from different architectures at the same location. This API allows you to query all of valid platforms.

Parameters:addr (int) – virtual address of the desired Function object list. Returns:a list of binaryninja.Function objects defined at the provided virtual address Return type:list(Function)

get_functions_containing(addr)

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

Parameters:addr (int) – virtual address to query. Return type:list of Function objects or None

get_instruction_length(addr, arch=None)

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

Parameters:

• addr (int) – virtual address of the instruction query
• arch (Architecture) – (optional) the architecture of the instructions if different from the default

Returns:

Number of bytes in instruction

Return type:

int

Example:

>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> bv.get_instruction_length(0x100012f1)
2L
>>>

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.

Note

linear_disassembly doesn’t just return disassembly it will return a single line from the linear view, and thus will contain both data views, and disassembly.

Parameters:

settings (DisassemblySettings) – instance specifying the desired output formatting.

Returns:

An iterator containing formatted disassembly lines.

Return type:

LinearDisassemblyIterator

Example:

>>> settings = DisassemblySettings()
>>> lines = bv.get_linear_disassembly(settings)
>>> for line in lines:
...  print(line)
...  break
...
cf fa ed fe 07 00 00 01  ........

get_linear_disassembly_position_at(addr, settings)

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

Parameters:

• addr (int) – virtual address of linear disassembly position
• settings (DisassemblySettings) – an instantiated DisassemblySettings object

Returns:

An instantiated LinearDisassemblyPosition object for the provided virtual address

Return type:

LinearDisassemblyPosition

Example:

>>> settings = DisassemblySettings()
>>> pos = bv.get_linear_disassembly_position_at(0x1000149f, settings)
>>> lines = bv.get_previous_linear_disassembly_lines(pos, settings)
>>> lines
[<0x1000149a: pop     esi>, <0x1000149b: pop     ebp>,
<0x1000149c: retn    0xc>, <0x1000149f: >]

get_modification(addr, length=None)

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

Parameters:

• addr (int) – virtual address to get modification from
• length (int) – optional length of modification

Returns:

Either ModificationStatus of the byte at addr, or string of modified bytes at addr

Return type:

ModificationStatus or str

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

address addr

Parameters:

addr (int) – the virtual address to start looking from.

Returns:

the virtual address of the next BasicBlock

Return type:

int

Example:

>>> hex(bv.get_next_basic_block_start_after(bv.entry_point))
'0x100014a8L'
>>> hex(bv.get_next_basic_block_start_after(0x100014a8))
'0x100014adL'
>>>

get_next_data_after(addr)

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

Parameters:

addr (int) – the virtual address to start looking from.

Returns:

the virtual address of the next data byte which is data, not code

Return type:

int

Example:

>>> hex(bv.get_next_data_after(0x10000000))
'0x10000001L'

get_next_data_var_after(addr)

get_next_data_var_after retrieves the next virtual address of the next DataVariable

Parameters:

addr (int) – the virtual address to start looking from.

Returns:

the virtual address of the next DataVariable

Return type:

int

Example:

>>> hex(bv.get_next_data_var_after(0x10000000))
'0x1000003cL'
>>> bv.get_data_var_at(0x1000003c)
<var 0x1000003c: int32_t>
>>>

get_next_disassembly(arch=None)

get_next_disassembly simple helper function for printing disassembly of the next instruction. The internal state of the instruction to be printed is stored in the next_address attribute

Parameters:

arch (Architecture) – optional Architecture, self.arch is used if this parameter is None

Returns:

a str representation of the instruction at virtual address self.next_address

Return type:

str or None

Example:

>>> bv.get_next_disassembly()
'push    ebp'
>>> bv.get_next_disassembly()
'mov     ebp, esp'
>>> #Now reset the starting point back to the entry point
>>> bv.next_address = bv.entry_point
>>> bv.get_next_disassembly()
'push    ebp'
>>>

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

Parameters:

addr (int) – the virtual address to start looking from.

Returns:

the virtual address of the next Function

Return type:

int

Example:

>>> bv.get_next_function_start_after(bv.entry_point)
268441061L
>>> hex(bv.get_next_function_start_after(bv.entry_point))
'0x100015e5L'
>>> hex(bv.get_next_function_start_after(0x100015e5))
'0x10001629L'
>>> hex(bv.get_next_function_start_after(0x10001629))
'0x1000165eL'
>>>

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. This function can be called repeatedly to get more lines of linear disassembly.

Parameters:

• pos (LinearDisassemblyPosition) – Position to start retrieving linear disassembly lines from
• settings (DisassemblySettings) – DisassemblySettings display settings for the linear disassembly

Returns:

a list of LinearDisassemblyLine objects for the next lines.

Example:

>>> settings = DisassemblySettings()
>>> pos = bv.get_linear_disassembly_position_at(0x10001483, settings)
>>> bv.get_next_linear_disassembly_lines(pos, settings)
[<0x10001483: xor     eax, eax  {0x0}>, <0x10001485: inc     eax  {0x1}>, ... , <0x10001488: >]
>>> bv.get_next_linear_disassembly_lines(pos, settings)
[<0x10001488: push    dword [ebp+0x10 {arg_c}]>, ... , <0x1000149a: >]
>>>

get_previous_basic_block_end_before(addr)

get_previous_basic_block_end_before

Parameters:

addr (int) – the virtual address to start looking from.

Returns:

the virtual address of the previous BasicBlock end

Return type:

int

Example:

>>> hex(bv.entry_point)
'0x1000149fL'
>>> hex(bv.get_next_basic_block_start_after(bv.entry_point))
'0x100014a8L'
>>> hex(bv.get_previous_basic_block_end_before(0x100014a8))
'0x100014a8L'

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

Parameters:

addr (int) – the virtual address to start looking from.

Returns:

the virtual address of the previous BasicBlock

Return type:

int

Example:

>>> hex(bv.entry_point)
'0x1000149fL'
>>> hex(bv.get_next_basic_block_start_after(bv.entry_point))
'0x100014a8L'
>>> hex(bv.get_previous_basic_block_start_before(0x100014a8))
'0x1000149fL'
>>>

get_previous_data_before(addr)

get_previous_data_before

Parameters:

addr (int) – the virtual address to start looking from.

Returns:

the virtual address of the previous data (non-code) byte

Return type:

int

Example:

>>> hex(bv.get_previous_data_before(0x1000001))
'0x1000000L'
>>>

get_previous_data_var_before(addr)

get_previous_data_var_before

Parameters:

addr (int) – the virtual address to start looking from.

Returns:

the virtual address of the previous DataVariable

Return type:

int

Example:

>>> hex(bv.get_previous_data_var_before(0x1000003c))
'0x10000000L'
>>> bv.get_data_var_at(0x10000000)
<var 0x10000000: int16_t>
>>>

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

Parameters:

addr (int) – the virtual address to start looking from.

Returns:

the virtual address of the previous Function

Return type:

int

Example:

>>> hex(bv.entry_point)
'0x1000149fL'
>>> hex(bv.get_next_function_start_after(bv.entry_point))
'0x100015e5L'
>>> hex(bv.get_previous_function_start_before(0x100015e5))
'0x1000149fL'
>>>

get_previous_linear_disassembly_lines(pos, settings)

get_previous_linear_disassembly_lines retrieves a list of LinearDisassemblyLine objects for the previous disassembly lines, and updates the LinearDisassemblyPosition passed in. This function can be called repeatedly to get more lines of linear disassembly.

Parameters:

• pos (LinearDisassemblyPosition) – Position to start retrieving linear disassembly lines from
• settings (DisassemblySettings) – DisassemblySettings display settings for the linear disassembly

Returns:

a list of LinearDisassemblyLine objects for the previous lines.

Example:

>>> settings = DisassemblySettings()
>>> pos = bv.get_linear_disassembly_position_at(0x1000149a, settings)
>>> bv.get_previous_linear_disassembly_lines(pos, settings)
[<0x10001488: push    dword [ebp+0x10 {arg_c}]>, ... , <0x1000149a: >]
>>> bv.get_previous_linear_disassembly_lines(pos, settings)
[<0x10001483: xor     eax, eax  {0x0}>, ... , <0x10001488: >]

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_strings(start=None, length=None)

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

Parameters:

• start (int) – optional virtual address to start the string list from, defaults to start of the binary
• length (int) – optional length range to return strings from, defaults to length of the binary

Returns:

a list of all strings or a list of strings defined between start and start+length

Return type:

list(str())

Example:

>>> bv.get_strings(0x1000004d, 1)
[<AsciiString: 0x1000004d, len 0x2c>]
>>>

get_symbol_at(addr, namespace=None)

get_symbol_at returns the Symbol at the provided virtual address.

Parameters:

• addr (int) – virtual address to query for symbol
• namespace (NameSpace) – the namespace of the symbols to retrieve

Returns:

Symbol for the given virtual address

Return type:

Symbol

Example:

>>> bv.get_symbol_at(bv.entry_point)
<FunctionSymbol: "_start" @ 0x100001174>
>>>

get_symbol_by_raw_name(name, namespace=None)

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

Parameters:

• name (str) – raw (mangled) name of Symbol to be retrieved
• namespace (NameSpace) – the namespace to search for the given symbol

Returns:

Symbol object corresponding to the provided raw name

Return type:

Symbol

Example:

>>> bv.get_symbol_by_raw_name('?testf@Foobar@@SA?AW4foo@1@W421@@Z')
<FunctionSymbol: "public: static enum Foobar::foo __cdecl Foobar::testf(enum Foobar::foo)" @ 0x10001100>
>>>

get_symbols(start=None, length=None, namespace=None)

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

Parameters:

• start (int) – optional start virtual address
• length (int) – optional length

Returns:

list of all Symbol objects, or those Symbol objects in the range of start-start+length

Return type:

list(Symbol)

Example:

>>> bv.get_symbols(0x1000200c, 1)
[<ImportAddressSymbol: "KERNEL32!IsProcessorFeaturePresent@IAT" @ 0x1000200c>]
>>>

get_symbols_by_name(name, namespace=None)

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

Parameters:

• name (str) – name of Symbol object to be retrieved
• namespace (NameSpace) – the namespace of the symbol

Returns:

Symbol object corresponding to the provided name

Return type:

Symbol

Example:

>>> bv.get_symbols_by_name('?testf@Foobar@@SA?AW4foo@1@W421@@Z')
[<FunctionSymbol: "public: static enum Foobar::foo __cdecl Foobar::testf(enum Foobar::foo)" @ 0x10001100>]
>>>

get_symbols_of_type(sym_type, start=None, length=None, namespace=None)

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

provided range.

Parameters:

• sym_type (SymbolType) – A Symbol type: Symbol.
• start (int) – optional start virtual address
• length (int) – optional length

Returns:

list of all Symbol objects of type sym_type, or those Symbol objects in the range of start-start+length

Return type:

list(Symbol)

Example:

>>> bv.get_symbols_of_type(SymbolType.ImportAddressSymbol, 0x10002028, 1)
[<ImportAddressSymbol: "KERNEL32!GetCurrentThreadId@IAT" @ 0x10002028>]
>>>

get_type_by_id(id)

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

Parameters:

id (str) – Unique identifier to lookup

Returns:

A Type or None if the type does not exist

Return type:

Type or None

Example:

>>> type, name = bv.parse_type_string("int foo")
>>> type_id = Type.generate_auto_type_id("source", name)
>>> bv.define_type(type_id, name, type)
>>> bv.get_type_by_id(type_id)
<type: int32_t>
>>>

get_type_by_name(name)

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

Parameters:

name (QualifiedName) – Type name to lookup

Returns:

A Type or None if the type does not exist

Return type:

Type or None

Example:

>>> type, name = bv.parse_type_string("int foo")
>>> bv.define_user_type(name, type)
>>> bv.get_type_by_name(name)
<type: int32_t>
>>>

get_type_id(name)

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

Parameters:

name (QualifiedName) – Type name to lookup

Returns:

The unique identifier of the type

Return type:

str

Example:

>>> type, name = bv.parse_type_string("int foo")
>>> type_id = Type.generate_auto_type_id("source", name)
>>> registered_name = bv.define_type(type_id, name, type)
>>> bv.get_type_id(registered_name) == type_id
True
>>>

get_type_name_by_id(id)

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

Parameters:

id (str) – Unique identifier to lookup

Returns:

A QualifiedName or None if the type does not exist

Return type:

QualifiedName or None

Example:

>>> type, name = bv.parse_type_string("int foo")
>>> type_id = Type.generate_auto_type_id("source", name)
>>> bv.define_type(type_id, name, type)
'foo'
>>> bv.get_type_name_by_id(type_id)
'foo'
>>>

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.

Parameters:name (str) – Name of the view to be retrieved Returns:BinaryView object associated with the provided name or None on failure Return type:BinaryView or None

init()

insert(addr, data)

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

Parameters:

• addr (int) – virtual address to write to.
• data (str) – data to be inserted at addr.

Returns:

number of bytes inserted to virtual address addr

Return type:

int

Example:

>>> bv.insert(0,"BBBB")
4L
>>> bv.read(0,8)
'BBBBAAAA'

classmethod internal_namespace()

Internal namespace for the current BinaryView

invert_branch(addr, arch=None)

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

Note

This API performs a binary patch, analysis may need to be updated afterward. Additionally the binary

file must be saved in order to preserve the changes made.

Parameters:

• addr (int) – virtual address of the instruction to be modified
• arch (Architecture) – (optional) the architecture of the instructions if different from the default

Returns:

True on success, False on failure.

Return type:

bool

Example:

>>> bv.get_disassembly(0x1000130e)
'je      0x10001317'
>>> bv.invert_branch(0x1000130e)
True
>>>
>>> bv.get_disassembly(0x1000130e)
'jne     0x10001317'
>>>

is_always_branch_patch_available(addr, arch=None)

is_always_branch_patch_available queries the architecture plugin to determine if the instruction at addr can be made to always branch. The actual logic of which is implemented in the perform_is_always_branch_patch_available in the corresponding architecture.

Parameters:

• addr (int) – the virtual address of the instruction to be patched
• arch (Architecture) – (optional) the architecture for the current view

Returns:

True if the instruction can be patched, False otherwise

Return type:

bool

Example:

>>> bv.get_disassembly(0x100012ed)
'test    eax, eax'
>>> bv.is_always_branch_patch_available(0x100012ed)
False
>>> bv.get_disassembly(0x100012ef)
'jg      0x100012f5'
>>> bv.is_always_branch_patch_available(0x100012ef)
True
>>>

is_invert_branch_patch_available(addr, arch=None)

is_invert_branch_patch_available queries the architecture plugin to determine if the instruction at addr is a branch that can be inverted. The actual logic of which is implemented in the perform_is_invert_branch_patch_available in the corresponding architecture.

Parameters:

• addr (int) – the virtual address of the instruction to be patched
• arch (Architecture) – (optional) the architecture of the instructions if different from the default

Returns:

True if the instruction can be patched, False otherwise

Return type:

bool

Example:

>>> bv.get_disassembly(0x100012ed)
'test    eax, eax'
>>> bv.is_invert_branch_patch_available(0x100012ed)
False
>>> bv.get_disassembly(0x100012ef)
'jg      0x100012f5'
>>> bv.is_invert_branch_patch_available(0x100012ef)
True
>>>

is_never_branch_patch_available(addr, arch=None)

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. The actual logic of which is implemented in the perform_is_never_branch_patch_available in the corresponding architecture.

Parameters:

• addr (int) – the virtual address of the instruction to be patched
• arch (Architecture) – (optional) the architecture of the instructions if different from the default

Returns:

True if the instruction can be patched, False otherwise

Return type:

bool

Example:

>>> bv.get_disassembly(0x100012ed)
'test    eax, eax'
>>> bv.is_never_branch_patch_available(0x100012ed)
False
>>> bv.get_disassembly(0x100012ef)
'jg      0x100012f5'
>>> bv.is_never_branch_patch_available(0x100012ef)
True
>>>

is_offset_code_semantics(addr)

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

Parameters:addr (int) – a virtual address to be checked Returns:true if the virtual address is valid for writing, false if the virtual address is invalid or error Return type:bool

is_offset_executable(addr)

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

Parameters:addr (int) – a virtual address to be checked Returns:true if the virtual address is valid for executing, false if the virtual address is invalid or error Return type:bool

is_offset_extern_semantics(addr)

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

Parameters:addr (int) – a virtual address to be checked Returns:true if the virtual address is valid for writing, false if the virtual address is invalid or error Return type:bool

is_offset_readable(addr)

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

Parameters:addr (int) – a virtual address to be checked Returns:true if the virtual address is valid for reading, false if the virtual address is invalid or error Return type:bool

is_offset_writable(addr)

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

Parameters:addr (int) – a virtual address to be checked Returns:true if the virtual address is valid for writing, false if the virtual address is invalid or error Return type:bool

is_offset_writable_semantics(addr)

is_offset_writable_semantics checks if an virtual address addr is semantically writable. Some sections may have writable permissions for linking purposes but can be treated as read-only for the purposes of analysis.

Parameters:addr (int) – a virtual address to be checked Returns:true if the virtual address is valid for writing, false if the virtual address is invalid or error Return type:bool

is_skip_and_return_value_patch_available(addr, arch=None)

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. The actual logic of which is implemented in the perform_is_skip_and_return_value_patch_available in the corresponding architecture.

Parameters:

• addr (int) – the virtual address of the instruction to be patched
• arch (Architecture) – (optional) the architecture of the instructions if different from the default

Returns:

True if the instruction can be patched, False otherwise

Return type:

bool

Example:

>>> bv.get_disassembly(0x100012f6)
'mov     dword [0x10003020], eax'
>>> bv.is_skip_and_return_value_patch_available(0x100012f6)
False
>>> bv.get_disassembly(0x100012fb)
'call    0x10001629'
>>> bv.is_skip_and_return_value_patch_available(0x100012fb)
True
>>>

is_skip_and_return_zero_patch_available(addr, arch=None)

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. The actual logic of which is implemented in the perform_is_skip_and_return_zero_patch_available in the corresponding architecture.

Parameters:

• addr (int) – the virtual address of the instruction to be patched
• arch (Architecture) – (optional) the architecture of the instructions if different from the default

Returns:

True if the instruction can be patched, False otherwise

Return type:

bool

Example:

>>> bv.get_disassembly(0x100012f6)
'mov     dword [0x10003020], eax'
>>> bv.is_skip_and_return_zero_patch_available(0x100012f6)
False
>>> bv.get_disassembly(0x100012fb)
'call    0x10001629'
>>> bv.is_skip_and_return_zero_patch_available(0x100012fb)
True
>>>

is_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 name is considered an auto type.

Parameters:

name (QualifiedName) – Name of type to query

Returns:

True if the type is not a user type. False if the type is a user type.

Example:

>>> bv.is_type_auto_defined("foo")
True
>>> bv.define_user_type("foo", bv.parse_type_string("struct {int x,y;}")[0])
>>> bv.is_type_auto_defined("foo")
False
>>>

is_valid_offset(addr)

is_valid_offset checks if an virtual address addr is valid .

Parameters:addr (int) – a virtual address to be checked Returns:true if the virtual address is valid, false if the virtual address is invalid or error Return type:bool

navigate(view, offset)

never_branch(addr, arch=None)

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

Note

This API performs a binary patch, analysis may need to be updated afterward. Additionally the binary file must be saved in order to preserve the changes made.

Parameters:

• addr (int) – virtual address of the instruction to be modified
• arch (Architecture) – (optional) the architecture of the instructions if different from the default

Returns:

True on success, False on failure.

Return type:

bool

Example:

>>> bv.get_disassembly(0x1000130e)
'jne     0x10001317'
>>> bv.never_branch(0x1000130e)
True
>>> bv.get_disassembly(0x1000130e)
'nop'
>>>

classmethod new(data=None, file_metadata=None)

notify_data_inserted(offset, length)

notify_data_removed(offset, length)

notify_data_written(offset, length)

classmethod open(src, file_metadata=None)

parse_expression(expression, here=0)

Evaluates an string expression to an integer value.

The parser uses the following rules:

• symbols are defined by the lexer as [A-Za-z0-9_:<>][A-Za-z0-9_:$-<>]+ or anything enclosed in either single or

double quotes

• Numbers are defaulted to hexadecimal thus _printf + 10 is equivalent to printf + 0x10 If decimal numbers required use the decimal prefix.
• Since numbers and symbols can be ambiguous its recommended that you prefix your numbers with the following: - 0x - Hexadecimal - 0n - Decimal - 0 - Octal
• In the case of an ambiguous number/symbol (one with no prefix) for instance 12345 we will first attempt to look up the string as a symbol, if a symbol is found its address is used, otherwise we attempt to convert it to a hexadecimal number.
• The following operations are valid: +, -, *, /, %, (), &, |, ^, ~
• In addition to the above operators there are _il-style_ dereference operators - [<expression>] - read the _current address size_ at <expression> - [<expression>].b - read the byte at <expression> - [<expression>].w - read the word (2 bytes) at <expression> - [<expression>].d - read the dword (4 bytes) at <expression> - [<expression>].q - read the quadword (8 bytes) at <expression>
• The $here keyword can be used in calculations and is defined as the here parameter

Parameters:

• expression (string) – Arithmetic expression to be evaluated
• here (int) – (optional) Base address for relative expressions, defaults to zero

Return type:

int

parse_type_string(text)

parse_type_string converts C-style string into a Type.

Parameters:

text (str) – C-style string of type to create

Returns:

A tuple of a Type and type name

Return type:

tuple(Type, QualifiedName)

Example:

>>> bv.parse_type_string("int foo")
(<type: int32_t>, 'foo')
>>>

perform_get_address_size()

perform_get_default_endianness()

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

Note

This method may be implemented for custom BinaryViews that are not LittleEndian.

Warning

This method must not be called directly.

Returns:either Endianness.LittleEndian or Endianness.BigEndian Return type:Endianness

perform_get_entry_point()

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

Note

This method should be implemented for custom BinaryViews that are executable.

Warning

This method must not be called directly.

Returns:the virtual address of the entry point Return type:int

perform_get_length()

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

Note

This method may be overridden by custom BinaryViews. Use add_auto_segment to provide

data without overriding this method. .. warning:: This method must not be called directly.

Returns:returns the size of the virtual address range used by the BinaryView. Return type:int

perform_get_modification(addr)

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

Note

This method may be overridden by custom BinaryViews. Use add_auto_segment to provide

data without overriding this method. .. warning:: This method must not be called directly.

Parameters:addr (int) – a virtual address to be checked Returns:One of the following: Original = 0, Changed = 1, Inserted = 2 Return type:ModificationStatus

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.

Note

This method may be overridden by custom BinaryViews. Use add_auto_segment to provide

data without overriding this method. .. warning:: This method must not be called directly.

Parameters:addr (int) – a virtual address to start checking from. Returns:the next readable, writable, or executable virtual memory address Return type:int

perform_get_start()

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

Note

This method may be overridden by custom BinaryViews. Use add_auto_segment to provide

data without overriding this method. .. warning:: This method must not be called directly.

Returns:returns the first virtual address in the BinaryView. Return type:int

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.

Note

This method may be overridden by custom BinaryViews. If not overridden, inserting is disallowed

Warning

This method must not be called directly.

Parameters:

• addr (int) – a virtual address
• data (str) – the data to be inserted

Returns:

length of data inserted, should return 0 on error

Return type:

int

perform_is_executable()

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

Note

This method must be implemented for custom BinaryViews that are executable.

Warning

This method must not be called directly.

Returns:true if the current BinaryView is executable, false if it is not executable or on error Return type:bool

perform_is_offset_executable(addr)

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

Note

This method may be overridden by custom BinaryViews. Use add_auto_segment to provide

data without overriding this method. .. warning:: This method must not be called directly.

Parameters:addr (int) – a virtual address to be checked Returns:true if the virtual address is executable, false if the virtual address is not executable or error Return type:int

perform_is_offset_readable(offset)

perform_is_offset_readable implements a check if an virtual address is readable.

Note

This method may be overridden by custom BinaryViews. Use add_auto_segment to provide

data without overriding this method. .. warning:: This method must not be called directly.

Parameters:offset (int) – a virtual address to be checked Returns:true if the virtual address is readable, false if the virtual address is not readable or error Return type:bool

perform_is_offset_writable(addr)

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

Note

This method may be overridden by custom BinaryViews. Use add_auto_segment to provide

data without overriding this method. .. warning:: This method must not be called directly.

Parameters:addr (int) – a virtual address to be checked Returns:true if the virtual address is writable, false if the virtual address is not writable or error Return type:bool

perform_is_relocatable()

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

Note

This method may be implemented for custom BinaryViews that are relocatable.

Warning

This method must not be called directly.

Returns:True if the BinaryView is relocatable, False otherwise Return type:boolean

perform_is_valid_offset(addr)

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

Note

This method may be overridden by custom BinaryViews. Use add_auto_segment to provide

data without overriding this method. .. warning:: This method must not be called directly.

Parameters:addr (int) – a virtual address to be checked Returns:true if the virtual address is valid, false if the virtual address is invalid or error Return type:bool

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.

Note

This method may be overridden by custom BinaryViews. Use add_auto_segment to provide

data without overriding this method. .. warning:: This method must not be called directly.

Parameters:

• addr (int) – a virtual address to attempt to read from
• length (int) – the number of bytes to be read

Returns:

length bytes read from addr, should return empty string on error

Return type:

str

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.

Note

This method may be overridden by custom BinaryViews. If not overridden, removing data is disallowed

Warning

This method must not be called directly.

Parameters:

• addr (int) – a virtual address
• data (str) – the data to be removed

Returns:

length of data removed, should return 0 on error

Return type:

int

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.

Note

This method may be overridden by custom BinaryViews. Use add_auto_segment to provide

data without overriding this method. .. warning:: This method must not be called directly.

Parameters:

• addr (int) – a virtual address
• data (str) – the data to be written

Returns:

length of data written, should return 0 on error

Return type:

int

query_metadata(key)

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

Parameters:

key (string) – key to query

Return type:

metadata associated with the key

Example:

>>> bv.store_metadata("integer", 1337)
>>> bv.query_metadata("integer")
1337L
>>> bv.store_metadata("list", [1,2,3])
>>> bv.query_metadata("list")
[1L, 2L, 3L]
>>> bv.store_metadata("string", "my_data")
>>> bv.query_metadata("string")
'my_data'

read(addr, length)

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

Note: Python2 returns a str, but Python3 returns a bytes object. str(DataBufferObject) will still get you a str in either case.

Parameters:

• addr (int) – virtual address to read from.
• length (int) – number of bytes to read.

Returns:

at most length bytes from the virtual address addr, empty string on error or no data.

Return type:

python2 - str; python3 - bytes

Example:

>>> #Opening a x86_64 Mach-O binary
>>> bv = BinaryViewType['Raw'].open("/bin/ls")
>>> bv.read(0,4)
'\xcf\xfa\xed\xfe'

reanalyze()

reanalyze causes all functions to be reanalyzed. This function does not wait for the analysis to finish.

Return type:None

redo()

redo redo the last committed action in the undo database.

Return type:

None

Example:

>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> bv.begin_undo_actions()
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.commit_undo_actions()
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> bv.redo()
>>> bv.get_disassembly(0x100012f1)
'nop'
>>>

classmethod register()

register_notification(notify)

register_notification provides a mechanism for receiving callbacks for various analysis events. A full list of callbacks can be seen in BinaryDataNotification.

Parameters:notify (BinaryDataNotification) – notify is a subclassed instance of BinaryDataNotification. Return type:None

register_platform_types(platform)

register_platform_types ensures that the platform-specific types for a Platform are available for the current BinaryView. This is automatically performed when adding a new function or setting the default platform.

Parameters:

platform (Platform) – Platform containing types to be registered

Return type:

None

Example:

>>> platform = Platform["linux-x86"]
>>> bv.register_platform_types(platform)
>>>

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.

Parameters:

• addr (int) – virtual address to remove from.
• length (int) – number of bytes to remove.

Returns:

number of bytes removed from virtual address addr

Return type:

int

Example:

>>> bv.read(0,8)
'BBBBAAAA'
>>> bv.remove(0,4)
4L
>>> bv.read(0,4)
'AAAA'

remove_auto_section(name)

remove_auto_segment(start, length)

remove_function(func)

remove_function removes the function func from the list of functions

Parameters:

func (Function) – a Function object.

Return type:

None

Example:

>>> bv.functions
[<func: x86_64@0x1>]
>>> bv.remove_function(bv.functions[0])
>>> bv.functions
[]

remove_metadata(key)

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

Parameters:

key (string) – key associated with metadata to remove from the BinaryView

Return type:

None

Example:

>>> bv.store_metadata("integer", 1337)
>>> bv.remove_metadata("integer")

remove_user_function(func)

remove_user_function removes the user function func from the list of functions

Parameters:

func (Function) – a Function object.

Return type:

None

Example:

>>> bv.functions
[<func: x86_64@0x1>]
>>> bv.remove_user_function(bv.functions[0])
>>> bv.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

Parameters:

• old_name (QualifiedName) – Existing name of type to be renamed
• new_name (QualifiedName) – New name of type to be renamed

Return type:

None

Example:

>>> type, name = bv.parse_type_string("int foo")
>>> bv.define_user_type(name, type)
>>> bv.get_type_by_name("foo")
<type: int32_t>
>>> bv.rename_type("foo", "bar")
>>> bv.get_type_by_name("bar")
<type: int32_t>
>>>

save(dest)

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

Parameters:dest (str) – destination path and filename of file to be written Returns:boolean True on success, False on failure Return type:bool

save_auto_snapshot(progress_func=None)

save_auto_snapshot saves the current database to the already created file.

Note

create_database() should have been called prior to executing this method

Parameters:progress_func (callable()) – optional function to be called with the current progress and total count. Returns:True if it successfully saved the snapshot, False otherwise Return type:bool

classmethod set_default_session_data(name, value)

set_default_session_data saves a variable to the BinaryView. :param name: name of the variable to be saved :param value: value of the variable to be saved

Example:

>>> BinaryView.set_default_session_data("variable_name", "value")
>>> bv.session_data.variable_name
'value'

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. HTML reports support hyperlinking into the BinaryView. Hyperlinks can be specified as follows: binaryninja://?expr=_start Where expr= specifies an expression parsable by the parse_expression API.

Note: This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line

a simple text prompt is used.

Parameters:

• contents (str) – HTML contents to display
• plaintext (str) – Plain text version to display (used on the command-line)

Return type:

None

Example:

>>> bv.show_html_report("title", "<h1>Contents</h1>", "Plain text contents")
Plain text contents

show_markdown_report(title, contents, plaintext='')

show_markdown_report displays the markdown contents in UI applications and plaintext in command-line applications. Markdown reports support hyperlinking into the BinaryView. Hyperlinks can be specified as follows: binaryninja://?expr=_start Where expr= specifies an expression parsable by the parse_expression API.

Note: This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line

a simple text prompt is used.

Parameters:

• contents (str) – markdown contents to display
• plaintext (str) – Plain text version to display (used on the command-line)

Return type:

None

Example:

>>> bv.show_markdown_report("title", "##Contents", "Plain text contents")
Plain text contents

show_plain_text_report(title, contents)

skip_and_return_value(addr, value, arch=None)

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

Parameters:

• addr (int) – virtual address of the instruction to be modified
• value (int) – value to make the instruction return
• arch (Architecture) – (optional) the architecture of the instructions if different from the default

Returns:

True on success, False on failure.

Return type:

bool

Example:

>>> bv.get_disassembly(0x1000132a)
'call    0x1000134a'
>>> bv.skip_and_return_value(0x1000132a, 42)
True
>>> #The return value from x86 functions is stored in eax thus:
>>> bv.get_disassembly(0x1000132a)
'mov     eax, 0x2a'
>>>

store_metadata(key, md)

store_metadata stores an object for the given key in the current BinaryView. Objects stored using store_metadata can be retrieved when the database is reopened. Objects stored are not arbitrary python objects! The values stored must be able to be held in a Metadata object. See Metadata for more information. Python objects could obviously be serialized using pickle but this intentionally a task left to the user since there is the potential security issues.

Parameters:

• key (string) – key value to associate the Metadata object with
• md (Varies) – object to store.

Return type:

None

Example:

>>> bv.store_metadata("integer", 1337)
>>> bv.query_metadata("integer")
1337L
>>> bv.store_metadata("list", [1,2,3])
>>> bv.query_metadata("list")
[1L, 2L, 3L]
>>> bv.store_metadata("string", "my_data")
>>> bv.query_metadata("string")
'my_data'

undefine_auto_symbol(sym)

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

Parameters:sym (Symbol) – the symbol to undefine Return type:None

undefine_data_var(addr)

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

Parameters:

addr (int) – virtual address to define the data variable to be removed

Return type:

None

Example:

>>> bv.undefine_data_var(bv.entry_point)
>>>

undefine_type(type_id)

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

Parameters:

type_id (str) – Unique identifier of type to be undefined

Return type:

None

Example:

>>> type, name = bv.parse_type_string("int foo")
>>> type_id = Type.generate_auto_type_id("source", name)
>>> bv.define_type(type_id, name, type)
>>> bv.get_type_by_name(name)
<type: int32_t>
>>> bv.undefine_type(type_id)
>>> bv.get_type_by_name(name)
>>>

undefine_user_data_var(addr)

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

Parameters:

addr (int) – virtual address to define the data variable to be removed

Return type:

None

Example:

>>> bv.undefine_user_data_var(bv.entry_point)
>>>

undefine_user_symbol(sym)

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

Parameters:sym (Symbol) – the symbol to undefine Return type:None

undefine_user_type(name)

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

Parameters:

name (QualifiedName) – Name of user type to be undefined

Return type:

None

Example:

>>> type, name = bv.parse_type_string("int foo")
>>> bv.define_user_type(name, type)
>>> bv.get_type_by_name(name)
<type: int32_t>
>>> bv.undefine_user_type(name)
>>> bv.get_type_by_name(name)
>>>

undo()

undo undo the last committed action in the undo database.

Return type:

None

Example:

>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> bv.begin_undo_actions()
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.commit_undo_actions()
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> bv.redo()
>>> bv.get_disassembly(0x100012f1)
'nop'
>>>

unregister_notification(notify)

unregister_notification unregisters the BinaryDataNotification object passed to register_notification

Parameters:notify (BinaryDataNotification) – notify is a subclassed instance of BinaryDataNotification. Return type:None

update_analysis()

update_analysis asynchronously starts the analysis running and returns immediately. Analysis of BinaryViews does not occur automatically, the user must start analysis by calling either update_analysis() or update_analysis_and_wait(). An analysis update must be run after changes are made which could change analysis results such as adding functions.

Return type:None

update_analysis_and_wait()

update_analysis_and_wait blocking call to update the analysis, this call returns when the analysis is complete. Analysis of BinaryViews does not occur automatically, the user must start analysis by calling either update_analysis() or update_analysis_and_wait(). An analysis update must be run after changes are made which could change analysis results such as adding functions.

Return type:None

write(addr, data)

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

Parameters:

• addr (int) – virtual address to write to.
• data (str) – data to be written at addr.

Returns:

number of bytes written to virtual address addr

Return type:

int

Example:

>>> bv.read(0,4)
'BBBB'
>>> bv.write(0, "AAAA")
4L
>>> bv.read(0,4)
'AAAA'

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). All times are given in units of milliseconds (ms). Per function analysis_time is the aggregation of time spent performing incremental updates and is reset on a full function update. Per function update_count tracks the current number of incremental updates and is reset on a full function update. Per function submit_count tracks the current number of full updates that have completed. Note that the submit_count is currently not reset across analysis updates.

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 = None

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 = None

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 = 0

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 = None

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)

types

List of defined types (read-only)

view

view_type

View type (read-only)

class BinaryViewType(handle)

Bases: object

create(data)

get_arch(ident, endian)

get_platform(ident, arch)

classmethod get_view_of_file(filename, update_analysis=True, progress_func=None)

get_view_of_file returns the first available, non-Raw BinaryView available.

Parameters:

• filename (str) – Path to filename or bndb
• update_analysis (bool) – defaults to True. Pass False to not run update_analysis_and_wait.
• progress_func (callable()) – optional function to be called with the current progress and total count.

Returns:

returns a BinaryView object for the given filename.

Return type:

BinaryView or None

is_valid_for_data(data)

open(src, file_metadata=None)

register_arch(ident, endian, arch)

register_default_platform(arch, plat)

register_platform(ident, arch, plat)

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

long_name

BinaryView long name (read-only)

name

BinaryView name (read-only)

class BinaryWriter(view, endian=None)

Bases: object

class BinaryWriter is a convenience class for writing binary data.

BinaryWriter can be instantiated as follows and the rest of the document will start from this context

>>> from binaryninja import *
>>> bv = BinaryViewType['Mach-O'].open("/bin/ls")
>>> br = BinaryReader(bv)
>>> bw = BinaryWriter(bv)
>>>

Or using the optional endian parameter

>>> from binaryninja import *
>>> br = BinaryReader(bv, Endianness.BigEndian)
>>> bw = BinaryWriter(bv, Endianness.BigEndian)
>>>

seek(offset)

seek update internal offset to offset.

Parameters:

offset (int) – offset to set the internal offset to

Return type:

None

Example:

>>> hex(bw.offset)
'0x100000008L'
>>> bw.seek(0x100000000)
>>> hex(bw.offset)
'0x100000000L'
>>>

seek_relative(offset)

seek_relative updates the internal offset by offset.

Parameters:

offset (int) – offset to add to the internal offset

Return type:

None

Example:

>>> hex(bw.offset)
'0x100000008L'
>>> bw.seek_relative(-8)
>>> hex(bw.offset)
'0x100000000L'
>>>

write(value)

write writes len(value) bytes to the internal offset, without regard to endianness.

Parameters:

value (str) – bytes to be written at current offset

Returns:

boolean True on success, False on failure.

Return type:

bool

Example:

>>> bw.write("AAAA")
True
>>> br.read(4)
'AAAA'
>>>

write16(value)

write16 writes the lowest order two bytes from the integer value to the current offset, using internal endianness.

Parameters:value (int) – integer value to write. Returns:boolean True on success, False on failure. Return type:bool

write16be(value)

write16be writes the lowest order two bytes from the big endian integer value to the current offset.

Parameters:value (int) – integer value to write. Returns:boolean True on success, False on failure. Return type:bool

write16le(value)

write16le writes the lowest order two bytes from the little endian integer value to the current offset.

Parameters:value (int) – integer value to write. Returns:boolean True on success, False on failure. Return type:bool

write32(value)

write32 writes the lowest order four bytes from the integer value to the current offset, using internal endianness.

Parameters:value (int) – integer value to write. Returns:boolean True on success, False on failure. Return type:bool

write32be(value)

write32be writes the lowest order four bytes from the big endian integer value to the current offset.

Parameters:value (int) – integer value to write. Returns:boolean True on success, False on failure. Return type:bool

write32le(value)

write32le writes the lowest order four bytes from the little endian integer value to the current offset.

Parameters:value (int) – integer value to write. Returns:boolean True on success, False on failure. Return type:bool

write64(value)

write64 writes the lowest order eight bytes from the integer value to the current offset, using internal endianness.

Parameters:value (int) – integer value to write. Returns:boolean True on success, False on failure. Return type:bool

write64be(value)

write64be writes the lowest order eight bytes from the big endian integer value to the current offset.

Parameters:value (int) – integer value to write. Returns:boolean True on success, False on failure. Return type:bool

write64le(value)

write64le writes the lowest order eight bytes from the little endian integer value to the current offset.

Parameters:value (int) – integer value to write. Returns:boolean True on success, False on failure. Return type:bool

write8(value)

write8 lowest order byte from the integer value to the current offset.

Parameters:

value (str) – bytes to be written at current offset

Returns:

boolean

Return type:

int

Example:

>>> bw.write8(0x42)
True
>>> br.read(1)
'B'
>>>

endianness

The Endianness to written data. (read/write)

Getter:returns the endianness of the reader Setter:sets the endianness of the reader (BigEndian or LittleEndian) Type:Endianness

offset

The current write offset (read/write).

Getter:returns the current internal offset Setter:sets the internal offset Type:int

class DataVariable(addr, var_type, auto_discovered, view=None)

Bases: object

code_refs

code references to this data variable (read-only)

data_refs

data cross references to this data variable (read-only)

data_refs_from

data cross references from this data variable (read-only)

class Section(handle)

Bases: object

align

auto_defined

end

entry_size

info_data

info_section

linked_section

name

semantics

start

type

class Segment(handle)

Bases: object

relocation_ranges_at(addr)

List of relocation range tuples (read-only)

data_end

data_length

data_offset

end

executable

readable

relocation_count

relocation_ranges

List of relocation range tuples (read-only)

start

writable

class StringReference(bv, string_type, start, length)

Bases: object

value

class StructuredDataValue(type, address, value)

Bases: object

address

int

str

type

value

width

class StructuredDataView(bv, structure_name, address)

Bases: object

class StructuredDataView is a convenience class for reading structured binary data.

StructuredDataView can be instantiated as follows:

>>> from binaryninja import *
>>> bv = BinaryViewType['Mach-O'].open("/bin/ls")
>>> structure = "Elf64_Header"
>>> address = bv.start
>>> elf = StructuredDataView(bv, structure, address)
>>>

Once instantiated, members can be accessed:

>>> print("{:x}".format(elf.machine))
003e
>>>