binaryview module ¶

Example

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

apply_debug_info(value: DebugInfo) → None[source]¶

Sets the debug info and applies its contents to the current binary view

Parameters: value (DebugInfo) –
Return type: None

begin_undo_actions() → None[source]¶

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'
>>>

bulk_modify_symbols()[source]¶: bulk_modify_symbols returns a context manager that improves performance when adding or removing a large number of symbols. Symbols added within the Python with keyword will defer processing until the end of the block. Many symbol getter APIs will return stale results inside the with block, so this function should only be used when symbol queries are not needed at the same time as the modifications.

can_assemble(arch: Optional[Architecture] = None) → bool[source]¶

can_assemble queries the architecture plugin to determine if the architecture can assemble instructions.

Returns

True if the architecture can assemble, False otherwise

Return type

Example

>>> bv.can_assemble()
True
>>>

Parameters

arch (Optional[Architecture]) –

commit_undo_actions() → None[source]¶

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: int, arch: Optional[Architecture] = None) → bool[source]¶

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

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_disassembly(0x100012fb + 1)
'nop'
>>> bv.get_disassembly(0x100012fb + 2)
'nop'
>>> bv.get_disassembly(0x100012fb + 3)
'nop'
>>> bv.get_disassembly(0x100012fb + 4)
'nop'
>>> bv.get_disassembly(0x100012fb + 5)
'mov     byte [ebp-0x1c], al'

create_auto_data_tag(addr: int, type: TagType, data: str, unique: bool = False) → Tag[source]¶

create_auto_data_tag creates and adds a Tag object at a data address.

Parameters

addr (int) – address at which to add the tag
type (TagType) – TagType for the Tag that is created
data (str) – additional data for the Tag
unique (bool) – If a tag already exists at this location with this data, don’t add another

Returns

The created Tag object

Return type

create_auto_tag(type: TagType, data: str) → Tag[source]¶

Parameters

type (TagType) –
data (str) –

Return type

create_component(name: Optional[str] = None, parent: Optional[Union[Component, str]] = None) → Component[source]¶

Create a new component with an optional name and parent.

The parent argument can be either a Component or the Guid of a component that the created component will be: added as a child of

Parameters

name (Optional[str]) – Optional name to create the component with
parent (Optional[Union[Component, str]]) – Optional parent to which the component will be added

Returns

The created component

Return type

Component

create_database(filename: str, progress_func: Optional[Callable[[int, int], bool]] = None, settings: Optional[SaveSettings] = None) → bool[source]¶

create_database writes the current database (.bndb) 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 (callback) – optional function to be called with the current progress and total count.
settings (SaveSettings) – optional argument for special save options.

Returns

True on success, False on failure

Return type

Example

>>> settings = SaveSettings()
>>> bv.create_database(f"{bv.file.filename}.bndb", None, settings)
True

create_logger(logger_name: str) → Logger[source]¶

Parameters: logger_name (str) –
Return type: Logger

create_structure_from_offset_access(name: QualifiedName) → StructureType[source]¶

Parameters: name (QualifiedName) –
Return type: StructureType

create_structure_member_from_access(name: QualifiedName, offset: int) → Type[source]¶

Parameters

name (QualifiedName) –
offset (int) –

Return type

Type

create_tag(tag_type: TagType, data: str, user: bool = True) → Tag[source]¶

create_tag creates a new Tag object but does not add it anywhere. Use create_user_data_tag to create and add in one step.

Parameters

tag_type (TagType) – The TagType for this Tag
data (str) – additional data for the Tag
user (bool) – Whether or not a user tag

Returns

The created Tag

Return type

Example

>>> tt = bv.tag_types["Crashes"]
>>> tag = bv.create_tag(tt, "Null pointer dereference", True)
>>> bv.add_user_data_tag(here, tag)
>>>

create_tag_type(name: str, icon: str) → TagType[source]¶

create_tag_type creates a new TagType and adds it to the view

Parameters

name (str) – The name for the tag
icon (str) – The icon (recommended 1 emoji or 2 chars) for the tag

Returns

The created tag type

Return type

TagType

Example

>>> tt = bv.create_tag_type("Crabby Functions", "🦀")
>>> bv.create_user_data_tag(here, tt, "Get Crabbed")
>>>

create_user_data_tag(addr: int, type: TagType, data: str, unique: bool = False) → Tag[source]¶

create_user_data_tag creates and adds a Tag object at a data address. Since this adds a user tag, it will be added to the current undo buffer.

This API is appropriate for generic data tags, for functions, consider using create_user_function_tag or for specific addresses inside of functions, use create_user_address_tag.

Parameters

addr (int) – address at which to add the tag
type (TagType) – TagType for the Tag that is created
data (str) – additional data for the Tag
unique (bool) – if a tag already exists at this location with this data, don’t add another

Returns

The created Tag

Return type

Example

>>> tt = bv.tag_types["Crashes"]
>>> bv.create_user_data_tag(here, tt, "String data to associate with this tag")

create_user_function(addr: int, plat: Optional[Platform] = None) → Function[source]¶

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: [email protected]>]

create_user_tag(type: TagType, data: str) → Tag[source]¶

Parameters

type (TagType) –
data (str) –

Return type

define_auto_symbol(sym: CoreSymbol) → None[source]¶

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 (CoreSymbol) – the symbol to define
Return type: None

define_auto_symbol_and_var_or_function(sym: CoreSymbol, type: Type, plat: Optional[Platform] = None) → Optional[CoreSymbol][source]¶

define_auto_symbol_and_var_or_function Defines an “Auto” symbol, and a Variable/Function alongside it.

Warning

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

Parameters

sym (CoreSymbol) – Symbol to define
type (Type) – Type for the function/variable being defined (can be None)
plat (Optional[Platform]) – Platform (optional)

Return type

Optional[CoreSymbol]

define_data_var(addr: int, var_type: Union[str, Type, TypeBuilder], name: Optional[Union[str, CoreSymbol]] = None) → None[source]¶

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 (StringOrType) – type to be defined at the given virtual address
name (Optional[Union[str, CoreSymbol]]) – Optionally additionally define a symbol at this location
name –

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])
>>> bv.define_data_var(bv.entry_point + 4, "int", "foo")
>>> bv.get_symbol_at(bv.entry_point + 4)
<DataSymbol: "foo" @ 0x23950>
>>> bv.get_data_var_at(bv.entry_point + 4)
<var 0x23950: int32_t>

define_imported_function(import_addr_sym: CoreSymbol, func: Function, type: Optional[Type] = None) → None[source]¶

define_imported_function defines an imported Function func with a ImportedFunctionSymbol type.

Parameters

import_addr_sym (CoreSymbol) – A Symbol object with type ImportedFunctionSymbol
func (Function) – A Function object to define as an imported function
type (Optional[Type]) – Optional type for the function

Return type

None

define_type(type_id: str, default_name: Optional[_types.QualifiedNameType], type_obj: Union[str, _types.Type, _types.TypeBuilder]) → _types.QualifiedName[source]¶

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 (StringOrType) – 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>
>>> registered_name = bv.define_type("mytypeid", None, "int bar")
>>> bv.get_type_by_name(registered_name)
<type: int32_t>

define_user_data_var(addr: int, var_type: Union[str, Type, TypeBuilder], name: Optional[Union[str, CoreSymbol]] = None) → Optional[DataVariable][source]¶

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
name (Optional[Union[str, CoreSymbol]]) – Optionally, additionally define a symbol at this same address
name –

Return type

Optional[DataVariable]

Example

