binaryview module

binaryninja.binaryview.ActiveAnalysisInfo(...)

binaryninja.binaryview.AdvancedILFunctionList(view)

The purpose of this class is to generate IL functions IL function in the background improving the performance of iterating MediumLevelIL and HighLevelILFunctions.

binaryninja.binaryview.AnalysisCompletionEvent(...)

The AnalysisCompletionEvent object provides an asynchronous mechanism for receiving callbacks when analysis is complete.

binaryninja.binaryview.AnalysisInfo(state, ...)

binaryninja.binaryview.AnalysisProgress(...)

binaryninja.binaryview.BinaryDataNotification([...])

class BinaryDataNotification provides an interface for receiving event notifications.

binaryninja.binaryview.BinaryDataNotificationCallbacks(...)

binaryninja.binaryview.BinaryReader(view[, ...])

class BinaryReader is a convenience class for reading binary data.

binaryninja.binaryview.BinaryView([...])

class BinaryView implements a view on binary data, and presents a queryable interface of a binary file.

binaryninja.binaryview.BinaryViewEvent()

The BinaryViewEvent object provides a mechanism for receiving callbacks when a BinaryView is Finalized or the initial analysis is finished.

binaryninja.binaryview.BinaryViewType(handle)

The BinaryViewType object is used internally and should not be directly instantiated.

binaryninja.binaryview.BinaryWriter(view[, ...])

class BinaryWriter is a convenience class for writing binary data.

binaryninja.binaryview.CoreDataVariable(...)

binaryninja.binaryview.DataVariable(view, ...)

binaryninja.binaryview.DataVariableAndName(...)

binaryninja.binaryview.FunctionList(view)

binaryninja.binaryview.MemoryMap(handle)

The MemoryMap object is used to describe a system level MemoryMap for which a BinaryView is loaded into. A loaded

binaryninja.binaryview.ReferenceSource(...)

binaryninja.binaryview.Section(handle)

The Section object is returned during BinaryView creation and should not be directly instantiated.

binaryninja.binaryview.Segment(handle)

The Segment object is returned during BinaryView creation and should not be directly instantiated.

binaryninja.binaryview.StringReference(bv, ...)

binaryninja.binaryview.StructuredDataValue(t, ...)

binaryninja.binaryview.StructuredDataView(bv, ...)

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

binaryninja.binaryview.SymbolMapping(view)

SymbolMapping object is used to improve performance of the bv.symbols API.

binaryninja.binaryview.Tag(handle)

The Tag object is created by other APIs (create_*_tag) and should not be directly instantiated.

binaryninja.binaryview.TagType(handle)

The TagType object is created by the create_tag_type API and should not be directly instantiated.

binaryninja.binaryview.TypeMapping(view[, ...])

TypeMapping object is used to improve performance of the bv.types API.

binaryninja.binaryview.TypedDataAccessor(...)

binaryninja.binaryview.TypedDataReader

alias of TypedDataAccessor

class ActiveAnalysisInfo(func: '_function.Function', analysis_time: int, update_count: int, submit_count: int)[source]

Bases: object

Parameters:
  • func (Function) –

  • analysis_time (int) –

  • update_count (int) –

  • submit_count (int) –

analysis_time: int
func: Function
submit_count: int
update_count: int
class AdvancedILFunctionList(view: BinaryView, preload_limit: int = 19, functions: Iterable | None = None)[source]

Bases: object

The purpose of this class is to generate IL functions IL function in the background improving the performance of iterating MediumLevelIL and HighLevelILFunctions.

Using this class or the associated helper methods BinaryView.mlil_functions / BinaryView.hlil_functions can improve the performance of ILFunction iteration significantly

The prefetch_limit property is configurable and should be modified based upon your machines hardware and RAM limitations.

Warning

Setting the prefetch_limit excessively high can result in high memory utilization.

Example:
>>> import timeit
>>> len(bv.functions)
4817
>>> # Calculate the average time to generate hlil for all functions withing 'bv':
>>> timeit.timeit(lambda:[f.hlil for f in bv.functions], number=1)
21.761621682000168
>>> t1 = _
>>> # Now try again with the advanced analysis iterator
>>> timeit.timeit(lambda:[f for f in bv.hlil_functions(128)], number=1)
6.3147709989998475
>>> t1/_
3.4461458199270947
>>> # This particular binary can iterate hlil functions 3.4x faster
>>> # If you don't need IL then its still much faster to just use `bv.functions`
>>> timeit.timeit(lambda:[f for f in bv.functions], number=1)
0.02230275600004461
Parameters:
class AnalysisCompletionEvent(view: BinaryView, callback: Callable[[AnalysisCompletionEvent], None] | Callable[[], None])[source]

Bases: object

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

Example:
>>> def on_complete(self):
...     print("Analysis Complete", self._view)
...
>>> evt = AnalysisCompletionEvent(bv, on_complete)
>>>
Parameters:
cancel() None[source]

The cancel method will cancel analysis for an AnalysisCompletionEvent.

Warning

This method should only be used when the system is being shut down and no further analysis should be done afterward.

Return type:

None

property view: BinaryView
class AnalysisInfo(state: AnalysisState, analysis_time: int, active_info: List[ActiveAnalysisInfo])[source]

Bases: object

Parameters:
active_info: List[ActiveAnalysisInfo]
analysis_time: int
state: AnalysisState
class AnalysisProgress(state: AnalysisState, count: int, total: int)[source]

Bases: object

Parameters:
count: int
state: AnalysisState
total: int
class BinaryDataNotification(notifications: NotificationType | None = None)[source]

Bases: object

class BinaryDataNotification provides an interface for receiving event notifications. Usage requires inheriting from this interface, overriding the relevant event handlers, and registering the BinaryDataNotification instance with a BinaryView using the register_notification method.

By default, a BinaryDataNotification instance receives notifications for all available notification types. It is recommended for users of this interface to initialize the BinaryDataNotification base class with with specific callbacks of interest by passing the appropriate NotificationType flags into the __init__ constructor.

Handlers provided by the user should aim to limit the amount of processing within the callback. The callback context holds a global lock, preventing other threads from making progress during the callback phase. While most of the API can be used safely during this time, care must be taken when issuing a call that can block, as waiting for a thread requiring the global lock can result in deadlock.

The NotificationBarrier is a special NotificationType that is disabled by default. To enable it, the NotificationBarrier flag must be passed to __init__. This notification is designed to facilitate efficient batch processing of other notification types. The idea is to collect other notifications of interest into a cache, which can be very efficient as it doesn’t require additional locks. After some time, the core generates a NotificationBarrier event, providing a safe context to move the cache for processing by a different thread.

To control the time of the next NotificationBarrier event, return the desired number of milliseconds until the next event from the NotificationBarrier callback. Returning zero quiesces future NotificationBarrier events. If the NotificationBarrier is quiesced, the reception of a new callback of interest automatically generates a new NotificationBarrier call after that notification is delivered. This mechanism effectively allows throttling and quiescing when necessary.

Note

Note that the core generates a NotificationBarrier as part of the BinaryDataNotification registration process. Registering the same BinaryDataNotification instance again results in a gratuitous NotificationBarrier event, which can be useful in situations requiring a safe context for processing due to some other asynchronous event (e.g., user interaction).

Example:

Parameters:

notifications (NotificationType) –