>>> t = bv.parse_type_string("int foo")
>>> t
(<type: int32_t>, 'foo')
>>> bv.define_user_data_var(bv.entry_point, t[0])
<var 0x2394c: int32_t>
>>> bv.define_user_data_var(bv.entry_point + 4, "int", "foo")
<var 0x23950: int32_t>
>>> bv.get_symbol_at(bv.entry_point + 4)
<DataSymbol: "foo" @ 0x23950>
>>> bv.get_data_var_at(bv.entry_point + 4)
<var 0x23950: int32_t>

define_user_symbol(sym: CoreSymbol) → None[source]¶

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: Optional[_types.QualifiedNameType], type_obj: Union[str, _types.Type, _types.TypeBuilder]) → None[source]¶

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 (StringOrType) – 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>
>>> bv.define_user_type(None, "int bas")
>>> bv.get_type_by_name("bas")
<type: int32_t>

disassembly_text(addr: int, arch: Optional[Architecture] = None) → Generator[Tuple[str, int], None, None][source]¶

disassembly_text helper function for getting 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

>>> next(bv.disassembly_text(bv.entry_point))
'push    ebp', 1
>>>

disassembly_tokens(addr: int, arch: Optional[Architecture] = None) → Generator[Tuple[List[InstructionTextToken], int], None, None][source]¶

Parameters

addr (int) –
arch (Optional[Architecture]) –

Return type

Generator[Tuple[List[InstructionTextToken], int], None, None]

eval(expression: str, here: int = 0) → int[source]¶

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

Parameters

expression (str) –
here (int) –

Return type

export_object_to_library(lib: TypeLibrary, name: Optional[str], type_obj: Union[str, Type, TypeBuilder]) → None[source]¶

export_object_to_library recursively exports type_obj into lib as an object with name name

As other referenced types are encountered, they are either copied into the destination type library or else the type library that provided the referenced type is added as a dependency for the destination library.

Parameters

lib (TypeLibrary) –
name (QualifiedName) –
type_obj (StringOrType) –

Return type

None

export_type_to_library(lib: TypeLibrary, name: Optional[str], type_obj: Union[str, Type, TypeBuilder]) → None[source]¶

export_type_to_library recursively exports type_obj into lib as a type with name name

As other referenced types are encountered, they are either copied into the destination type library or else the type library that provided the referenced type is added as a dependency for the destination library.

Parameters

lib (TypeLibrary) –
name (QualifiedName) –
type_obj (StringOrType) –

Return type

None

static external_namespace() → NameSpace[source]¶

External namespace for the current BinaryView

Return type: NameSpace

find_all_constant(start: int, end: int, constant: int, settings: Optional[DisassemblySettings] = None, graph_type: FunctionGraphType = FunctionGraphType.NormalFunctionGraph, progress_func: Optional[Callable[[int, int], bool]] = None, match_callback: Optional[Callable[[int, LinearDisassemblyLine], bool]] = None) → QueueGenerator[source]¶

find_all_constant searches for the integer constant constant starting at the virtual address start until the virtual address end. Once a match is found, the match_callback is called.

Parameters

start (int) – virtual address to start searching from.
end (int) – virtual address to end the search.
constant (int) – constant to search for
settings (DisassemblySettings) – DisassemblySettings object used to render the text to be searched
graph_type (FunctionGraphType) – the IL to search within
progress_func (callback) – optional function to be called with the current progress and total count. This function should return a boolean value that decides whether the search should continue or stop
match_callback (callback) – function that gets called when a match is found. The callback takes two parameters, i.e., the address of the match, and the LinearDisassemblyLine that contains the matching line. If this parameter is None, this function becomes a generator and yields the matching address and the matching LinearDisassemblyLine. This function can return a boolean value that decides whether the search should continue or stop

Rtype bool

whether any (one or more) match is found for the search

find_all_data(start: int, end: int, data: bytes, flags: FindFlag = FindFlag.FindCaseSensitive, progress_func: Optional[Callable[[int, int], bool]] = None, match_callback: Optional[Callable[[int, DataBuffer], bool]] = None) → QueueGenerator[source]¶

find_all_data searches for the bytes data starting at the virtual address start until the virtual address end. Once a match is found, the match_callback is called.

Parameters

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

FindFlag

Description

FindCaseSensitive

Case-sensitive search

FindCaseInsensitive

Case-insensitive search
progress_func (callback) – optional function to be called with the current progress and total count. This function should return a boolean value that decides whether the search should continue or stop
match_callback (callback) – function that gets called when a match is found. The callback takes two parameters, i.e., the address of the match, and the actual DataBuffer that satisfies the search. If this parameter is None, this function becomes a generator and yields a tuple of the matching address and the matched DataBuffer. This function can return a boolean value that decides whether the search should continue or stop.
data –

Rtype bool

whether any (one or more) match is found for the search

find_all_text(start: int, end: int, text: str, settings: Optional[DisassemblySettings] = None, flags=FindFlag.FindCaseSensitive, graph_type=FunctionGraphType.NormalFunctionGraph, progress_func=None, match_callback=None) → QueueGenerator[source]¶

find_all_text searches for string text occurring in the linear view output starting at the virtual address start until the virtual address end. Once a match is found, the match_callback is called.

Parameters

start (int) – virtual address to start searching from.
end (int) – virtual address to end the search.
text (str) – text to search for
settings (DisassemblySettings) – DisassemblySettings object used to render the text to be searched
flags (FindFlag) –
(optional) defaults to case-insensitive data search

FindFlag

Description

FindCaseSensitive

Case-sensitive search

FindCaseInsensitive

Case-insensitive search
graph_type (FunctionGraphType) – the IL to search within
progress_func (callback) – optional function to be called with the current progress and total count. This function should return a boolean value that decides whether the search should continue or stop
match_callback (callback) – function that gets called when a match is found. The callback takes three parameters, i.e., the address of the match, and the actual string that satisfies the search, and the LinearDisassemblyLine that contains the matching line. If this parameter is None, this function becomes a generator and yields a tuple of the matching address, the matched string, and the matching LinearDisassemblyLine. This function can return a boolean value that decides whether the search should continue or stop

Rtype bool

whether any (one or more) match is found for the search

find_next_constant(start: int, constant: int, settings: Optional[DisassemblySettings] = None, graph_type: FunctionGraphType = FunctionGraphType.NormalFunctionGraph) → Optional[int][source]¶

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
settings (DisassemblySettings) – disassembly settings
graph_type (FunctionGraphType) – the IL to search within

Return type

find_next_data(start: int, data: bytes, flags: FindFlag = FindFlag.FindCaseSensitive) → Optional[int][source]¶

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 (bytes) – data to search for
flags (FindFlag) –
(optional) defaults to case-insensitive data search

FindFlag

Description

FindCaseSensitive

Case-sensitive search

FindCaseInsensitive

Case-insensitive search
data –

Return type

find_next_text(start: int, text: str, settings: Optional[DisassemblySettings] = None, flags: FindFlag = FindFlag.FindCaseSensitive, graph_type: FunctionGraphType = FunctionGraphType.NormalFunctionGraph) → Optional[int][source]¶

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
settings (DisassemblySettings) – disassembly settings
flags (FindFlag) –
(optional) defaults to case-insensitive data search

FindFlag

Description

FindCaseSensitive

Case-sensitive search

FindCaseInsensitive

Case-insensitive search
graph_type (FunctionGraphType) – the IL to search within

Return type

get_address_for_data_offset(offset: int) → Optional[int][source]¶

get_address_for_data_offset returns the virtual address that maps to the specific file offset.

Parameters: offset (int) – file offset
Returns: the virtual address of the first segment that contains that file location
Return type: Int

get_address_input(prompt: str, title: str, current_address: Optional[int] = None) → Optional[int][source]¶

get_address_input Gets a virtual address via a prompt displayed to the user

Parameters

prompt (str) – Prompt for the dialog
title (str) – Display title, if displayed via the UI
current_address (Optional[int]) – Optional current address, for relative inputs

Returns

The value entered by the user, if one was entered

Return type

list(ReferenceSource)

get_all_fields_referenced(name: _types.QualifiedNameType) → List[int][source]¶

get_all_fields_referenced returns a list of offsets in the QualifiedName specified by name, which are referenced by code.

Parameters

name (QualifiedName) – name of type to query for references

Returns

List of offsets

Return type

list(integer)

Example

>>> bv.get_all_fields_referenced('A')
[0, 8, 16, 24, 32, 40]
>>>

get_all_sizes_referenced(name: _types.QualifiedNameType) → Mapping[int, List[int]][source]¶

get_all_sizes_referenced returns a map from field offset to a list of sizes of the accesses to it.

Parameters

name (QualifiedName) – name of type to query for references

Returns

A map from field offset to the size of the code accesses to it

Return type

map

Example

>>> bv.get_all_sizes_referenced('B')
{0: [1, 8], 8: [8], 16: [1, 8]}
>>>

get_all_types_referenced(name: _types.QualifiedNameType) → Mapping[int, List[_types.Type]][source]¶

get_all_types_referenced returns a map from field offset to a list of incoming types written to the specified type.

Parameters

name (QualifiedName) – name of type to query for references

Returns

A map from field offset to a list of incoming types written to it

Return type

map

Example

>>> bv.get_all_types_referenced('B')
{0: [<type: char, 0% confidence>], 8: [<type: int64_t, 0% confidence>],
16: [<type: char, 0% confidence>, <type: bool>]}
>>>

get_ascii_string_at(addr: int, min_length: int = 4, max_length: Optional[int] = None, require_cstring: bool = True) → Optional[StringReference][source]¶

get_ascii_string_at returns an ascii string found at addr.

Note

This returns an ascii string irrespective of whether the core analysis identified a string at that location. For an alternative API that uses existing identified strings, use get_string_at.

Parameters

addr (int) – virtual address to start the string
min_length (int) – minimum length to define a string
max_length (int) – max length string to return
require_cstring (bool) – only return 0x0-terminated strings

Returns

the string found at addr or None if a string does not exist

Return type

StringReference or None

Example

>>> s1 = bv.get_ascii_string_at(0x70d0)
>>> s1
<AsciiString: 0x70d0, len 0xb>
>>> s1.value
'AWAVAUATUSH'
>>> s2 = bv.get_ascii_string_at(0x70d1)
>>> s2
<AsciiString: 0x70d1, len 0xa>
>>> s2.value
'WAVAUATUSH'

get_auto_data_tags_at(addr: int) → List[Tag][source]¶

get_auto_data_tags_at gets a list of all auto-defined Tag objects for a data address.

Parameters: addr (int) – address to get tags at
Returns: A list of data Tag objects
Return type: list(Tag)

get_auto_data_tags_in_range(address_range: AddressRange) → List[Tuple[int, Tag]][source]¶

get_auto_data_tags_in_range gets a list of all auto-defined data Tag objects in a given range. Range is inclusive at the start, exclusive at the end.

Parameters: address_range (AddressRange) – address range from which to get tags
Returns: A list of (address, data tag) tuples
Return type: list((int, Tag))

get_auto_data_tags_of_type(addr: int, tag_type: TagType) → List[Tag][source]¶

get_auto_data_tags_of_type gets a list of all auto-defined Tag objects for a data address of a given type.

Parameters

addr (int) – address to get tags at
tag_type (TagType) – TagType object to match in searching

Returns

A list of data Tag objects

Return type

list(Tag)

get_basic_blocks_at(addr: int) → List[BasicBlock][source]¶

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: int) → List[BasicBlock][source]¶

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_callees(addr: int, func: Optional[Function] = None, arch: Optional[Architecture] = None) → List[int][source]¶

get_callees returns a list of virtual addresses called by the call site in the function func, of the architecture arch, and at the address addr. If no function is specified, call sites from all functions and containing the address will be considered. If no architecture is specified, the architecture of the function will be used.

Parameters

addr (int) – virtual address of the call site to query for callees
func (Architecture) – (optional) the function that the call site belongs to
func – (optional) the architecture of the call site
arch (Optional[Architecture]) –

Returns

list of integers

Return type

list(integer)

get_callers(addr: int) → Generator[ReferenceSource, None, None][source]¶

get_callers returns a list of ReferenceSource objects (xrefs or cross-references) that call the provided virtual address. In this case, tail calls, jumps, and ordinary calls are considered.

Parameters

addr (int) – virtual address of callee to query for callers

Returns

List of References that call the given virtual address

Return type

Example

>>> bv.get_callers(here)
[<ref: [email protected]>]
>>>

get_code_refs(addr: int, length: Optional[int] = None) → Generator[ReferenceSource, None, None][source]¶

get_code_refs returns a generator of ReferenceSource objects (xrefs or cross-references) that point to the provided virtual address. This function returns both autoanalysis (“auto”) and user-specified (“user”) xrefs. To add a user-specified reference, see add_user_code_ref.

The related get_data_refs is used to find data references to an address unlike this API which returns references that exist in code.

Note

Note that get_code_refs returns xrefs to code that references the address being queried. get_data_refs on the other hand returns references that exist in data (pointers in global variables for example). The related get_refs_from looks for references that are outgoing from the queried address to other locations.

Parameters

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

Returns

A generator of References for the given virtual address

Return type

Generator[ReferenceSource, None, None]

Example

>>> bv.get_code_refs(here)
[<ref: [email protected]>]
>>>

get_code_refs_for_type(name: str) → Generator[ReferenceSource, None, None][source]¶

get_code_refs_for_type returns a Generator[ReferenceSource] objects (xrefs or cross-references) that reference the provided QualifiedName.

Parameters

name (QualifiedName) – name of type to query for references

Returns

List of References for the given type

Return type

list(ReferenceSource)

Example

>>> bv.get_code_refs_for_type('A')
[<ref: [email protected]>]
>>>

get_code_refs_for_type_field(name: str, offset: int) → Generator[TypeFieldReference, None, None][source]¶

get_code_refs_for_type returns a Generator[TypeFieldReference] objects (xrefs or cross-references) that reference the provided type field.

Parameters

name (QualifiedName) – name of type to query for references
offset (int) – offset of the field, relative to the type

Returns

Generator of References for the given type

Return type

Generator[TypeFieldReference]

Example

>>> bv.get_code_refs_for_type_field('A', 0x8)
[<ref: [email protected]>]
>>>

get_code_refs_for_type_fields_from(addr: int, func: Optional[Function] = None, arch: Optional[Architecture] = None, length: Optional[int] = None) → List[TypeReferenceSource][source]¶

get_code_refs_for_type_fields_from returns a list of type fields referenced by code in the function func, of the architecture arch, and at the address addr. If no function is specified, references from all functions and containing the address will be returned. If no architecture is specified, the architecture of the function will be used.

Parameters

addr (int) – virtual address to query for references
length (int) – optional length of query
func (Optional[Function]) –
arch (Optional[Architecture]) –

Returns

list of references

Return type

get_code_refs_for_type_from(addr: int, func: Optional[Function] = None, arch: Optional[Architecture] = None, length: Optional[int] = None) → List[TypeReferenceSource][source]¶

get_code_refs_for_type_from returns a list of types referenced by code in the function func, of the architecture arch, and at the address addr. If no function is specified, references from all functions and containing the address will be returned. If no architecture is specified, the architecture of the function will be used.