>>> class NotifyTest(binaryninja.BinaryDataNotification):
...     def __init__(self):
...             super(NotifyTest, self).__init__(binaryninja.NotificationType.NotificationBarrier | binaryninja.NotificationType.FunctionLifetime | binaryninja.NotificationType.FunctionUpdated)
...             self.received_event = False
...     def notification_barrier(self, view: 'BinaryView') -> int:
...             has_events = self.received_event
...             self.received_event = False
...             log_info("notification_barrier")
...             if has_events:
...                     return 250
...             else:
...                     return 0
...     def function_added(self, view: 'BinaryView', func: '_function.Function') -> None:
...             self.received_event = True
...             log_info("function_added")
...     def function_removed(self, view: 'BinaryView', func: '_function.Function') -> None:
...             self.received_event = True
...             log_info("function_removed")
...     def function_updated(self, view: 'BinaryView', func: '_function.Function') -> None:
...             self.received_event = True
...             log_info("function_updated")
...
>>>
>>> bv.register_notification(NotifyTest())
>>>
component_added(view: BinaryView, _component: Component) None[source]
Parameters:
Return type:

None

component_data_var_added(view: BinaryView, _component: Component, var: DataVariable)[source]
Parameters:
component_data_var_removed(view: BinaryView, _component: Component, var: DataVariable)[source]
Parameters:
component_function_added(view: BinaryView, _component: Component, func: Function)[source]
Parameters:
component_function_removed(view: BinaryView, _component: Component, func: Function)[source]
Parameters:
component_moved(view: BinaryView, formerParent: Component, newParent: Component, _component: Component) None[source]
Parameters:
Return type:

None

component_name_updated(view: BinaryView, previous_name: str, _component: Component) None[source]
Parameters:
Return type:

None

component_removed(view: BinaryView, formerParent: Component, _component: Component) None[source]
Parameters:
Return type:

None

data_inserted(view: BinaryView, offset: int, length: int) None[source]
Parameters:
Return type:

None

data_metadata_updated(view: BinaryView, offset: int) None[source]
Parameters:
Return type:

None

data_removed(view: BinaryView, offset: int, length: int) None[source]
Parameters:
Return type:

None

data_var_added(view: BinaryView, var: DataVariable) None[source]
Parameters:
Return type:

None

data_var_removed(view: BinaryView, var: DataVariable) None[source]
Parameters:
Return type:

None

data_var_updated(view: BinaryView, var: DataVariable) None[source]
Parameters:
Return type:

None

data_written(view: BinaryView, offset: int, length: int) None[source]
Parameters:
Return type:

None

function_added(view: BinaryView, func: Function) None[source]
Parameters:
Return type:

None

function_removed(view: BinaryView, func: Function) None[source]
Parameters:
Return type:

None

function_update_requested(view: BinaryView, func: Function) None[source]
Parameters:
Return type:

None

function_updated(view: BinaryView, func: Function) None[source]
Parameters:
Return type:

None

notification_barrier(view: BinaryView) int[source]
Parameters:

view (BinaryView) –

Return type:

int

redo_entry_taken(view: BinaryView, entry: UndoEntry)[source]
Parameters:
section_added(view: BinaryView, section: Section) None[source]
Parameters:
Return type:

None

section_removed(view: BinaryView, section: Section) None[source]
Parameters:
Return type:

None

section_updated(view: BinaryView, section: Section) None[source]
Parameters:
Return type:

None

segment_added(view: BinaryView, segment: Segment) None[source]
Parameters:
Return type:

None

segment_removed(view: BinaryView, segment: Segment) None[source]
Parameters:
Return type:

None

segment_updated(view: BinaryView, segment: Segment) None[source]
Parameters:
Return type:

None

string_found(view: BinaryView, string_type: StringType, offset: int, length: int) None[source]
Parameters:
Return type:

None

string_removed(view: BinaryView, string_type: StringType, offset: int, length: int) None[source]
Parameters:
Return type:

None

symbol_added(view: BinaryView, sym: CoreSymbol) None[source]
Parameters:
Return type:

None

symbol_removed(view: BinaryView, sym: CoreSymbol) None[source]
Parameters:
Return type:

None

symbol_updated(view: BinaryView, sym: CoreSymbol) None[source]
Parameters:
Return type:

None

tag_added(view: BinaryView, tag: Tag, ref_type: TagReferenceType, auto_defined: bool, arch: Architecture | None, func: Function | None, addr: int) None[source]
Parameters:
Return type:

None

tag_removed(view: BinaryView, tag: Tag, ref_type: TagReferenceType, auto_defined: bool, arch: Architecture | None, func: Function | None, addr: int) None[source]
Parameters:
Return type:

None

tag_type_updated(view: BinaryView, tag_type) None[source]
Parameters:

view (BinaryView) –

Return type:

None

tag_updated(view: BinaryView, tag: Tag, ref_type: TagReferenceType, auto_defined: bool, arch: Architecture | None, func: Function | None, addr: int) None[source]
Parameters:
Return type:

None

type_archive_attached(view: BinaryView, id: str, path: str)[source]
Parameters:
type_archive_connected(view: BinaryView, archive: TypeArchive)[source]
Parameters:
type_archive_detached(view: BinaryView, id: str, path: str)[source]
Parameters:
type_archive_disconnected(view: BinaryView, archive: TypeArchive)[source]
Parameters:
type_defined(view: BinaryView, name: QualifiedName, type: Type) None[source]
Parameters:
Return type:

None

type_field_ref_changed(view: BinaryView, name: QualifiedName, offset: int) None[source]
Parameters:
Return type:

None

type_ref_changed(view: BinaryView, name: QualifiedName, type: Type) None[source]
Parameters:
Return type:

None

type_undefined(view: BinaryView, name: QualifiedName, type: Type) None[source]
Parameters:
Return type:

None

undo_entry_added(view: BinaryView, entry: UndoEntry)[source]
Parameters:
undo_entry_taken(view: BinaryView, entry: UndoEntry)[source]
Parameters:
class BinaryDataNotificationCallbacks(view: BinaryView, notify: BinaryDataNotification)[source]

Bases: object

Parameters:
property notify: BinaryDataNotification
property view: BinaryView
class BinaryReader(view: BinaryView, endian: Endianness | None = None, address: int | None = None)[source]

Bases: object

class BinaryReader is a convenience class for reading binary data.

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

>>> from binaryninja import *
>>> bv = load("/bin/ls")
>>> br = BinaryReader(bv)
>>> hex(br.read32())
'0xfeedfacfL'
>>>

Or using the optional endian parameter

>>> from binaryninja import *
>>> br = BinaryReader(bv, Endianness.BigEndian)
>>> hex(br.read32())
'0xcffaedfeL'
>>>
Parameters:
read(length: int, address: int | None = None) bytes | None[source]

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

Parameters:
  • length (int) – number of bytes to read.

  • address (int) – offset to set the internal offset before reading

Returns:

length bytes from current offset

Return type:

str, or None on failure

Example:
>>> br.read(8)
'\xcf\xfa\xed\xfe\x07\x00\x00\x01'
>>>
read16(address: int | None = None) int | None[source]

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

Parameters:

address (int) – offset to set the internal offset before reading

Returns:

a two byte integer at offset.

Return type:

int, or None on failure

Example:
>>> br.seek(0x100000000)
>>> hex(br.read16())
'0xfacf'
>>>
read16be(address: int | None = None) int | None[source]

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

Parameters:

address (int) – offset to set the internal offset before reading

Returns:

a two byte integer at offset.

Return type:

int, or None on failure

Example:
>>> br.seek(0x100000000)
>>> hex(br.read16be())
'0xcffa'
>>>
read16le(address: int | None = None) int | None[source]

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

Parameters:

address (int) – offset to set the internal offset before reading

Returns:

a two byte integer at offset.

Return type:

int, or None on failure