Parameters

addr (int) – virtual address to query for references
length (int) – optional length of query
func (Optional[Function]) –
arch (Optional[Architecture]) –

Returns

list of references

Return type

get_code_refs_from(addr: int, func: Optional[Function] = None, arch: Optional[Architecture] = None, length: Optional[int] = None) → List[int][source]¶

get_code_refs_from returns a list of virtual addresses referenced by code in the function func, of the architecture arch, and at the address addr. If no function is specified, references from all functions and containing the address will be returned. If no architecture is specified, the architecture of the function will be used. This function returns both autoanalysis (“auto”) and user-specified (“user”) xrefs. To add a user-specified reference, see add_user_code_ref.

Parameters

addr (int) – virtual address to query for references
length (int) – optional length of query
arch (Architecture) – optional architecture of query
func (Optional[Function]) –

Returns

list of integers

Return type

list(integer)

get_comment_at(addr: int) → str[source]¶

get_comment_at returns the address-based comment attached to the given address in this BinaryView Note that address-based comments are different from function-level comments which are specific to each Function. For more information, see address_comments.

Parameters: addr (int) – virtual address within the current BinaryView to apply the comment to
Return type: str

get_component(guid: str) → Optional[Component][source]¶

Lookup a Component by its Guid

Parameters: guid (str) – Guid of the component to look up
Returns: The Component with that Guid
Return type: Optional[Component]

get_component_by_path(path: str) → Optional[Component][source]¶

Lookup a Component by its pathname

Note: This is a convenience method, and for performance-sensitive lookups, GetComponentByGuid is very highly recommended.
Parameters: path (str) –
Return type: Optional[Component]

Lookups are done based on the .display_name of the Component.

All lookups are absolute from the root component, and are case-sensitive. Pathnames are delimited with “/”

Parameters

path (str) – Pathname of the desired Component

Returns

The Component at that pathname

Example

>>> c = bv.create_component(name="MyComponent")
>>> c2 = bv.create_component(name="MySubComponent", parent=c)
>>> bv.get_component_by_path("/MyComponent/MySubComponent") == c2
True
>>> c3 = bv.create_component(name="MySubComponent", parent=c)
>>> c3
<Component "MySubComponent (1)" "(20712aff...")>
>>> bv.get_component_by_path("/MyComponent/MySubComponent (1)") == c3
True

Return type

Optional[Component]

get_constant_data(addr: int) → DataBuffer[source]¶

Parameters: addr (int) –
Return type: DataBuffer

get_data_offset_for_address(address: int) → Optional[int][source]¶

get_data_offset_for_address returns the file offset that maps to the given virtual address, if possible.

If address falls within a bss segment or an external segment, for example, no mapping is possible, and None will be returned.

Parameters: address (int) – virtual address
Returns: the file location that is mapped to the given virtual address, or None if no such mapping is possible
Return type: Int

get_data_refs(addr: int, length: Optional[int] = None) → Generator[int, None, None][source]¶

get_data_refs returns a list of virtual addresses of _data_ (not code) 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. This function returns both autoanalysis (“auto”) and user-specified (“user”) xrefs. To add a user-specified reference, see add_user_data_ref.

Warning

If you’re looking at this API, please double check that you don’t mean to use get_code_refs instead. get_code_refs returns references from code to the specified address while this API returns references from data (pointers in global variables for example).

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_for_type(name: str) → Generator[int, None, None][source]¶

get_data_refs_for_type returns a list of virtual addresses of data which references the type name. Note, the returned addresses are the actual start of the queried type. For example, suppose there is a DataVariable at 0x1000 that has type A, and type A contains type B at offset 0x10. Then get_data_refs_for_type(‘B’) will return 0x1010 for it.

Parameters

name (QualifiedName) – name of type to query for references

Returns

list of integers

Return type

list(integer)

Example

>>> bv.get_data_refs_for_type('A')
[4203812]
>>>

get_data_refs_for_type_field(name: _types.QualifiedNameType, offset: int) → List[int][source]¶

get_data_refs_for_type_field returns a list of virtual addresses of data which references the type name. Note, the returned addresses are the actual start of the queried type field. For example, suppose there is a DataVariable at 0x1000 that has type A, and type A contains type B at offset 0x10. Then get_data_refs_for_type_field(‘B’, 0x8) will return 0x1018 for it.

Parameters

name (QualifiedName) – name of type to query for references
offset (int) – offset of the field, relative to the type

Returns

list of integers

Return type

list(integer)

Example

>>> bv.get_data_refs_for_type_field('A', 0x8)
[4203812]
>>>

get_data_refs_from(addr: int, length: Optional[int] = None) → Generator[int, None, None][source]¶

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. This function returns both autoanalysis (“auto”) and user-specified (“user”) xrefs. To add a user-specified reference, see add_user_data_ref.

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_tags_at(addr: int) → List[Tag][source]¶

get_data_tags_at gets a list of all Tag objects for a data address.

Parameters: addr (int) – address to get tags at
Returns: A list of data Tag objects
Return type: list(Tag)

get_data_tags_in_range(address_range: AddressRange) → List[Tuple[int, Tag]][source]¶

get_data_tags_in_range gets a list of all data Tag objects in a given range. Range is inclusive at the start, exclusive at the end.

Parameters: address_range (AddressRange) – address range from which to get tags
Returns: A list of (address, data tag) tuples
Return type: list((int, Tag))

get_data_tags_of_type(addr: int, tag_type: TagType) → List[Tag][source]¶

get_data_tags_of_type gets a list of all Tag objects for a data address of a given type.

Parameters

addr (int) – address to get tags at
tag_type (TagType) – TagType object to match in searching

Returns

A list of data Tag objects

Return type

list(Tag)

get_data_var_at(addr: int) → Optional[DataVariable][source]¶

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: int, arch: Optional[Architecture] = None) → Optional[str][source]¶

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'
>>>

Note

This API is very simplistic and only returns text. See disassembly_text and instructions for more capable APIs.

get_entropy(addr: int, length: int, block_size: int = 0) → List[float][source]¶

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(float)

get_expression_parser_magic_value(name: str) → Optional[int][source]¶

Parameters: name (str) –
Return type: Optional[int]

get_function_at(addr: int, plat: Optional[Platform] = None) → Optional[Function][source]¶

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) – platform 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: [email protected]>
>>>

get_functions_at(addr: int) → List[Function][source]¶

get_functions_at get a list of Function objects (one for each valid platform) that start 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.

You may also be interested in get_functions_containing which is useful for requesting all function that contain a given address

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

get_functions_by_name(name: str, plat: Optional[Platform] = None, ordered_filter: Optional[List[SymbolType]] = None) → List[Function][source]¶

get_functions_by_name returns a list of Function objects function with a Symbol of name.

Parameters

name (str) – name of the functions
plat (Platform) – (optional) platform
ordered_filter (list(SymbolType)) – (optional) an ordered filter based on SymbolType

Returns

returns a list of Function objects or an empty list

Return type

list(Function)

Example

>>> bv.get_functions_by_name("main")
[<func: [email protected]>]
>>>

get_functions_containing(addr: int, plat: Optional[Platform] = None) → List[Function][source]¶

get_functions_containing returns a list of Function objects which contain the given address.

Parameters

addr (int) – virtual address to query.
plat (Optional[Platform]) –

Return type

list of Function objects

get_instruction_length(addr: int, arch: Optional[Architecture] = None) → int[source]¶

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

Example

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

get_linear_disassembly(settings: Optional[DisassemblySettings] = None) → Iterator[LinearDisassemblyLine][source]¶

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. Defaults to None which will use default settings.

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: int, settings: Optional[DisassemblySettings] = None) → LinearViewCursor[source]¶