Example:
>>> br.seek(0x100000000)
>>> hex(br.read16le())
'0xfacf'
>>>
read32(address: int | None = None) int | None[source]

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

Parameters:

address (int) – offset to set the internal offset before reading

Returns:

a four byte integer at offset.

Return type:

int, or None on failure

Example:
>>> br.seek(0x100000000)
>>> hex(br.read32())
'0xfeedfacfL'
>>>
read32be(address: int | None = None) int | None[source]

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

Parameters:

address (int) – offset to set the internal offset before reading

Returns:

a four byte integer at offset.

Return type:

int, or None on failure

Example:
>>> br.seek(0x100000000)
>>> hex(br.read32be())
'0xcffaedfe'
read32le(address: int | None = None) int | None[source]

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

Parameters:

address (int) – offset to set the internal offset before reading

Returns:

a four byte integer at offset.

Return type:

int, or None on failure

Example:
>>> br.seek(0x100000000)
>>> hex(br.read32le())
'0xfeedfacf'
>>>
read64(address: int | None = None) int | None[source]

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

Parameters:

address (int) – offset to set the internal offset before reading

Returns:

an eight byte integer at offset.

Return type:

int, or None on failure

Example:
>>> br.seek(0x100000000)
>>> hex(br.read64())
'0x1000007feedfacfL'
>>>
read64be(address: int | None = None) int | None[source]

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

Parameters:

address (int) – offset to set the internal offset before reading

Returns:

a eight byte integer at offset.

Return type:

int, or None on failure

Example:
>>> br.seek(0x100000000)
>>> hex(br.read64be())
'0xcffaedfe07000001L'
read64le(address: int | None = None) int | None[source]

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

Parameters:

address (int) – offset to set the internal offset before reading

Returns:

a eight byte integer at offset.

Return type:

int, or None on failure

Example:
>>> br.seek(0x100000000)
>>> hex(br.read64le())
'0x1000007feedfacf'
>>>
read8(address: int | None = None) int | None[source]

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

Parameters:

address (int) – offset to set the internal offset before reading

Returns:

byte at offset.

Return type:

int, or None on failure

Example:
>>> br.seek(0x100000000)
>>> br.read8()
207
>>>
seek(offset: int, whence: int | None = 0) None[source]

seek update internal offset to offset.

Parameters:
  • offset (int) – offset to set the internal offset to

  • whence (int) – optional, defaults to 0 for absolute file positioning, or 1 for relative to current location

Return type:

None

Example:
>>> hex(br.offset)
'0x100000008L'
>>> br.seek(0x100000000)
>>> hex(br.offset)
'0x100000000L'
>>>
seek_relative(offset: int) None[source]

seek_relative updates the internal offset by offset.

Parameters:

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

Return type:

None

Example:
>>> hex(br.offset)
'0x100000008L'
>>> br.seek_relative(-8)
>>> hex(br.offset)
'0x100000000L'
>>>
property endianness: Endianness

The Endianness to read data. (read/write)

Getter:

returns the endianness of the reader

Setter:

sets the endianness of the reader (BigEndian or LittleEndian)

Type:

Endianness

property eof: bool

Is end of file (read-only)

Getter:

returns boolean, true if end of file, false otherwise

Type:

bool

property offset: int

The current read offset (read/write).

Getter:

returns the current internal offset

Setter:

sets the internal offset

Type:

int

property virtual_base: int

The current virtual base offset for the stream (read/write).

Getter:

returns the current virtual base

Setter:

sets the virtual base

Type:

int

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

Bases: object

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

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

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

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

To open a file with a given BinaryView the following code is recommended:

>>> with load("/bin/ls") as bv:
...   bv
<BinaryView: '/bin/ls', start 0x100000000, len 0x142c8>

By convention in the rest of this document we will use bv to mean an open and, analyzed, BinaryView of an executable file. When a BinaryView is open on an executable view analysis is automatically run unless specific named parameters are used to disable updates. If such a parameter is used, updates can be triggered using the update_analysis_and_wait method which disassembles the executable and returns when all disassembly and analysis is complete:

>>> bv.update_analysis_and_wait()
>>>

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

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

Note

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

class QueueGenerator(t, results)[source]

Bases: object

abort_analysis() None[source]

abort_analysis will abort the currently running analysis.

Warning

This method should be considered non-recoverable and generally only used when shutdown is imminent after stopping.

Return type:

None

add_analysis_completion_event(callback: Callable[[], None]) AnalysisCompletionEvent[source]

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

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

Note

The lock held by the callback thread on the BinaryView instance ensures that other BinaryView actions can be safely performed in the callback thread.

Warning

The built-in python console automatically updates analysis after every command is run, which means this call back may not behave as expected if entered interactively.

Parameters:

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

Returns:

An initialized AnalysisCompletionEvent object

Return type:

AnalysisCompletionEvent

Example:
>>> def completionEvent():
...   print("done")
...
>>> bv.add_analysis_completion_event(completionEvent)
<binaryninja.AnalysisCompletionEvent object at 0x10a2c9f10>
>>> bv.update_analysis()
done
>>>
add_analysis_option(name: str) None[source]

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

Parameters:

name (str) – name of the analysis option. Available options are: “linearsweep”, and “signaturematcher”.

Return type:

None

Example:
>>> bv.add_analysis_option("linearsweep")
>>> bv.update_analysis_and_wait()
add_auto_data_tag(addr: int, tag: Tag)[source]

Deprecated since version 3.4.4146: Use add_tag instead

Parameters:
  • addr (int) –

  • tag (Tag) –

add_auto_section(name: str, start: int, length: int, semantics: SectionSemantics = SectionSemantics.DefaultSectionSemantics, type: str = '', align: int = 1, entry_size: int = 1, linked_section: str = '', info_section: str = '', info_data: int = 0) None[source]
Parameters:
Return type:

None

add_auto_segment(start: int, length: int, data_offset: int, data_length: int, flags: SegmentFlag) None[source]
Parameters:
Return type:

None

add_entry_point(addr: int, plat: Platform | None = None) None[source]

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

Parameters:
  • addr (int) – virtual address to start analysis from

  • plat (Platform) – Platform for the entry point analysis

Return type:

None

Example:
>>> bv.add_entry_point(0xdeadbeef)
>>>
add_expression_parser_magic_value(name: str, value: int) None[source]

Add a magic value to the expression parser.

If the magic value already exists, its value gets updated. The magic value can be used in the expression by a $ followed by its name, e.g., $foobar. It is optional to include the $ when calling this function, i.e., calling with foobar and $foobar has the same effect.

Parameters:
  • name (str) – name for the magic value to add or update

  • value (int) – value for the magic value

Returns:

Return type:

None

add_expression_parser_magic_values(names: List[str], values: List[int]) None[source]

Add a list of magic value to the expression parser.

The list names and values must have the same size. The ith name in the names will correspond to the ith value in the values.

If a magic value already exists, its value gets updated. The magic value can be used in the expression by a $ followed by its name, e.g., $foobar. It is optional to include the $ when calling this function, i.e., calling with foobar and $foobar has the same effect.

Parameters:
  • names (list(str)) – names for the magic values to add or update

  • values (list(int)) – value for the magic values

Returns:

Return type:

None

add_external_library(name: str, backing_file: ProjectFile | None = None, auto: bool = False) ExternalLibrary[source]

Add an ExternalLibrary to this BinaryView

Parameters:
  • name (str) – Name of the external library

  • backing_file (ProjectFile | None) – Optional ProjectFile that backs the external library

  • auto (bool) – Whether or not this action is the result of automated analysis

Returns:

The created ExternalLibrary

Return type:

ExternalLibrary