get_linear_disassembly_position_at instantiates a LinearViewCursor 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, defaults to None which will use default settings

Returns

An instantiated LinearViewCursor object for the provided virtual address

Return type

LinearViewCursor

Example

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

get_load_settings(type_name: str) → Optional[Settings][source]¶

get_load_settings retrieve a Settings object which defines the load settings for the given BinaryViewType type_name

Parameters: type_name (str) – the BinaryViewType name
Returns: the load settings
Return type: Settings, or None

get_load_settings_type_names() → List[str][source]¶

get_load_settings_type_names retrieve a list BinaryViewType names for which load settings exist in this BinaryView context

Returns: list of BinaryViewType names
Return type: list(str)

get_modification(addr: int, length: Optional[int] = None) → List[ModificationStatus][source]¶

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

List of ModificationStatus values for each byte in range

Return type

List[ModificationStatus]

get_next_basic_block_start_after(addr: int) → int[source]¶

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

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: int) → int[source]¶

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

Example

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

get_next_data_var_after(addr: int) → Optional[DataVariable][source]¶

get_next_data_var_after retrieves the next DataVariable, or None.

Parameters

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

Returns

the next DataVariable

Return type

DataVariable

Example

>>> bv.get_next_data_var_after(0x10000000)
<var 0x1000003c: int32_t>
>>>

get_next_data_var_start_after(addr: int) → int[source]¶

get_next_data_var_start_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

Example

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

get_next_function_start_after(addr: int) → int[source]¶

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

List[LinearDisassemblyLine]

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: LinearViewCursor) → List[LinearDisassemblyLine][source]¶

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

Parameters

pos (LinearViewCursor) – Position to start retrieving linear disassembly lines from

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)
[<0x10001483: xor     eax, eax  {0x0}>, <0x10001485: inc     eax  {0x1}>, ... , <0x10001488: >]
>>> bv.get_next_linear_disassembly_lines(pos)
[<0x10001488: push    dword [ebp+0x10 {arg_c}]>, ... , <0x1000149a: >]
>>>

Return type

get_next_valid_offset(addr: int) → int[source]¶

get_next_valid_offset returns the next valid offset after addr.

Parameters: addr (int) – a virtual address
Returns: The minimum of the next valid offset in the BinaryView and the end address of the BinaryView
Return type: int

get_previous_basic_block_end_before(addr: int) → int[source]¶

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

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: int) → int[source]¶

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

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: int) → int[source]¶

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

Example

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

get_previous_data_var_before(addr: int) → Optional[DataVariable][source]¶

get_previous_data_var_before retrieves the previous DataVariable, or None.

Parameters

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

Returns

the previous DataVariable

Return type

DataVariable

Example

>>> bv.get_previous_data_var_before(0x1000003c)
<var 0x10000000: int16_t>
>>>

get_previous_data_var_start_before(addr: int) → int[source]¶

get_previous_data_var_start_before

Parameters

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

Returns

the virtual address of the previous DataVariable

Return type

Example

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

get_previous_function_start_before(addr: int) → int[source]¶

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

List[LinearDisassemblyLine]

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: LinearViewCursor) → List[LinearDisassemblyLine][source]¶

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

Parameters

pos (LinearViewCursor) – Position to start retrieving linear disassembly lines from

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)
[<0x10001488: push    dword [ebp+0x10 {arg_c}]>, ... , <0x1000149a: >]
>>> bv.get_previous_linear_disassembly_lines(pos)
[<0x10001483: xor     eax, eax  {0x0}>, ... , <0x10001488: >]

Return type

get_recent_basic_block_at(addr: int) → Optional[BasicBlock][source]¶

Parameters: addr (int) –
Return type: Optional[BasicBlock]

get_recent_function_at(addr: int) → Optional[Function][source]¶

Parameters: addr (int) –
Return type: Optional[Function]

get_section_by_name(name: str) → Optional[Section][source]¶

Parameters: name (str) –
Return type: Optional[Section]

get_sections_at(addr: int) → List[Section][source]¶

Parameters: addr (int) –
Return type: List[Section]

get_segment_at(addr: int) → Optional[Segment][source]¶

get_segment_at gets the Segment a given virtual address is located in

Parameters: addr (int) – A virtual address
Returns: The segment, if it was found
Return type: Optional[Segment]

get_sizes_referenced(name: _types.QualifiedNameType, offset: int) → List[int][source]¶

get_sizes_referenced returns a list of access sizes to the specified type.

Parameters

name (QualifiedName) – name of type to query for references
offset (int) – offset of the field

Returns

a list of sizes of the accesses to it.

Return type

list

Example

>>> bv.get_sizes_referenced('B', 16)
[1, 8]
>>>

get_string_at(addr: int, partial: bool = False) → Optional[StringReference][source]¶

get_string_at returns the string that falls on given virtual address.

Note

This returns discovered strings and is therefore governed by analysis.limits.minStringLength and other settings. For an alternative API that simply returns any potential c-string at a given location, use get_ascii_string_at.

Parameters

addr (int) – virtual address to get the string from
partial (bool) – whether to return a partial string reference or not

Returns

returns the StringReference at the given virtual address, otherwise None.

Return type

StringReference

Example

>>> bv.get_string_at(0x40302f)
<StringType.AsciiString: 0x403028, len 0x12>

get_strings(start: Optional[int] = None, length: Optional[int] = None) → List[StringReference][source]¶

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

Note that this API will only return strings that have been identified by the string-analysis and thus governed by the minimum and maximum length settings and unrelated to the type system.

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(StringReference)

Example

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

get_symbol_at(addr: int, namespace: _types.NameSpaceType = None) → Optional[_types.CoreSymbol][source]¶

get_symbol_at returns the Symbol at the provided virtual address.

Parameters

addr (int) – virtual address to query for symbol
namespace (_types.NameSpaceType) – (optional) the namespace of the symbols to retrieve

Returns

CoreSymbol for the given virtual address

Return type

CoreSymbol

Example

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

get_symbol_by_raw_name(name: str, namespace: _types.NameSpaceType = None) → Optional[_types.CoreSymbol][source]¶

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

Parameters

name (str) – raw (mangled) name of Symbol to be retrieved
namespace (_types.NameSpaceType) – (optional) the namespace to search for the given symbol

Returns

CoreSymbol object corresponding to the provided raw name

Return type

CoreSymbol

Example

>>> bv.get_symbol_by_raw_name('[email protected]@@[email protected]@[email protected]@Z')
<FunctionSymbol: "public: static enum Foobar::foo __cdecl Foobar::testf(enum Foobar::foo)" @ 0x10001100>
>>>

get_symbols(start: Optional[int] = None, length: Optional[int] = None, namespace: _types.NameSpaceType = None) → List[_types.CoreSymbol][source]¶

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

Parameters

start (Optional[int]) – optional start virtual address
length (Optional[int]) – optional length
namespace (_types.NameSpaceType) –

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" @ 0x1000200c>]
>>>

get_symbols_by_name(name: str, namespace: _types.NameSpaceType = None, ordered_filter: Optional[List[SymbolType]] = None) → List[_types.CoreSymbol][source]¶

get_symbols_by_name retrieves a list of Symbol objects for the given symbol name and ordered filter

Parameters

name (str) – name of Symbol object to be retrieved
namespace (_types.NameSpaceType) – (optional) the namespace to search for the given symbol
namespace – (optional) the namespace to search for the given symbol
ordered_filter (Optional[List[SymbolType]]) – (optional) an ordered filter based on SymbolType

Returns

Symbol object corresponding to the provided name

Return type