add_external_location(source_symbol: CoreSymbol, library: ExternalLibrary | None, target_symbol: str | None, target_address: int | None, auto: bool = False) ExternalLocation[source]

Add an ExternalLocation with its source in this BinaryView. ExternalLocations must have a target address and/or symbol.

Parameters:
  • source_symbol (CoreSymbol) – Symbol that the association is from

  • library (ExternalLibrary | None) – Library that the ExternalLocation belongs to

  • target_symbol (str | None) – Symbol that the ExternalLocation points to

  • target_address (int | None) – Address that the ExternalLocation points to

  • auto (bool) – Whether or not this action is the result of automated analysis

Returns:

The created ExternalLocation

Return type:

ExternalLocation

add_function(addr: int, plat: Platform | None = None, auto_discovered: bool = False, func_type: Function | None = None) Function | None[source]

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

Warning

This function is used to create auto functions, often used when writing loaders, etc. Most users will want to use create_user_function in their scripts.

Parameters:
  • addr (int) – virtual address of the function to be added

  • plat (Platform) – Platform for the function to be added

  • auto_discovered (bool) – True if function was automatically discovered, False if created by user

  • func_type (Function | None) – optional function type

Return type:

None

Example:
>>> bv.add_function(1)
>>> bv.functions
[<func: x86_64@0x1>]
add_tag(addr: int, tag_type_name: str, data: str, user: bool = True)[source]

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

This API is appropriate for generic data tags. For functions, consider using add_tag.

Parameters:
  • addr (int) – address at which to add the tag

  • tag_type_name (str) – The name of the tag type for this Tag

  • data (str) – additional data for the Tag

  • user (bool) – Whether or not a user tag

Example:
>>> bv.add_tag(here, "Crashes", "Null pointer dereference")
>>>
add_to_entry_functions(func: Function) None[source]

add_to_entry_functions adds a function to the entry_functions list.

Parameters:

func (Function) – a Function object

Return type:

None

Example:
>>> bv.entry_functions
[<func: x86@0x4014c8>, <func: x86@0x401618>]
>>> bv.add_to_entry_functions(bv.get_function_at(0x4014da))
>>> bv.entry_functions
[<func: x86@0x4014c8>, <func: x86@0x401618>, <func: x86@0x4014da>]
add_type_library(lib: TypeLibrary) None[source]

add_type_library make the contents of a type library available for type/import resolution

Parameters:

lib (TypeLibrary) – library to register with the view

Return type:

None

add_user_data_ref(from_addr: int, to_addr: int) None[source]

add_user_data_ref adds a user-specified data cross-reference (xref) from the address from_addr to the address to_addr. If the reference already exists, no action is performed. To remove the reference, use remove_user_data_ref.

Parameters:
  • from_addr (int) – the reference’s source virtual address.

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

Return type:

None

add_user_data_tag(addr: int, tag: Tag)[source]

Deprecated since version 3.4.4146: Use add_tag instead

Parameters:
  • addr (int) –

  • tag (Tag) –

add_user_section(name: str, start: int, length: int, semantics: SectionSemantics = SectionSemantics.DefaultSectionSemantics, type: str = '', align: int = 1, entry_size: int = 1, linked_section: str = '', info_section: str = '', info_data: int = 0) None[source]

add_user_section creates a user-defined section that can help inform analysis by clarifying what types of data exist in what ranges. Note that all data specified must already be mapped by an existing segment.

Parameters:
  • name (str) – name of the section

  • start (int) – virtual address of the start of the section

  • length (int) – length of the section

  • semantics (SectionSemantics) – SectionSemantics of the section

  • type (str) – optional type

  • align (int) – optional byte alignment

  • entry_size (int) – optional entry size

  • linked_section (str) – optional name of a linked section

  • info_section (str) – optional name of an associated informational section

  • info_data (int) – optional info data

Return type:

None

add_user_segment(start: int, length: int, data_offset: int, data_length: int, flags: SegmentFlag) None[source]

add_user_segment creates a user-defined segment that specifies how data from the raw file is mapped into a virtual address space.

Parameters:
  • start (int) – virtual address of the start of the segment

  • length (int) – length of the segment (may be larger than the source data)

  • data_offset (int) – offset from the parent view

  • data_length (int) – length of the data from the parent view

  • flags (SegmentFlag) – SegmentFlags

Return type:

None

always_branch(addr: int, arch: Architecture | None = None) bool[source]

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

Note

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

Parameters:
  • addr (int) – virtual address of the instruction to be modified

  • arch (Architecture) – (optional) the architecture of the instructions if different from the default

Returns:

True on success, False on failure.

Return type:

bool

Example:
>>> bv.get_disassembly(0x100012ef)
'jg      0x100012f5'
>>> bv.always_branch(0x100012ef)
True
>>> bv.get_disassembly(0x100012ef)
'jmp     0x100012f5'
>>>
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

attach_type_archive(archive: TypeArchive)[source]

Attach a given type archive to the analysis and try to connect to it. If attaching was successful, names from that archive will become available to pull, but no types will actually be associated by calling this.

Parameters:

archive (TypeArchive) – New archive

attach_type_archive_by_id(id: str, path: str) TypeArchive | None[source]

Attach a type archive to the owned analysis and try to connect to it. If attaching was successful, names from that archive will become available to pull, but no types will actually be associated by calling this.

The behavior of this function is rather complicated, in an attempt to enable the ability to have attached, but disconnected Type Archives.

Normal operation:

If there was no previously connected Type Archive whose id matches id, and the file at path contains a Type Archive whose id matches id, it will be attached and connected.

Edge-cases:

If there was a previously connected Type Archive whose id matches id, nothing will happen, and it will simply be returned. If the file at path does not exist, nothing will happen and None will be returned. If the file at path exists but does not contain a Type Archive whose id matches id, nothing will happen and None will be returned. If there was a previously attached but disconnected Type Archive whose id matches id, and the file at path contains a Type Archive whose id matches id, the previously attached Type Archive will have its saved path updated to point to path. The Type Archive at path will be connected and returned.

Parameters:
  • id (str) – Id of Type Archive to attach

  • path (str) – Path to file of Type Archive to attach

Returns:

Attached archive object, if it could be connected.

Return type:

TypeArchive | None

begin_undo_actions(anonymous_allowed: bool = True) str[source]

begin_undo_actions starts recording actions taken so they can be undone at some point.

Parameters:

anonymous_allowed (bool) – Legacy interop: prevent empty calls to commit_undo_actions` from affecting this undo state. Specifically for undoable_transaction`

Returns:

Id of undo state, for passing to commit_undo_actions` or revert_undo_actions.

Return type:

str

Example:
>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> state = bv.begin_undo_actions()
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.commit_undo_actions(state)
>>> 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: Architecture | None = 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:

bool

Example:
>>> bv.can_assemble()
True
>>>
Parameters:

arch (Architecture | None) –

check_for_string_annotation_type(addr: int, allow_short_strings: bool = False, allow_large_strings: bool = False, child_width: int = 0) Tuple[str, StringType] | None[source]

Check for string annotation at a given address. This returns the string (and type of the string) as annotated in the UI at a given address. If there’s no annotation, this function returns None.

Parameters:
  • addr (int) – address at which to check for string annotation

  • allow_short_strings (bool) – Allow string shorter than the analysis.limits.minStringLength setting

  • allow_large_strings (bool) – Allow strings longer than the rendering.strings.maxAnnotationLength setting (up to analysis.limits.maxStringLength)

  • child_width (int) – What width of strings to look for, 1 for ASCII/UTF8, 2 for UTF16, 4 for UTF32, 0 to check for all

Return type:

None

commit_undo_actions(id: str | None = None) None[source]

commit_undo_actions commits the actions taken since a call to begin_undo_actions Pass as id the value returned by begin_undo_actions. Empty values of id will commit all changes since the last call to begin_undo_actions.

Parameters:

id (Optional[str]) – id of undo state, from begin_undo_actions

Return type:

None

Example:
>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> state = bv.begin_undo_actions()
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.commit_undo_actions(state)
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>>
convert_to_nop(addr: int, arch: Architecture | None = 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:

bool

Example:
>>> bv.get_disassembly(0x100012fb)
'call    0x10001629'
>>> bv.convert_to_nop(0x100012fb)
True
>>> #The above 'call' instruction is 5 bytes, a nop in x86 is 1 byte,
>>> # thus 5 nops are used:
>>> bv.get_disassembly(0x100012fb)
'nop'
>>> bv.get_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]

Deprecated since version 3.4.4146: Use add_tag instead

Parameters:
Return type:

Tag

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

Deprecated since version 3.4.4146: Use add_tag instead.

Parameters:
Return type:

Tag

create_component(name: str | None = None, parent: Component | str | None = 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 (str | None) – Optional name to create the component with

  • parent (Component | str | None) – Optional parent to which the component will be added

Returns:

The created component

Return type:

Component

create_database(filename: str, progress_func: Callable[[int, int], bool] | None = None, settings: SaveSettings | None = 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:

bool

Warning

The calling thread must not hold a lock on the BinaryView instance as this action is run on the main thread which requires the lock.

Example:
>>> settings = SaveSettings()
>>> bv.create_database(f"{bv.file.filename}.bndb", None, settings)
True
Parameters:
Return type:

bool

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:
Return type:

Type

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

Deprecated since version 3.4.4146: Use add_tag instead.

Parameters:
Return type:

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:
>>> bv.create_tag_type("Crabby Functions", "🦀")
>>>
create_user_data_tag(addr: int, type: TagType, data: str, unique: bool = False) Tag[source]

Deprecated since version 3.4.4146: Use add_tag instead

Parameters:
Return type:

Tag

create_user_function(addr: int, plat: Platform | None = None) Function | None[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: x86_64@0x1>]
create_user_tag(type: TagType, data: str) Tag[source]

Deprecated since version 3.4.4146: Use add_tag instead.

Parameters:
Return type:

Tag

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: Platform | None = None) CoreSymbol | None[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 (Platform | None) – Platform (optional)

Return type:

Optional[CoreSymbol]

define_data_var(addr: int, var_type: str | Type | TypeBuilder, name: str | CoreSymbol | None = 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 (str | CoreSymbol | None) – 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: Type | None = 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 (Type | None) – Optional type for the function

Return type:

None

define_type(type_id: str, default_name: _types.QualifiedNameType | None, type_obj: 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_types(types: List[Tuple[str, _types.QualifiedNameType | None, str | _types.Type | _types.TypeBuilder]], progress_func: Callable[[int, int], bool] | None) Mapping[str, _types.QualifiedName][source]

define_types registers multiple types as though calling define_type multiple times. The difference with this plural version is that it is optimized for adding many types at the same time, using knowledge of all types at add-time to improve runtime. There is an optional progress_func callback function in case you want updates for a long-running call.

Warning

This method should only be used for automatically generated types, see define_user_types for interactive plugin uses.

The return values of this function provide a map of each type id and which name was chosen for that type (which may be different from the requested name).

Parameters:
  • types (List[Tuple[str, _types.QualifiedNameType | None, str | _types.Type | _types.TypeBuilder]]) – List of type ids/names/definitions for the new types. Check define_type for more details.

  • progress – Function to call for progress updates

  • progress_func (Callable[[int, int], bool] | None) –

Returns:

A map of all the chosen names for the defined types with their ids.

Return type:

Mapping[str, _types.QualifiedName]

define_user_data_var(addr: int, var_type: str | Type | TypeBuilder, name: str | CoreSymbol | None = None) DataVariable | None[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 (str | CoreSymbol | None) – 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: _types.QualifiedNameType | None, type_obj: 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>
define_user_types(types: List[Tuple[_types.QualifiedNameType | None, str | _types.Type | _types.TypeBuilder]], progress_func: Callable[[int, int], bool] | None)[source]

define_user_types registers multiple types as though calling define_user_type multiple times. The difference with this plural version is that it is optimized for adding many types at the same time, using knowledge of all types at add-time to improve runtime. There is an optional progress_func callback function in case you want updates for a long-running call.

Parameters:
  • types (List[Tuple[_types.QualifiedNameType | None, str | _types.Type | _types.TypeBuilder]]) – List of type names/definitions for the new types. Check define_user_type for more details.

  • progress – Function to call for progress updates

  • progress_func (Callable[[int, int], bool] | None) –

detach_type_archive(archive: TypeArchive)[source]

Detach from a type archive, breaking all associations to types within the archive

Parameters:

archive (TypeArchive) – Type archive to detach

detach_type_archive_by_id(id: str)[source]

Detach from a type archive, breaking all associations to types within the archive

Parameters:

id (str) – Id of archive to detach

disassembly_text(addr: int, arch: Architecture | None = 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: Architecture | None = None) Generator[Tuple[List[InstructionTextToken], int], None, None][source]
Parameters:
Return type:

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

disassociate_type_archive_type(type: _types.QualifiedNameType) bool[source]

Disassociate an associated type, so that it will no longer receive updates from its connected type archive

Parameters:

type (_types.QualifiedNameType) – Name of type in analysis

Returns:

True if successful

Return type:

bool

disassociate_type_archive_type_by_id(type_id: str) bool[source]

Disassociate an associated type id, so that it will no longer receive updates from its connected type archive

Parameters:

type_id (str) – Id of type in analysis

Returns:

True if successful

Return type:

bool

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:

int

export_object_to_library(lib: TypeLibrary, name: str | None, type_obj: 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:
Return type:

None

export_type_to_library(lib: TypeLibrary, name: str | None, type_obj: 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:
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: DisassemblySettings | None = None, graph_type: FunctionGraphType = FunctionGraphType.NormalFunctionGraph, progress_func: Callable[[int, int], bool] | None = None, match_callback: Callable[[int, LinearDisassemblyLine], bool] | None = 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.

Note

A constant is considered used if a line in the linear view expansion of the given function graph type contains a token with a value that matches that constant. This does not search for raw bytes/data in the binary, for that you want to use find_all_data.

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

A generator object that will yield all the found results

find_all_data(start: int, end: int, data: bytes, flags: FindFlag = FindFlag.FindCaseSensitive, progress_func: Callable[[int, int], bool] | None = None, match_callback: Callable[[int, DataBuffer], bool] | None = 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 QueueGenerator:

A generator object that will yield all the found results

find_all_text(start: int, end: int, text: str, settings: DisassemblySettings | None = 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 QueueGenerator:

A generator object that will yield all the found results

find_next_constant(start: int, constant: int, settings: DisassemblySettings | None = None, graph_type: FunctionGraphType = FunctionGraphType.NormalFunctionGraph) int | None[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:

int | None

find_next_data(start: int, data: bytes, flags: FindFlag = FindFlag.FindCaseSensitive) int | None[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:

int | None

find_next_text(start: int, text: str, settings: DisassemblySettings | None = None, flags: FindFlag = FindFlag.FindCaseSensitive, graph_type: FunctionGraphType = FunctionGraphType.NormalFunctionGraph) int | None[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:

int | None

get_address_for_data_offset(offset: int) int | None[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: int | None = None) int | None[source]

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

Parameters:
  • prompt (str) – Prompt for the dialog

  • title (str) – Window title, if used in the UI

  • current_address (int | None) – Optional current address, for relative inputs

Returns:

The value entered by the user, if one was entered

Return type:

int | None

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: int | None = None, require_cstring: bool = True) StringReference | None[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_associated_type_archive_type_source(archive: TypeArchive, archive_type: _types.QualifiedNameType) _types.QualifiedName | None[source]

Determine the local source type name for a given archive type

Parameters:
  • archive (TypeArchive) – Target type archive

  • archive_type (_types.QualifiedNameType) – Name of target archive type

Returns:

Name of source analysis type, if this type is associated. None otherwise.

Return type:

_types.QualifiedName | None

get_associated_type_archive_type_source_by_id(archive_id: str, archive_type_id: str) str | None[source]

Determine the local source type id for a given archive type

Parameters:
  • archive_id (str) – Id of target type archive

  • archive_type_id (str) – Id of target archive type

Returns:

Id of source analysis type, if this type is associated. None otherwise.

Return type:

str | None

get_associated_type_archive_type_target(name: _types.QualifiedNameType) Tuple[TypeArchive | None, str] | None[source]

Determine the target archive / type id of a given analysis type

Parameters:

name (_types.QualifiedNameType) – Analysis type

Returns:

(archive, archive type id) if the type is associated. None otherwise.

Return type:

Tuple[TypeArchive | None, str] | None

get_associated_type_archive_type_target_by_id(type_id: str) Tuple[str, str] | None[source]

Determine the target archive / type id of a given analysis type

Parameters:

type_id (str) – Analysis type id

Returns:

(archive id, archive type id) if the type is associated. None otherwise.

Return type:

Tuple[str, str] | None

get_associated_types_from_archive(archive: TypeArchive) Mapping[QualifiedName, str][source]

Get a list of all types in the analysis that are associated with a specific type archive

Returns:

Map of all analysis types to their corresponding archive id

Parameters:

archive (TypeArchive) –

Return type:

Mapping[QualifiedName, str]

get_associated_types_from_archive_by_id(archive_id: str) Mapping[str, str][source]

Get a list of all types in the analysis that are associated with a specific type archive :return: Map of all analysis types to their corresponding archive id

Parameters:

archive_id (str) –

Return type:

Mapping[str, str]

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

Deprecated since version 3.4.4146: Use get_tags_at instead.

Parameters:

addr (int) –

Return type:

List[Tag]

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

Deprecated since version 3.4.4146: Use get_tags_in_range instead.

Parameters:

address_range (AddressRange) –

Return type:

List[Tuple[int, Tag]]

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

Deprecated since version 3.4.4146: Use get_tags_at instead.

Parameters:
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: Function | None = None, arch: Architecture | None = 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 (Architecture | None) –

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:

list(ReferenceSource)

Example:
>>> bv.get_callers(here)
[<ref: x86@0x4165ff>]
>>>
get_code_refs(addr: int, length: int | None = 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_code_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: x86@0x4165ff>]
>>>
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: x86@0x4165ff>]
>>>
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: x86@0x4165ff>]
>>>
get_code_refs_for_type_fields_from(addr: int, func: Function | None = None, arch: Architecture | None = None, length: int | None = 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 (Function | None) –

  • arch (Architecture | None) –

Returns:

list of references

Return type:

list(TypeReferenceSource)

get_code_refs_for_type_from(addr: int, func: Function | None = None, arch: Architecture | None = None, length: int | None = 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 (Function | None) –

  • arch (Architecture | None) –

Returns:

list of references

Return type:

list(TypeReferenceSource)

get_code_refs_from(addr: int, func: Function | None = None, arch: Architecture | None = None, length: int | None = 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 (Function | None) –

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) Component | None[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:

Component | None

get_component_by_path(path: str) Component | None[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:

Component | None

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:

Component | None

get_data_offset_for_address(address: int) int | None[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: int | None = 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). Also, note there exists get_data_refs_from.

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: int | None = 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. Also, note there exists get_data_refs.

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_refs_from_for_type_field(name: _types.QualifiedNameType, offset: int) List[int][source]

get_data_refs_from_for_type_field returns a list of virtual addresses of data which are referenced by the type name.

Only data referenced by structures with the __data_var_refs attribute are included.

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_from_for_type_field('A', 0x8)
[4203812]
>>>
get_data_tags_at(addr: int, auto: bool | None = None) List[Tag][source]

Deprecated since version 3.4.4146: Use get_tags_at instead.

Parameters:
  • addr (int) –

  • auto (bool | None) –

Return type:

List[Tag]

get_data_tags_in_range(address_range: AddressRange, user: bool | None = None) List[Tuple[int, Tag]][source]

Deprecated since version 3.4.4146: Use get_tags_in_range instead.

Parameters:
Return type:

List[Tuple[int, Tag]]

get_data_tags_of_type(addr: int, tag_type: str, auto: bool | None = None) List[Tag][source]

Deprecated since version 3.4.4146: Use get_tags_at instead.

Parameters:
  • addr (int) –

  • tag_type (str) –

  • auto (bool | None) –

Return type:

List[Tag]

get_data_var_at(addr: int) DataVariable | None[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_data_variable_parent_components(data_variable: DataVariable) List[Component][source]
Parameters:

data_variable (DataVariable) –

Return type:

List[Component]

get_disassembly(addr: int, arch: Architecture | None = None) str | None[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) int | None[source]

Get the value of an expression parser magic value

If the queried magic value exists, the function returns true and the magic value is returned in value. If the queried magic value does not exist, the function returns None.

Parameters:

name (str) – name for the magic value to query

Returns:

Return type:

int | None

get_external_libraries() List[ExternalLibrary][source]

Get a list of all ExternalLibrary in this BinaryView

Returns:

A list of ExternalLibraries in this BinaryView

Return type:

List[ExternalLibrary]

get_external_library(name: str) ExternalLibrary | None[source]

Get an ExternalLibrary in this BinaryView by name

Parameters:

name (str) – Name of the external library

Returns:

An ExternalLibrary with the given name, or None

Return type:

ExternalLibrary | None

get_external_location(source_symbol: CoreSymbol) ExternalLocation | None[source]

Get the ExternalLocation with the given source symbol in this BinaryView

Parameters:

source_symbol (CoreSymbol) – The source symbol of the ExternalLocation

Returns:

An ExternalLocation with the given source symbol, or None

Return type:

ExternalLocation | None

get_external_locations() List[ExternalLocation][source]

Get a list of ExternalLocations in this BinaryView

Returns:

A list of ExternalLocations in this BinaryView

Return type:

List[ExternalLocation]

get_function_at(addr: int, plat: Platform | None = None) Function | None[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: x86_64@0x100001174>
>>>
get_function_parent_components(function: Function) List[Component][source]
Parameters:

function (Function) –

Return type:

List[Component]

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: Platform | None = None, ordered_filter: List[SymbolType] | None = 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: x86_64@0x1587>]
>>>
get_functions_containing(addr: int, plat: Platform | None = 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 (Platform | None) –

Return type:

list of Function objects

get_incoming_direct_type_references(name: _types.QualifiedNameType) List[_types.QualifiedName][source]
Parameters:

name (_types.QualifiedNameType) –

Return type:

List[_types.QualifiedName]

get_incoming_recursive_type_references(names: _types.QualifiedNameType | List[_types.QualifiedNameType]) List[_types.QualifiedName][source]
Parameters:

names (_types.QualifiedNameType | List[_types.QualifiedNameType]) –

Return type:

List[_types.QualifiedName]

get_instruction_length(addr: int, arch: Architecture | None = 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:

int

Example:
>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> bv.get_instruction_length(0x100012f1)
2L
>>>
get_linear_disassembly(settings: DisassemblySettings | None = 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: DisassemblySettings | None = 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:
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) Settings | None[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: int | None = 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:

int

Example:
>>> hex(bv.get_next_basic_block_start_after(bv.entry_point))
'0x100014a8L'
>>> hex(bv.get_next_basic_block_start_after(0x100014a8))
'0x100014adL'
>>>
get_next_data_after(addr: 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:

int

Example:
>>> hex(bv.get_next_data_after(0x10000000))
'0x10000001L'
get_next_data_var_after(addr: int) DataVariable | None[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:

int

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:

int

Example:
>>> bv.get_next_function_start_after(bv.entry_point)
268441061L
>>> hex(bv.get_next_function_start_after(bv.entry_point))
'0x100015e5L'
>>> hex(bv.get_next_function_start_after(0x100015e5))
'0x10001629L'
>>> hex(bv.get_next_function_start_after(0x10001629))
'0x1000165eL'
>>>
get_next_linear_disassembly_lines(pos: 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:

List[LinearDisassemblyLine]

get_next_valid_offset(addr: int) int[source]

get_next_valid_offset returns the next valid offset in the BinaryView starting from the given virtual address addr.

Parameters:

addr (int) – a virtual address to start checking from.

Returns:

The minimum of the next valid offset in the BinaryView and the end address of the BinaryView

Return type:

int

get_outgoing_direct_type_references(name: _types.QualifiedNameType) List[_types.QualifiedName][source]
Parameters:

name (_types.QualifiedNameType) –

Return type:

List[_types.QualifiedName]

get_outgoing_recursive_type_references(names: _types.QualifiedNameType | List[_types.QualifiedNameType]) List[_types.QualifiedName][source]
Parameters:

names (_types.QualifiedNameType | List[_types.QualifiedNameType]) –

Return type:

List[_types.QualifiedName]

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:

int

Example:
>>> hex(bv.entry_point)
'0x1000149fL'
>>> hex(bv.get_next_basic_block_start_after(bv.entry_point))
'0x100014a8L'
>>> hex(bv.get_previous_basic_block_end_before(0x100014a8))
'0x100014a8L'
get_previous_basic_block_start_before(addr: 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:

int

Example:
>>> hex(bv.entry_point)
'0x1000149fL'
>>> hex(bv.get_next_basic_block_start_after(bv.entry_point))
'0x100014a8L'
>>> hex(bv.get_previous_basic_block_start_before(0x100014a8))
'0x1000149fL'
>>>
get_previous_data_before(addr: 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:

int

Example:
>>> hex(bv.get_previous_data_before(0x1000001))
'0x1000000L'
>>>
get_previous_data_var_before(addr: int) DataVariable | None[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:

int

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:

int

Example:
>>> hex(bv.entry_point)
'0x1000149fL'
>>> hex(bv.get_next_function_start_after(bv.entry_point))
'0x100015e5L'
>>> hex(bv.get_previous_function_start_before(0x100015e5))
'0x1000149fL'
>>>
get_previous_linear_disassembly_lines(pos: 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:

List[LinearDisassemblyLine]

get_recent_basic_block_at(addr: int) BasicBlock | None[source]
Parameters:

addr (int) –

Return type:

BasicBlock | None

get_recent_function_at(addr: int) Function | None[source]
Parameters:

addr (int) –

Return type:

Function | None

get_section_by_name(name: str) Section | None[source]
Parameters:

name (str) –

Return type:

Section | None

get_sections_at(addr: int) List[Section][source]
Parameters:

addr (int) –

Return type:

List[Section]

get_segment_at(addr: int) Segment | None[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:

Segment | None

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) StringReference | None[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: int | None = None, length: int | None = 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) _types.CoreSymbol | None[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) _types.CoreSymbol | None[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('?testf@Foobar@@SA?AW4foo@1@W421@@Z')
<FunctionSymbol: "public: static enum Foobar::foo __cdecl Foobar::testf(enum Foobar::foo)" @ 0x10001100>
>>>
get_symbols(start: int | None = None, length: int | None = 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 (int | None) – optional start virtual address

  • length (int | None) – 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: List[SymbolType] | None = 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 (List[SymbolType] | None) – (optional) an ordered filter based on SymbolType

Returns:

Symbol object corresponding to the provided name

Return type:

Symbol

Example:
>>> bv.get_symbols_by_name('?testf@Foobar@@SA?AW4foo@1@W421@@Z')
[<FunctionSymbol: "public: static enum Foobar::foo __cdecl Foobar::testf(enum Foobar::foo)" @ 0x10001100>]
>>>
get_symbols_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: int | None = None, length: int | None = 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 (int | None) – optional start virtual address

  • length (int | None) – 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) Tag | None[source]

Deprecated since version 3.4.4146.

Parameters:

id (str) –

Return type:

Tag | None

get_tag_type(name: str) TagType | None[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_tag_type_by_id(id: str) TagType | None[source]

Deprecated since version 3.4.4146: Use get_tag_type instead.

Parameters:

id (str) –

Return type:

TagType | None

get_tag_type_by_name(name: str) TagType | None[source]

Deprecated since version 3.4.4146: Use get_tag_type instead.

Parameters:

name (str) –

Return type:

TagType | None

get_tags(auto: bool | None = None) List[Tuple[int, Tag]][source]

tags gets a list of all data Tag objects in the view. Tags are returned as a list of (address, Tag) pairs.

Return type:

list(int, Tag)

Parameters:

auto (bool | None) –

get_tags_at(addr: int, auto: bool | None = None) List[Tag][source]

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

Parameters:
  • addr (int) – address to get tags at

  • auto (bool) – If None, gets all tags, if True, gets auto tags, if False, gets user tags

Returns:

A list of data Tag objects

Return type:

list(Tag)

get_tags_in_range(address_range: AddressRange, auto: bool | None = None) 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

  • auto (bool) – If None, gets all tags, if True, gets auto tags, if False, gets auto tags

Returns:

A list of (address, data tag) tuples

Return type:

list((int, Tag))

get_type_archive(id: str) TypeArchive | None[source]

Look up a connected archive by its id

Parameters:

id (str) – Id of archive

Returns:

Archive, if one exists with that id. Otherwise None

Return type:

TypeArchive | None

get_type_archive_path(id: str) str | None[source]

Look up the path for an attached (but not necessarily connected) type archive by its id

Parameters:

id (str) – Id of archive

Returns:

Archive path, if it is attached. Otherwise None.

Return type:

str | None

get_type_archives_for_type_name(name: _types.QualifiedNameType) List[Tuple[TypeArchive, str]][source]

Get a list of all connected type archives that have a given type name

Returns:

(archive, archive type id) for all archives

Parameters:

name (_types.QualifiedNameType) –

Return type:

List[Tuple[TypeArchive, str]]

get_type_by_id(id: str) Type | None[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) _types.Type | None[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) TypeLibrary | None[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) QualifiedName | None[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:

list(TypeReferenceSource)

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:

list(TypeReferenceSource)

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]

Deprecated since version 3.4.4146: Use get_tags_at instead.

Parameters:

addr (int) –

Return type:

List[Tag]

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

Deprecated since version 3.4.4146: Use get_tags_in_range instead.

Parameters:

address_range (AddressRange) –

Return type:

List[Tuple[int, Tag]]

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

Deprecated since version 3.4.4146: Use get_tags_at instead.

Parameters:
Return type:

List[Tag]

get_view_of_type(name: str) BinaryView | None[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: int | None = None, function_generator: Generator[Function, None, 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:
Return type:

Generator[HighLevelILFunction, None, None]

import_library_object(name: str, lib: TypeLibrary | None = None) Tuple[TypeLibrary, Type] | None[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:
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: TypeLibrary | None = None) Type | None[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:
Returns:

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

Return type:

Type

import_type_by_guid(guid: str | UUID) Type | None[source]

import_type_by_guid recursively imports a type interface given its GUID.

Note

To support this type of lookup a type library must have contain a metadata key called “type_guids” which is a map Dict[string_guid, string_type_name] or Dict[string_guid, Tuple[string_type_name, type_library_name]]

Parameters:

guid (str) – GUID of the COM interface to import

Returns:

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

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:

int

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

bool

Example:
>>> bv.get_disassembly(0x1000130e)
'je      0x10001317'
>>> bv.invert_branch(0x1000130e)
True
>>>
>>> bv.get_disassembly(0x1000130e)
'jne     0x10001317'
>>>
is_always_branch_patch_available(addr: int, arch: Architecture | None = 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:

bool

Example:
>>> bv.get_disassembly(0x100012ed)
'test    eax, eax'
>>> bv.is_always_branch_patch_available(0x100012ed)
False
>>> bv.get_disassembly(0x100012ef)
'jg      0x100012f5'
>>> bv.is_always_branch_patch_available(0x100012ef)
True
>>>
is_invert_branch_patch_available(addr: int, arch: Architecture | None = 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:

bool

Example:
>>> bv.get_disassembly(0x100012ed)
'test    eax, eax'
>>> bv.is_invert_branch_patch_available(0x100012ed)
False
>>> bv.get_disassembly(0x100012ef)
'jg      0x100012f5'
>>> bv.is_invert_branch_patch_available(0x100012ef)
True
>>>
is_never_branch_patch_available(addr: int, arch: Architecture | None = 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:

bool

Example:
>>> bv.get_disassembly(0x100012ed)
'test    eax, eax'
>>> bv.is_never_branch_patch_available(0x100012ed)
False
>>> bv.get_disassembly(0x100012ef)
'jg      0x100012f5'
>>> bv.is_never_branch_patch_available(0x100012ef)
True
>>>
is_offset_code_semantics(addr: 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: Architecture | None = 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:

bool

Example:
>>> bv.get_disassembly(0x100012f6)
'mov     dword [0x10003020], eax'
>>> bv.is_skip_and_return_value_patch_available(0x100012f6)
False
>>> bv.get_disassembly(0x100012fb)
'call    0x10001629'
>>> bv.is_skip_and_return_value_patch_available(0x100012fb)
True
>>>
is_skip_and_return_zero_patch_available(addr: int, arch: Architecture | None = 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:

bool

Example:
>>> bv.get_disassembly(0x100012f6)
'mov     dword [0x10003020], eax'
>>> bv.is_skip_and_return_zero_patch_available(0x100012f6)
False
>>> bv.get_disassembly(0x100012fb)
'call    0x10001629'
>>> bv.is_skip_and_return_zero_patch_available(0x100012fb)
True
>>>
is_type_auto_defined(name: _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:

bool

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

static load(source: str | bytes | bytearray | DataBuffer | PathLike | BinaryView | ProjectFile, update_analysis: bool | None = True, progress_func: Callable[[int, int], bool] | None = None, options: Mapping[str, Any] = {}) BinaryView | None[source]

load opens, generates default load options (which are overridable), and returns the first available BinaryView. If no BinaryViewType is available, then a Mapped BinaryViewType is used to load the BinaryView with the specified load options. The Mapped view type attempts to auto-detect the architecture of the file during initialization. If no architecture is detected or specified in the load options, then the Mapped view type fails to initialize and returns None.

Note

Although general container file support is not complete, support for Universal archives exists. It’s possible to control the architecture preference with the ‘files.universal.architecturePreference’ setting. This setting is scoped to SettingsUserScope and can be modified as follows

>>> Settings().set_string_list("files.universal.architecturePreference", ["arm64"])

It’s also possible to override the ‘files.universal.architecturePreference’ user setting by specifying it directly with load. This specific usage of this setting is experimental and may change in the future

>>> bv = binaryninja.load('/bin/ls', options={'files.universal.architecturePreference': ['arm64']})

Warning

The recommended code pattern for opening a BinaryView is to use the load API as a context manager like with load('/bin/ls') as bv: which will automatically clean up when done with the view. If using this API directly you will need to call bv.file.close() before the BinaryView leaves scope to ensure the reference is properly removed and prevents memory leaks.

Parameters:
Returns:

returns a BinaryView object for the given filename or None

Return type:

BinaryView or None

Example:
>>> binaryninja.load('/bin/ls', options={'loader.imageBase': 0xfffffff0000, 'loader.macho.processFunctionStarts' : False})
<BinaryView: '/bin/ls', start 0xfffffff0000, len 0xa290>
>>>
lookup_imported_object_library(addr: int, platform: Platform | None = None) Tuple[TypeLibrary, QualifiedName] | None[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 (Platform | None) – Platform of symbol at import site

Returns:

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

Return type:

Tuple[TypeLibrary, QualifiedName]

lookup_imported_type_library(name: _types.QualifiedNameType) Tuple[TypeLibrary, _types.QualifiedName] | None[source]

lookup_imported_type_library gives you details of from which type library and name a given type in the analysis was imported.

Parameters:

name (_types.QualifiedNameType) – Name of type in analysis

Returns:

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

Return type:

Optional[Tuple[TypeLibrary, QualifiedName]]

lookup_imported_type_platform(name: _types.QualifiedNameType) Tuple[_platform.Platform, _types.QualifiedName] | None[source]

lookup_imported_type_platform gives you details of from which platform and name a given type in the analysis was imported.

Parameters:

name (_types.QualifiedNameType) – Name of type in analysis

Returns:

A tuple of [Platform, QualifiedName] with the platform and name used, or None if it was not imported

Return type:

Optional[Tuple[Platform, QualifiedName]]

mlil_functions(preload_limit: int | None = None, function_generator: Generator[Function, None, 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:
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:

bool

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

bool

Example:
>>> bv.get_disassembly(0x1000130e)
'jne     0x10001317'
>>> bv.never_branch(0x1000130e)
True
>>> bv.get_disassembly(0x1000130e)
'nop'
>>>
static new(data: bytes | bytearray | DataBuffer | None = None, file_metadata: FileMetadata | None = None) BinaryView | None[source]

new creates a new, Raw BinaryView for the provided data.

Parameters:
Returns:

returns a BinaryView object for the given filename or None

Return type:

BinaryView or None

Example:
>>> binaryninja.load('/bin/ls', options={'loader.imageBase': 0xfffffff0000, 'loader.macho.processFunctionStarts' : False})
<BinaryView: '/bin/ls', start 0xfffffff0000, len 0xa290>
>>>
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) BinaryView | None[source]
Return type:

BinaryView | None

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: +, -, \*, /, %, (), &, \|, ^, ~, ==, !=, >, <, >=, <=

    • Comparision operators return 1 if the condition is true, 0 otherwise.

  • 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

  • Arbitrary magic values (name-value-pairs) can be added to the expression parser via the add_expression_parser_magic_value API. Notably, the debugger adds all register values into the expression parser so they can be used directly when navigating. The register values can be referenced like $rbp, $x0, etc. For more details, refer to the related debugger docs.

Parameters:
  • expression (str) – Arithmetic expression to be evaluated

  • here (int) – (optional) Base address for relative expressions, defaults to zero

Return type:

int

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