Symbol

Example

>>> bv.get_symbols_by_name('[email protected]@@[email protected]@[email protected]@Z')
[<FunctionSymbol: "public: static enum Foobar::foo __cdecl Foobar::testf(enum Foobar::foo)" @ 0x10001100>]
>>>

get_symbols_by_raw_name(name: str, namespace: _types.NameSpaceType = None) → List[_types.CoreSymbol][source]¶

Parameters

name (str) –
namespace (_types.NameSpaceType) –

Return type

List[_types.CoreSymbol]

get_symbols_of_type(sym_type: SymbolType, start: Optional[int] = None, length: Optional[int] = None, namespace: _types.NameSpaceType = None) → List[_types.CoreSymbol][source]¶

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: SymbolType
start (Optional[int]) – optional start virtual address
length (Optional[int]) – optional length
namespace (_types.NameSpaceType) –

Returns

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

Return type

list(CoreSymbol)

Example

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

get_tag(id: str) → Optional[Tag][source]¶

Get a tag by its id. Note this does not tell you anything about where it is used.

Parameters: id (str) – tag id
Returns: the relevant tag, if it exists
Return type: Tag

get_tag_type(name: str) → Optional[TagType][source]¶

Get a tag type by its name. Shorthand for get_tag_type_by_name()

Parameters: name (str) – Name of the tag type
Returns: The relevant tag type, if it exists
Return type: TagType

get_tag_type_by_id(id: str) → Optional[TagType][source]¶

Get a tag type by its id

Parameters: id (str) – Id of the tag type
Returns: The relevant tag type, if it exists
Return type: TagType

get_tag_type_by_name(name: str) → Optional[TagType][source]¶

Get a tag type by its name

Parameters: name (str) – Name of the tag type
Returns: The relevant tag type, if it exists
Return type: TagType

get_type_by_id(id: str) → Optional[Type][source]¶

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: _types.QualifiedNameType) → Optional[_types.Type][source]¶

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: _types.QualifiedNameType) → str[source]¶

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_library(name: str) → Optional[TypeLibrary][source]¶

get_type_library returns the TypeLibrary

Parameters: name (str) – Library name to lookup
Returns: The Type Library object, if any
Return type: TypeLibrary or None
Example

get_type_name_by_id(id: str) → Optional[QualifiedName][source]¶

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_type_refs_for_type(name: _types.QualifiedNameType) → List[_types.TypeReferenceSource][source]¶

get_type_refs_for_type returns a list of TypeReferenceSource objects (xrefs or cross-references) that reference the provided QualifiedName.

Parameters

name (QualifiedName) – name of type to query for references

Returns

List of references for the given type

Return type

Example

>>> bv.get_type_refs_for_type('A')
['<type D, offset 0x8, direct>', '<type C, offset 0x10, indirect>']
>>>

get_type_refs_for_type_field(name: _types.QualifiedNameType, offset: int) → List[_types.TypeReferenceSource][source]¶

get_type_refs_for_type returns a list of TypeReferenceSource objects (xrefs or cross-references) that reference the provided type field.

Parameters

name (QualifiedName) – name of type to query for references
offset (int) – offset of the field, relative to the type

Returns

List of references for the given type

Return type

Example

>>> bv.get_type_refs_for_type_field('A', 0x8)
['<type D, offset 0x8, direct>', '<type C, offset 0x10, indirect>']
>>>

get_types_referenced(name: QualifiedName, offset: int) → List[Type][source]¶

get_types_referenced returns a list of types related to the type field access.

Parameters

name (QualifiedName) – name of type to query for references
offset (int) – offset of the field

Returns

a list of types related to the type field access.

Return type

list

Example

>>> bv.get_types_referenced('B', 0x10)
[<type: bool>, <type: char, 0% confidence>]
>>>

get_unique_section_names(name_list: List[str]) → List[str][source]¶

Parameters: name_list (List[str]) –
Return type: List[str]

get_user_data_tags_at(addr: int) → List[Tag][source]¶

get_user_data_tags_at gets a list of all user Tag objects for a data address.

Parameters: addr (int) – address to get tags at
Returns: A list of data Tag objects
Return type: list(Tag)

get_user_data_tags_in_range(address_range: AddressRange) → List[Tuple[int, Tag]][source]¶

get_user_data_tags_in_range gets a list of all user data Tag objects in a given range. Range is inclusive at the start, exclusive at the end.

Parameters: address_range (AddressRange) – address range from which to get tags
Returns: A list of (address, data tag) tuples
Return type: list((int, Tag))

get_user_data_tags_of_type(addr: int, tag_type: TagType) → List[Tag][source]¶

get_user_data_tags_of_type gets a list of all user Tag objects for a data address of a given type.

Parameters

addr (int) – address to get tags at
tag_type (TagType) – TagType object to match in searching

Returns

A list of data Tag objects

Return type

list(Tag)

get_view_of_type(name: str) → Optional[BinaryView][source]¶

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

has_initial_analysis() → bool[source]¶

has_initial_analysis check for the presence of an initial analysis in this BinaryView.

Returns: True if the BinaryView has a valid initial analysis, False otherwise
Return type: bool

hlil_functions(preload_limit: Optional[int] = None, function_generator: Optional[Generator[Function, None, None]] = None) → Generator[HighLevelILFunction, None, None][source]¶

Generates a list of il functions. This method should be used instead of ‘functions’ property if HLIL is needed and performance is a concern.

Parameters

preload_limit (Optional[int]) –
function_generator (Optional[Generator[Function, None, None]]) –

Return type

Generator[HighLevelILFunction, None, None]

import_library_object(name: str, lib: Optional[TypeLibrary] = None) → Optional[Type][source]¶

import_library_object recursively imports an object from the specified type library, or, if no library was explicitly provided, the first type library associated with the current BinaryView that provides the name requested.

This may have the impact of loading other type libraries as dependencies on other type libraries are lazily resolved when references to types provided by them are first encountered.

Note

If you are implementing a custom BinaryView and use this method to import object types,

you should then call record_imported_object with the details of where the object is located.

Parameters

name (QualifiedName) –
lib (TypeLibrary) –

Returns

the object type, with any interior NamedTypeReferences renamed as necessary to be appropriate for the current view

Return type

Type

import_library_type(name: str, lib: Optional[TypeLibrary] = None) → Optional[Type][source]¶

import_library_type recursively imports a type from the specified type library, or, if no library was explicitly provided, the first type library associated with the current BinaryView that provides the name requested.

This may have the impact of loading other type libraries as dependencies on other type libraries are lazily resolved when references to types provided by them are first encountered.

Note that the name actually inserted into the view may not match the name as it exists in the type library in the event of a name conflict. To aid in this, the Type object returned is a NamedTypeReference to the deconflicted name used.

Parameters

name (QualifiedName) –
lib (TypeLibrary) –

Returns

a NamedTypeReference to the type, taking into account any renaming performed

Return type

Type

init() → bool[source]¶

Return type: bool

insert(addr: int, data: bytes) → int[source]¶

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

Parameters

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

Returns

number of bytes inserted to virtual address addr

Return type

Example

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

static internal_namespace() → NameSpace[source]¶

Internal namespace for the current BinaryView

Return type: NameSpace

invert_branch(addr: int, arch: Optional[Architecture] = None) → bool[source]¶

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

Example

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

is_always_branch_patch_available(addr: int, arch: Optional[Architecture] = None) → bool[source]¶

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

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: int, arch: Optional[Architecture] = None) → bool[source]¶

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

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: int, arch: Optional[Architecture] = None) → bool[source]¶

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

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: int) → bool[source]¶

is_offset_code_semantics checks if a 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 code semantics, False if the virtual address is invalid or error
Return type: bool

is_offset_executable(addr: int) → bool[source]¶

is_offset_executable checks if a 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: int) → bool[source]¶

is_offset_extern_semantics checks if a 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 external references, false if the virtual address is invalid or error
Return type: bool

is_offset_readable(addr: int) → bool[source]¶

is_offset_readable checks if a 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: int) → bool[source]¶

is_offset_writable checks if a 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: int) → bool[source]¶

is_offset_writable_semantics checks if a 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: int, arch: Optional[Architecture] = None) → bool[source]¶

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

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: int, arch: Optional[Architecture] = None) → bool[source]¶

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

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: _types.QualifiedNameType) → bool[source]¶

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

Return type

is_valid_offset(addr: int) → bool[source]¶

is_valid_offset checks if a 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

lookup_imported_object_library(addr: int, platform: Optional[Platform] = None) → Optional[Tuple[TypeLibrary, str]][source]¶

lookup_imported_object_library gives you details of which type library and name was used to determine the type of a symbol at a given address

Parameters

addr (int) – address of symbol at import site
platform (Optional[Platform]) – Platform of symbol at import site

Returns

A tuple of [TypeLibrary, str] with the library and name used, or None if it was not imported

Return type

Tuple[TypeLibrary, str]

mlil_functions(preload_limit: Optional[int] = None, function_generator: Optional[Generator[Function, None, None]] = None) → Generator[MediumLevelILFunction, None, None][source]¶

Generates a list of il functions. This method should be used instead of ‘functions’ property if MLIL is needed and performance is a concern.

Parameters

preload_limit (Optional[int]) –
function_generator (Optional[Generator[Function, None, None]]) –

Return type

Generator[MediumLevelILFunction, None, None]

navigate(view_name: str, offset: int) → bool[source]¶

navigate navigates the UI to the specified virtual address in the specified View

The View name is created by combining a View type (e.g. “Graph”) with a BinaryView type (e.g. “Mach-O”), seperated by a colon, resulting in something like “Graph:Mach-O”.

Parameters

view_name (str) – View name.
offset (int) – address to navigate to

Returns

whether navigation succeeded

Return type

Example

>>> bv.navigate(bv.view, bv.start)
True
>>> bv.file.existing_views
['Mach-O', 'Raw']
>>> import binaryninjaui
>>> [i.getName() for i in binaryninjaui.ViewType.getTypes()]
['Graph', 'Hex', 'Linear', 'Strings', 'Types', 'Triage', 'Bytes']
>>> bv.navigate('Graph:Mach-O', bv.entry_point)
True

never_branch(addr: int, arch: Optional[Architecture] = None) → bool[source]¶

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

Example

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

static new(data: Optional[Union[bytes, bytearray, DataBuffer]] = None, file_metadata: Optional[FileMetadata] = None) → Optional[BinaryView][source]¶

Parameters

data (Optional[Union[bytes, bytearray, DataBuffer]]) –
file_metadata (Optional[FileMetadata]) –

Return type

Optional[BinaryView]

notify_data_inserted(offset: int, length: int) → None[source]¶

Parameters

offset (int) –
length (int) –

Return type

None

notify_data_removed(offset: int, length: int) → None[source]¶

Parameters

offset (int) –
length (int) –

Return type

None

notify_data_written(offset: int, length: int) → None[source]¶

Parameters

offset (int) –
length (int) –

Return type

None

static open(src, file_metadata=None) → Optional[BinaryView][source]¶

Return type: Optional[BinaryView]

parse_expression(expression: str, here: int = 0) → int[source]¶

Evaluates a 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

Symbols are everything in bv.symbols, unnamed DataVariables (i.e. data_00005000), unnamed functions (i.e. sub_00005000), or section names (i.e. .text)

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 dereference operators similar to BNIL style IL:

[<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 (or more succinctly: $) keyword can be used in calculations and is defined as the here parameter, or the currently selected address

The $start/$end keyword represents the address of the first/last bytes in the file respectively

Parameters

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

Return type

parse_possiblevalueset(value: str, state: RegisterValueType, here: int = 0) → PossibleValueSet[source]¶

Evaluates a string representation of a PossibleValueSet into an instance of the PossibleValueSet value.

Note

Values are evaluated based on the rules as specified for parse_expression API. This implies that a ConstantValue [0x4000].d can be provided given that 4 bytes can be read at 0x4000. All constants are considered to be in hexadecimal form by default.

The parser uses the following rules:

ConstantValue - <value>
ConstantPointerValue - <value>
StackFrameOffset - <value>
SignedRangeValue - <value>:<value>:<value>{,<value>:<value>:<value>}* (Multiple ValueRanges can be provided by separating them by commas)
UnsignedRangeValue - <value>:<value>:<value>{,<value>:<value>:<value>}* (Multiple ValueRanges can be provided by separating them by commas)
InSetOfValues - <value>{,<value>}*
NotInSetOfValues - <value>{,<value>}*

Parameters

value (str) – PossibleValueSet value to be parsed
state (RegisterValueType) – State for which the value is to be parsed
here (int) – (optional) Base address for relative expressions, defaults to zero

Return type

PossibleValueSet

Example

>>> psv_c = bv.parse_possiblevalueset("400", RegisterValueType.ConstantValue)
>>> psv_c
<const 0x400>
>>> psv_ur = bv.parse_possiblevalueset("1:10:1", RegisterValueType.UnsignedRangeValue)
>>> psv_ur
<unsigned ranges: [<range: 0x1 to 0x10>]>
>>> psv_is = bv.parse_possiblevalueset("1,2,3", RegisterValueType.InSetOfValues)
>>> psv_is
<in set([0x1, 0x2, 0x3])>
>>>

parse_type_string(text: str) → Tuple[Type, QualifiedName][source]¶

parse_type_string parses string containing C into a single type Type. In contrast to the parse_types_from_source or parse_types_from_source_file, parse_type_string can only load a single type, though it can take advantage of existing type information in the binary view, while those two APIs do not.

Parameters

text (str) – C source code 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')
>>>

parse_types_from_string(text: str, options: Optional[List[str]] = None, include_dirs: Optional[List[str]] = None) → TypeParserResult[source]¶

parse_types_from_string parses string containing C into a TypeParserResult objects. This API unlike the parse_types_from_source allows the reference of types already defined in the BinaryView.

Parameters

text (str) – C source code string of types, variables, and function types, to create
options (Optional[List[str]]) – Optional list of string options to be passed into the type parser
include_dirs (Optional[List[str]]) – Optional list of header search directories

Returns

TypeParserResult (a SyntaxError is thrown on parse error)

Return type

TypeParserResult

Example

>>> bv.parse_types_from_string('int foo;\nint bar(int x);\nstruct bas{int x,y;};\n')
({types: {'bas': <type: struct bas>}, variables: {'foo': <type: int32_t>}, functions:{'bar':
<type: int32_t(int32_t x)>}}, '')
>>>

abstract perform_get_address_size() → int[source]¶

Return type: int

perform_get_default_endianness() → Endianness[source]¶

perform_get_default_endianness implements a check which returns the Endianness of the BinaryView

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() → int[source]¶

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() → int[source]¶

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: int) → ModificationStatus[source]¶

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: int) → int[source]¶

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() → int[source]¶

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: int, data: bytes) → int[source]¶

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 (bytes) – the data to be inserted

Returns

length of data inserted, should return 0 on error

Return type

perform_is_executable() → bool[source]¶

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: int) → bool[source]¶

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: bool

perform_is_offset_readable(offset: int) → bool[source]¶

perform_is_offset_readable implements a check if a 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: int) → bool[source]¶

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() → bool[source]¶

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

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: int) → bool[source]¶

perform_is_valid_offset implements a check if a 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: int, length: int) → bytes[source]¶

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

bytes

perform_remove(addr: int, length: int) → int[source]¶

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
length (int) – the number of bytes to be removed

Returns

length of data removed, should return 0 on error

Return type

perform_save(accessor) → bool[source]¶

Return type: bool

perform_write(addr: int, data: bytes) → int[source]¶

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 (bytes) – the data to be written

Returns

length of data written, should return 0 on error

Return type

query_metadata(key: str) → metadata.MetadataValueType[source]¶

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

Parameters

key (str) – 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'

range_contains_relocation(addr: int, size: int) → bool[source]¶

Checks if the specified range overlaps with a relocation

Parameters

addr (int) –
size (int) –

Return type

read(addr: int, length: int) → bytes[source]¶

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

bytes

Example

>>> #Opening a x86_64 Mach-O binary
>>> bv = BinaryViewType['Raw'].open("/bin/ls") #note that we are using open instead of get_view_of_file to get the raw view
>>> bv.read(0,4)
b'\xcf\xfa\xed\xfe'

read_int(address: int, size: int, sign: bool = True, endian: Optional[Endianness] = None) → int[source]¶

Parameters

address (int) –
size (int) –
sign (bool) –
endian (Optional[Endianness]) –

Return type

read_pointer(address: int, size: Optional[int] = None) → int[source]¶

Parameters

address (int) –
size (Optional[int]) –

Return type

reader(address: Optional[int] = None) → BinaryReader[source]¶

Parameters: address (Optional[int]) –
Return type: BinaryReader

reanalyze() → None[source]¶

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

Return type: None

rebase(address: int, force: Optional[bool] = False, progress_func: Optional[Callable[[int, int], bool]] = None) → Optional[BinaryView][source]¶

rebase rebase the existing BinaryView into a new BinaryView at the specified virtual address

Note

This method does not update corresponding UI components. If the BinaryView is associated with UI components then initiate the rebase operation within the UI, e.g. using the command palette. If working with views that are not associated with UI components while the UI is active, then set force to True to enable rebasing.

Parameters

address (int) – virtual address of the start of the BinaryView
force (bool) – enable rebasing while the UI is active
progress_func (Optional[Callable[[int, int], bool]]) –

Returns

the new BinaryView object or None on failure

Return type

BinaryView or None

record_imported_object_library(lib: TypeLibrary, name: str, addr: int, platform: Optional[Platform] = None) → None[source]¶

record_imported_object_library should be called by custom py:py:class:BinaryView implementations when they have successfully imported an object from a type library (eg a symbol’s type). Values recorded with this function will then be queryable via lookup_imported_object_library.

Parameters

lib (TypeLibrary) – Type Library containing the imported type
name (str) – Name of the object in the type library
addr (int) – address of symbol at import site
platform (Optional[Platform]) – Platform of symbol at import site

Return type

None

redo() → None[source]¶

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() → None[source]¶

Return type: None

register_notification(notify: BinaryDataNotification) → None[source]¶

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: Platform) → None[source]¶

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: int) → List[Tuple[int, int]][source]¶

List of relocation range tuples for a given address

Parameters: addr (int) –
Return type: List[Tuple[int, int]]

remove(addr: int, length: int) → int[source]¶

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

Example

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

remove_auto_data_tag(addr: int, tag: Tag) → None[source]¶

remove_auto_data_tag removes a Tag object at a data address.

Parameters

addr (int) – address at which to remove the tag
tag (Tag) – Tag object to be removed

Return type

None

remove_auto_data_tags_of_type(addr: int, tag_type: TagType) → None[source]¶

remove_auto_data_tags_of_type removes all data tags at the given address of the given type.

Parameters

addr (int) – address at which to add the tags
tag_type (TagType) – TagType object to match for removing

Return type

None

remove_auto_section(name: str) → None[source]¶

Parameters: name (str) –
Return type: None

remove_auto_segment(start: int, length: int) → None[source]¶

remove_auto_segment removes an automatically generated segment from the current segment mapping.

Parameters

start (int) – virtual address of the start of the segment
length (int) – length of the segment

Return type

None

Warning

This action is not persistent across saving of a BNDB and must be re-applied each time a BNDB is loaded.

remove_component(_component: Union[Component, str]) → bool[source]¶

Remove a component from the tree entirely.

Parameters: _component (Union[Component, str]) – Component to remove
Returns: Whether the removal was successful
Return type: bool

remove_expression_parser_magic_value(name: str) → None[source]¶

Parameters: name (str) –
Return type: None

remove_expression_parser_magic_values(names: List[str]) → None[source]¶

Parameters: names (List[str]) –
Return type: None

remove_function(func: Function) → None[source]¶

remove_function removes the function func from the list of functions

Warning

This method should only be used when the function that is removed is expected to re-appear after any other analysis executes that could re-add it. Most users will want to use remove_user_function in their scripts.

Parameters

func (Function) – a Function object.

Return type

None

Example

>>> bv.functions
[<func: [email protected]>]
>>> bv.remove_function(next(bv.functions))
>>> bv.functions
[]

remove_metadata(key: str) → None[source]¶

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

Parameters

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

Return type

None

Example

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

remove_tag_type(tag_type: TagType) → None[source]¶

remove_tag_type removes a TagType and all tags that use it

Parameters: tag_type (TagType) – The TagType to remove
Return type: None

remove_user_data_ref(from_addr: int, to_addr: int) → None[source]¶

remove_user_data_ref removes a user-specified data cross-reference (xref) from the address from_addr to the address to_addr. This function will only remove user-specified references, not ones generated during autoanalysis. If the reference does not exist, no action is performed.

Parameters

from_addr (int) – the reference’s source virtual address.
to_addr (int) – the reference’s destination virtual address.

Return type

None

remove_user_data_tag(addr: int, tag: Tag) → None[source]¶

remove_user_data_tag removes a Tag object at a data address. Since this removes a user tag, it will be added to the current undo buffer.

Parameters

addr (int) – address at which to remove the tag
tag (Tag) – Tag object to be removed

Return type

None

remove_user_data_tags_of_type(addr: int, tag_type: TagType) → None[source]¶

remove_user_data_tags_of_type removes all data tags at the given address of the given type. Since this removes user tags, it will be added to the current undo buffer.

Parameters

addr (int) – address at which to add the tags
tag_type (TagType) – TagType object to match for removing

Return type

None

remove_user_function(func: Function) → None[source]¶

remove_user_function removes the function func from the list of functions as a user action.

Note

This API will prevent the function from being re-created if any analysis later triggers that would re-add it, unlike remove_function.

Parameters

func (Function) – a Function object.

Return type

None

Example

>>> bv.functions
[<func: [email protected]>]
>>> bv.remove_user_function(next(bv.functions))
>>> bv.functions
[]

remove_user_section(name: str) → None[source]¶

Parameters: name (str) –
Return type: None

remove_user_segment(start: int, length: int) → None[source]¶

Parameters

start (int) –
length (int) –

Return type

None

rename_type(old_name: _types.QualifiedNameType, new_name: _types.QualifiedNameType) → None[source]¶

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: Union[FileAccessor, str]) → bool[source]¶

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: True on success, False on failure
Return type: bool

save_auto_snapshot(progress_func: Optional[Callable[[int, int], bool]] = None, settings: Optional[SaveSettings] = None) → bool[source]¶

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 (callback) – optional function to be called with the current progress and total count.
settings (SaveSettings) – optional argument for special save options.

Returns

True if it successfully saved the snapshot, False otherwise

Return type