binaryview module¶
The purpose of this class is to generate IL functions IL function in the background improving the performance of iterating MediumLevelIL and HighLevelILFunctions. |
|
The |
|
|
|
|
|
|
|
The |
|
The |
|
|
|
|
|
|
|
|
Dictionary that remembers insertion order |
|
The |
|
The |
Warning This object is deprecated. Please migrate code away from using this class or method. |
|
Warning This object is deprecated. Please migrate code away from using this class or method. |
|
SymbolMapping object is used to improve performance of the bv.symbols API. |
|
|
The |
|
The |
|
TypeMapping object is used to improve performance of the bv.types API. |
alias of |
|
|
defaultdict(default_factory=None, /, [...]) --> dict with default factory |
|
deque([iterable[, maxlen]]) --> deque object |
- class ActiveAnalysisInfo(func: '_function.Function', analysis_time: int, update_count: int, submit_count: int)[source]¶
Bases:
object
- class AdvancedILFunctionList(view: BinaryView, preload_limit: int = 5, functions: Optional[Iterable] = 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
view (BinaryView) –
preload_limit (int) –
- class AnalysisCompletionEvent(view: BinaryView, callback: Union[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
view (BinaryView) –
callback (Union[Callable[[AnalysisCompletionEvent], None], Callable[[], None]]) –
- cancel() None [source]¶
The
cancel
method will cancel analysis for anAnalysisCompletionEvent
.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
state (AnalysisState) –
analysis_time (int) –
active_info (List[ActiveAnalysisInfo]) –
- active_info: List[ActiveAnalysisInfo]¶
- state: AnalysisState¶
- class AnalysisProgress(state: AnalysisState, count: int, total: int)[source]¶
Bases:
object
- Parameters
state (AnalysisState) –
count (int) –
total (int) –
- state: AnalysisState¶
- class BinaryDataNotification[source]¶
Bases:
object
- component_added(view: BinaryView, _component: Component) None [source]¶
- Parameters
view (BinaryView) –
_component (Component) –
- Return type
None
- component_function_added(view: BinaryView, _component: Component, func: Function)[source]¶
- Parameters
view (BinaryView) –
_component (Component) –
func (Function) –
- component_function_removed(view: BinaryView, _component: Component, func: Function)[source]¶
- Parameters
view (BinaryView) –
_component (Component) –
func (Function) –
- component_moved(view: BinaryView, formerParent: Component, newParent: Component, _component: Component) None [source]¶
- Parameters
view (BinaryView) –
formerParent (Component) –
newParent (Component) –
_component (Component) –
- Return type
None
- component_name_updated(view: BinaryView, previous_name: str, _component: Component) None [source]¶
- Parameters
view (BinaryView) –
previous_name (str) –
_component (Component) –
- Return type
None
- component_removed(view: BinaryView, formerParent: Component, _component: Component) None [source]¶
- Parameters
view (BinaryView) –
formerParent (Component) –
_component (Component) –
- Return type
None
- data_inserted(view: BinaryView, offset: int, length: int) None [source]¶
- Parameters
view (BinaryView) –
offset (int) –
length (int) –
- Return type
None
- data_metadata_updated(view: BinaryView, offset: int) None [source]¶
- Parameters
view (BinaryView) –
offset (int) –
- Return type
None
- data_removed(view: BinaryView, offset: int, length: int) None [source]¶
- Parameters
view (BinaryView) –
offset (int) –
length (int) –
- Return type
None
- data_var_added(view: BinaryView, var: DataVariable) None [source]¶
- Parameters
view (BinaryView) –
var (DataVariable) –
- Return type
None
- data_var_removed(view: BinaryView, var: DataVariable) None [source]¶
- Parameters
view (BinaryView) –
var (DataVariable) –
- Return type
None
- data_var_updated(view: BinaryView, var: DataVariable) None [source]¶
- Parameters
view (BinaryView) –
var (DataVariable) –
- Return type
None
- data_written(view: BinaryView, offset: int, length: int) None [source]¶
- Parameters
view (BinaryView) –
offset (int) –
length (int) –
- Return type
None
- function_added(view: BinaryView, func: Function) None [source]¶
- Parameters
view (BinaryView) –
func (Function) –
- Return type
None
- function_removed(view: BinaryView, func: Function) None [source]¶
- Parameters
view (BinaryView) –
func (Function) –
- Return type
None
- function_update_requested(view: BinaryView, func: Function) None [source]¶
- Parameters
view (BinaryView) –
func (Function) –
- Return type
None
- function_updated(view: BinaryView, func: Function) None [source]¶
- Parameters
view (BinaryView) –
func (Function) –
- Return type
None
- section_added(view: BinaryView, section: Section) None [source]¶
- Parameters
view (BinaryView) –
section (Section) –
- Return type
None
- section_removed(view: BinaryView, section: Section) None [source]¶
- Parameters
view (BinaryView) –
section (Section) –
- Return type
None
- section_updated(view: BinaryView, section: Section) None [source]¶
- Parameters
view (BinaryView) –
section (Section) –
- Return type
None
- segment_added(view: BinaryView, segment: Segment) None [source]¶
- Parameters
view (BinaryView) –
segment (Segment) –
- Return type
None
- segment_removed(view: BinaryView, segment: Segment) None [source]¶
- Parameters
view (BinaryView) –
segment (Segment) –
- Return type
None
- segment_updated(view: BinaryView, segment: Segment) None [source]¶
- Parameters
view (BinaryView) –
segment (Segment) –
- Return type
None
- string_found(view: BinaryView, string_type: StringType, offset: int, length: int) None [source]¶
- Parameters
view (BinaryView) –
string_type (StringType) –
offset (int) –
length (int) –
- Return type
None
- string_removed(view: BinaryView, string_type: StringType, offset: int, length: int) None [source]¶
- Parameters
view (BinaryView) –
string_type (StringType) –
offset (int) –
length (int) –
- Return type
None
- symbol_added(view: BinaryView, sym: CoreSymbol) None [source]¶
- Parameters
view (BinaryView) –
sym (CoreSymbol) –
- Return type
None
- symbol_removed(view: BinaryView, sym: CoreSymbol) None [source]¶
- Parameters
view (BinaryView) –
sym (CoreSymbol) –
- Return type
None
- symbol_updated(view: BinaryView, sym: CoreSymbol) None [source]¶
- Parameters
view (BinaryView) –
sym (CoreSymbol) –
- Return type
None
- tag_added(view: BinaryView, tag: Tag, ref_type: TagReferenceType, auto_defined: bool, arch: Optional[Architecture], func: Optional[Function], addr: int) None [source]¶
- Parameters
view (BinaryView) –
tag (Tag) –
ref_type (TagReferenceType) –
auto_defined (bool) –
arch (Optional[Architecture]) –
addr (int) –
- Return type
None
- tag_removed(view: BinaryView, tag: Tag, ref_type: TagReferenceType, auto_defined: bool, arch: Optional[Architecture], func: Optional[Function], addr: int) None [source]¶
- Parameters
view (BinaryView) –
tag (Tag) –
ref_type (TagReferenceType) –
auto_defined (bool) –
arch (Optional[Architecture]) –
addr (int) –
- 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: Optional[Architecture], func: Optional[Function], addr: int) None [source]¶
- Parameters
view (BinaryView) –
tag (Tag) –
ref_type (TagReferenceType) –
auto_defined (bool) –
arch (Optional[Architecture]) –
addr (int) –
- Return type
None
- type_defined(view: BinaryView, name: QualifiedName, type: Type) None [source]¶
- Parameters
view (BinaryView) –
name (QualifiedName) –
type (Type) –
- Return type
None
- type_field_ref_changed(view: BinaryView, name: QualifiedName, offset: int) None [source]¶
- Parameters
view (BinaryView) –
name (QualifiedName) –
offset (int) –
- Return type
None
- type_ref_changed(view: BinaryView, name: QualifiedName, type: Type) None [source]¶
- Parameters
view (BinaryView) –
name (QualifiedName) –
type (Type) –
- Return type
None
- type_undefined(view: BinaryView, name: QualifiedName, type: Type) None [source]¶
- Parameters
view (BinaryView) –
name (QualifiedName) –
type (Type) –
- Return type
None
- class BinaryDataNotificationCallbacks(view: BinaryView, notify: BinaryDataNotification)[source]¶
Bases:
object
- Parameters
view (BinaryView) –
notify (BinaryDataNotification) –
- property notify: BinaryDataNotification¶
- property view: BinaryView¶
- class BinaryReader(view: BinaryView, endian: Optional[Endianness] = None, address: Optional[int] = 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 = BinaryViewType.get_view_of_file("/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
view (BinaryView) –
endian (Optional[Endianness]) –
- read(length: int, address: Optional[int] = None) Optional[bytes] [source]¶
read
returnslength
bytes read from the current offset, addinglength
to offset.
- read16(address: Optional[int] = None) Optional[int] [source]¶
read16
returns a two byte integer from offset incrementing the offset by two, using specified endianness.
- read16be(address: Optional[int] = None) Optional[int] [source]¶
read16be
returns a two byte big endian integer from offset incrementing the offset by two.
- read16le(address: Optional[int] = None) Optional[int] [source]¶
read16le
returns a two byte little endian integer from offset incrementing the offset by two.
- read32(address: Optional[int] = None) Optional[int] [source]¶
read32
returns a four byte integer from offset incrementing the offset by four, using specified endianness.
- read32be(address: Optional[int] = None) Optional[int] [source]¶
read32be
returns a four byte big endian integer from offset incrementing the offset by four.
- read32le(address: Optional[int] = None) Optional[int] [source]¶
read32le
returns a four byte little endian integer from offset incrementing the offset by four.
- read64(address: Optional[int] = None) Optional[int] [source]¶
read64
returns an eight byte integer from offset incrementing the offset by eight, using specified endianness.
- read64be(address: Optional[int] = None) Optional[int] [source]¶
read64be
returns an eight byte big endian integer from offset incrementing the offset by eight.
- read64le(address: Optional[int] = None) Optional[int] [source]¶
read64le
returns an eight byte little endian integer from offset incrementing the offset by eight.
- read8(address: Optional[int] = None) Optional[int] [source]¶
read8
returns a one byte integer from offset incrementing the offset.
- seek(offset: int) None [source]¶
seek
update internal offset tooffset
.- Parameters
offset (int) – offset to set the internal offset to
- Return type
None
- Example
>>> hex(br.offset) '0x100000008L' >>> br.seek(0x100000000) >>> hex(br.offset) '0x100000000L' >>>
- seek_relative(offset: int) None [source]¶
seek_relative
updates the internal offset byoffset
.- 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
- class BinaryView(file_metadata: Optional[FileMetadata] = None, parent_view: Optional[BinaryView] = None, handle: Optional[LP_BNBinaryView] = 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. TheRaw
BinaryView is simply a hex editor, but is helpful for manipulating binary files via their absolute addresses.BinaryViews are plugins and thus registered with Binary Ninja at startup, and thus should never be instantiated directly as this is already done. The list of available BinaryViews can be seen in the BinaryViewType class which provides an iterator and map of the various installed BinaryViews:
>>> list(BinaryViewType) [<view type: 'Raw'>, <view type: 'ELF'>, <view type: 'Mach-O'>, <view type: 'PE'>] >>> BinaryViewType['ELF'] <view type: 'ELF'>
To open a file with a given BinaryView the following code is recommended:
>>> with open_view("/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 thanremove_function
). Thus use_user_
methods if saving to the database is desired.- Parameters
file_metadata (Optional[FileMetadata]) –
parent_view (Optional[BinaryView]) –
handle (Optional[LP_BNBinaryView]) –
- 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 usingupdate_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.
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
- 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 eitherupdate_analysis
orupdate_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) None [source]¶
add_auto_data_tag
adds an already-createdTag
object at a data address. If you want to create the tag as well, consider usingcreate_auto_data_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]¶
- add_auto_segment(start: int, length: int, data_offset: int, data_length: int, flags: SegmentFlag) None [source]¶
- Parameters
start (int) –
length (int) –
data_offset (int) –
data_length (int) –
flags (SegmentFlag) –
- Return type
None
- add_entry_point(addr: int, plat: Optional[Platform] = None) None [source]¶
add_entry_point
adds a virtual address to start analysis from for a given plat.
- add_function(addr: int, plat: Optional[Platform] = None) None [source]¶
add_function
add a new function of the givenplat
at the virtual addressaddr
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
- Return type
None
- Example
>>> bv.add_function(1) >>> bv.functions [<func: [email protected]>]
- 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 addressfrom_addr
to the addressto_addr
. If the reference already exists, no action is performed. To remove the reference, useremove_user_data_ref
.
- add_user_data_tag(addr: int, tag: Tag) None [source]¶
add_user_data_tag
adds an already-createdTag
object at a data address. Since this adds a user tag, it will be added to the current undo buffer. If you want to create the tag as well, consider usingcreate_user_data_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: Optional[Architecture] = None) bool [source]¶
always_branch
convert the instruction of architecturearch
at the virtual addressaddr
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
- Example
>>> bv.get_disassembly(0x100012ef) 'jg 0x100012f5' >>> bv.always_branch(0x100012ef) True >>> bv.get_disassembly(0x100012ef) 'jmp 0x100012f5' >>>
- apply_debug_info(value: DebugInfo) None [source]¶
Sets the debug info and applies its contents to the current binary view
- Parameters
value (DebugInfo) –
- Return type
None
- begin_undo_actions() None [source]¶
begin_undo_actions
start recording actions taken so the can be undone at some point.- Return type
None
- Example
>>> bv.get_disassembly(0x100012f1) 'xor eax, eax' >>> bv.begin_undo_actions() >>> bv.convert_to_nop(0x100012f1) True >>> bv.commit_undo_actions() >>> bv.get_disassembly(0x100012f1) 'nop' >>> bv.undo() >>> bv.get_disassembly(0x100012f1) 'xor eax, eax' >>>
- bulk_modify_symbols()[source]¶
bulk_modify_symbols
returns a context manager that improves performance when adding or removing a large number of symbols. Symbols added within the Python with keyword will defer processing until the end of the block. Many symbol getter APIs will return stale results inside the with block, so this function should only be used when symbol queries are not needed at the same time as the modifications.
- can_assemble(arch: Optional[Architecture] = None) bool [source]¶
can_assemble
queries the architecture plugin to determine if the architecture can assemble instructions.- Returns
True if the architecture can assemble, False otherwise
- Return type
- Example
>>> bv.can_assemble() True >>>
- Parameters
arch (Optional[Architecture]) –
- commit_undo_actions() None [source]¶
commit_undo_actions
commit the actions taken since the last commit to the undo database.- Return type
None
- Example
>>> bv.get_disassembly(0x100012f1) 'xor eax, eax' >>> bv.begin_undo_actions() >>> bv.convert_to_nop(0x100012f1) True >>> bv.commit_undo_actions() >>> bv.get_disassembly(0x100012f1) 'nop' >>> bv.undo() >>> bv.get_disassembly(0x100012f1) 'xor eax, eax' >>>
- convert_to_nop(addr: int, arch: Optional[Architecture] = None) bool [source]¶
convert_to_nop
converts the instruction at virtual addressaddr
to a nop of the provided architecture.Note
This API performs a binary patch, analysis may need to be updated afterward. Additionally the binary file must be saved in order to preserve the changes made.
- Parameters
addr (int) – virtual address of the instruction to convert to nops
arch (Architecture) – (optional) the architecture of the instructions if different from the default
- Returns
True on success, False on failure.
- Return type
- Example
>>> bv.get_disassembly(0x100012fb) 'call 0x10001629' >>> bv.convert_to_nop(0x100012fb) True >>> #The above 'call' instruction is 5 bytes, a nop in x86 is 1 byte, >>> # thus 5 nops are used: >>> bv.get_disassembly(0x100012fb) 'nop' >>> bv.get_disassembly(0x100012fb + 1) 'nop' >>> bv.get_disassembly(0x100012fb + 2) 'nop' >>> bv.get_disassembly(0x100012fb + 3) 'nop' >>> bv.get_disassembly(0x100012fb + 4) 'nop' >>> bv.get_disassembly(0x100012fb + 5) 'mov byte [ebp-0x1c], al'
- create_auto_data_tag(addr: int, type: TagType, data: str, unique: bool = False) Tag [source]¶
create_auto_data_tag
creates and adds aTag
object at a data address.
- create_component(name: Optional[str] = None, parent: Optional[Union[Component, str]] = None) Component [source]¶
Create a new component with an optional name and parent.
- The parent argument can be either a Component or the Guid of a component that the created component will be
added as a child of
- create_database(filename: str, progress_func: Optional[Callable[[int, int], bool]] = None, settings: Optional[SaveSettings] = None) bool [source]¶
create_database
writes the current database (.bndb) out to the specified file.- Parameters
filename (str) – path and filename to write the bndb to, this string should have “.bndb” appended to it.
progress_func (callback) – optional function to be called with the current progress and total count.
settings (SaveSettings) – optional argument for special save options.
- Returns
True on success, False on failure
- Return type
- Example
>>> settings = SaveSettings() >>> bv.create_database(f"{bv.file.filename}.bndb", None, settings) True
- create_structure_from_offset_access(name: QualifiedName) StructureType [source]¶
- Parameters
name (QualifiedName) –
- Return type
- create_structure_member_from_access(name: QualifiedName, offset: int) Type [source]¶
- Parameters
name (QualifiedName) –
offset (int) –
- Return type
- create_tag(tag_type: TagType, data: str, user: bool = True) Tag [source]¶
create_tag
creates a newTag
object but does not add it anywhere. Usecreate_user_data_tag
to create and add in one step.- Parameters
- Returns
The created Tag
- Return type
- Example
>>> tt = bv.tag_types["Crashes"] >>> tag = bv.create_tag(tt, "Null pointer dereference", True) >>> bv.add_user_data_tag(here, tag) >>>
- create_tag_type(name: str, icon: str) TagType [source]¶
create_tag_type
creates a newTagType
and adds it to the view
- create_user_data_tag(addr: int, type: TagType, data: str, unique: bool = False) Tag [source]¶
create_user_data_tag
creates and adds aTag
object at a data address. Since this adds a user tag, it will be added to the current undo buffer.This API is appropriate for generic data tags, for functions, consider using
create_user_function_tag
or for specific addresses inside of functions, usecreate_user_address_tag
.- Parameters
- Returns
The created
Tag
- Return type
- Example
>>> tt = bv.tag_types["Crashes"] >>> bv.create_user_data_tag(here, tt, "String data to associate with this tag")
- create_user_function(addr: int, plat: Optional[Platform] = None) Function [source]¶
create_user_function
add a new user function of the givenplat
at the virtual addressaddr
- Parameters
- Return type
None
- Example
>>> bv.create_user_function(1) >>> bv.functions [<func: [email protected]>]
- define_auto_symbol(sym: CoreSymbol) None [source]¶
define_auto_symbol
adds a symbol to the internal list of automatically discovered Symbol objects in a given namespace.Warning
If multiple symbols for the same address are defined, only the most recent symbol will ever be used.
- Parameters
sym (CoreSymbol) – the symbol to define
- Return type
None
- define_auto_symbol_and_var_or_function(sym: CoreSymbol, type: Type, plat: Optional[Platform] = None) Optional[CoreSymbol] [source]¶
define_auto_symbol_and_var_or_function
Defines an “Auto” symbol, and a Variable/Function alongside it.Warning
If multiple symbols for the same address are defined, only the most recent symbol will ever be used.
- Parameters
sym (CoreSymbol) – Symbol to define
type (Type) – Type for the function/variable being defined (can be None)
- Return type
Optional[CoreSymbol]
- define_data_var(addr: int, var_type: Union[str, Type, TypeBuilder], name: Optional[Union[str, CoreSymbol]] = None) None [source]¶
define_data_var
defines a non-user data variablevar_type
at the virtual addressaddr
.- Parameters
addr (int) – virtual address to define the given data variable
var_type (StringOrType) – type to be defined at the given virtual address
name (Optional[Union[str, CoreSymbol]]) – Optionally additionally define a symbol at this location
name –
- Return type
None
- Example
>>> t = bv.parse_type_string("int foo") >>> t (<type: int32_t>, 'foo') >>> bv.define_data_var(bv.entry_point, t[0]) >>> bv.define_data_var(bv.entry_point + 4, "int", "foo") >>> bv.get_symbol_at(bv.entry_point + 4) <DataSymbol: "foo" @ 0x23950> >>> bv.get_data_var_at(bv.entry_point + 4) <var 0x23950: int32_t>
- define_imported_function(import_addr_sym: CoreSymbol, func: Function, type: Optional[Type] = None) None [source]¶
define_imported_function
defines an imported Functionfunc
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
- Return type
None
- define_type(type_id: str, default_name: Optional[_types.QualifiedNameType], type_obj: Union[str, _types.Type, _types.TypeBuilder]) _types.QualifiedName [source]¶
define_type
registers aType
type_obj
of the givenname
in the global list of types for the currentBinaryView
. 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
- Example
>>> type, name = bv.parse_type_string("int foo") >>> registered_name = bv.define_type(Type.generate_auto_type_id("source", name), name, type) >>> bv.get_type_by_name(registered_name) <type: int32_t> >>> registered_name = bv.define_type("mytypeid", None, "int bar") >>> bv.get_type_by_name(registered_name) <type: int32_t>
- define_user_data_var(addr: int, var_type: Union[str, Type, TypeBuilder], name: Optional[Union[str, CoreSymbol]] = None) Optional[DataVariable] [source]¶
define_user_data_var
defines a user data variablevar_type
at the virtual addressaddr
.- Parameters
addr (int) – virtual address to define the given data variable
var_type (binaryninja.Type) – type to be defined at the given virtual address
name (Optional[Union[str, CoreSymbol]]) – Optionally, additionally define a symbol at this same address
name –
- Return type
Optional[DataVariable]
- Example
>>> t = bv.parse_type_string("int foo") >>> t (<type: int32_t>, 'foo') >>> bv.define_user_data_var(bv.entry_point, t[0]) <var 0x2394c: int32_t> >>> bv.define_user_data_var(bv.entry_point + 4, "int", "foo") <var 0x23950: int32_t> >>> bv.get_symbol_at(bv.entry_point + 4) <DataSymbol: "foo" @ 0x23950> >>> bv.get_data_var_at(bv.entry_point + 4) <var 0x23950: int32_t>
- define_user_symbol(sym: CoreSymbol) None [source]¶
define_user_symbol
adds a symbol to the internal list of user added Symbol objects.Warning
If multiple symbols for the same address are defined, only the most recent symbol will ever be used.
- Parameters
sym (Symbol) – the symbol to define
- Return type
None
- define_user_type(name: Optional[_types.QualifiedNameType], type_obj: Union[str, _types.Type, _types.TypeBuilder]) None [source]¶
define_user_type
registers aType
type_obj
of the givenname
in the global list of user types for the currentBinaryView
.- Parameters
name (QualifiedName) – Name of the user type to be registered
type_obj (StringOrType) – Type object to be registered
- Return type
None
- Example
>>> type, name = bv.parse_type_string("int foo") >>> bv.define_user_type(name, type) >>> bv.get_type_by_name(name) <type: int32_t> >>> bv.define_user_type(None, "int bas") >>> bv.get_type_by_name("bas") <type: int32_t>
- disassembly_text(addr: int, arch: Optional[Architecture] = None) Generator[Tuple[str, int], None, None] [source]¶
disassembly_text
helper function for getting disassembly of a given address- Parameters
addr (int) – virtual address of instruction
arch (Architecture) – optional Architecture,
self.arch
is used if this parameter is None
- Returns
a str representation of the instruction at virtual address
addr
or None- Return type
str or None
- Example
>>> next(bv.disassembly_text(bv.entry_point)) 'push ebp', 1 >>>
- disassembly_tokens(addr: int, arch: Optional[Architecture] = None) Generator[Tuple[List[InstructionTextToken], int], None, None] [source]¶
- Parameters
addr (int) –
arch (Optional[Architecture]) –
- Return type
Generator[Tuple[List[InstructionTextToken], int], None, None]
- eval(expression: str, here: int = 0) int [source]¶
Evaluates a string expression to an integer value. This is a more concise alias for the
parse_expression
API
- export_object_to_library(lib: TypeLibrary, name: Optional[str], type_obj: Union[str, Type, TypeBuilder]) None [source]¶
export_object_to_library
recursively exportstype_obj
intolib
as an object with namename
As other referenced types are encountered, they are either copied into the destination type library or else the type library that provided the referenced type is added as a dependency for the destination library.
- Parameters
lib (TypeLibrary) –
name (QualifiedName) –
type_obj (StringOrType) –
- Return type
None
- export_type_to_library(lib: TypeLibrary, name: Optional[str], type_obj: Union[str, Type, TypeBuilder]) None [source]¶
export_type_to_library
recursively exportstype_obj
intolib
as a type with namename
As other referenced types are encountered, they are either copied into the destination type library or else the type library that provided the referenced type is added as a dependency for the destination library.
- Parameters
lib (TypeLibrary) –
name (QualifiedName) –
type_obj (StringOrType) –
- Return type
None
- static external_namespace() NameSpace [source]¶
External namespace for the current BinaryView
- Return type
- find_all_constant(start: int, end: int, constant: int, settings: Optional[DisassemblySettings] = None, graph_type: FunctionGraphType = FunctionGraphType.NormalFunctionGraph, progress_func: Optional[Callable[[int, int], bool]] = None, match_callback: Optional[Callable[[int, LinearDisassemblyLine], bool]] = None) QueueGenerator [source]¶
find_all_constant
searches for the integer constantconstant
starting at the virtual addressstart
until the virtual addressend
. Once a match is found, thematch_callback
is called.- Parameters
start (int) – virtual address to start searching from.
end (int) – virtual address to end the search.
constant (int) – constant to search for
settings (DisassemblySettings) – DisassemblySettings object used to render the text to be searched
graph_type (FunctionGraphType) – the IL to search within
progress_func (callback) – optional function to be called with the current progress and total count. This function should return a boolean value that decides whether the search should continue or stop
match_callback (callback) – function that gets called when a match is found. The callback takes two parameters, i.e., the address of the match, and the LinearDisassemblyLine that contains the matching line. If this parameter is None, this function becomes a generator and yields the matching address and the matching LinearDisassemblyLine. This function can return a boolean value that decides whether the search should continue or stop
- Rtype bool
whether any (one or more) match is found for the search
- find_all_data(start: int, end: int, data: bytes, flags: FindFlag = FindFlag.FindCaseSensitive, progress_func: Optional[Callable[[int, int], bool]] = None, match_callback: Optional[Callable[[int, DataBuffer], bool]] = None) QueueGenerator [source]¶
find_all_data
searches for the bytesdata
starting at the virtual addressstart
until the virtual addressend
. Once a match is found, thematch_callback
is called.- Parameters
start (int) – virtual address to start searching from.
end (int) – virtual address to end the search.
data (bytes) – data to search for
flags (FindFlag) –
(optional) defaults to case-insensitive data search
FindFlag
Description
FindCaseSensitive
Case-sensitive search
FindCaseInsensitive
Case-insensitive search
progress_func (callback) – optional function to be called with the current progress and total count. This function should return a boolean value that decides whether the search should continue or stop
match_callback (callback) – function that gets called when a match is found. The callback takes two parameters, i.e., the address of the match, and the actual DataBuffer that satisfies the search. If this parameter is None, this function becomes a generator and yields a tuple of the matching address and the matched DataBuffer. This function can return a boolean value that decides whether the search should continue or stop.
data –
- Rtype bool
whether any (one or more) match is found for the search
- find_all_text(start: int, end: int, text: str, settings: Optional[DisassemblySettings] = None, flags=FindFlag.FindCaseSensitive, graph_type=FunctionGraphType.NormalFunctionGraph, progress_func=None, match_callback=None) QueueGenerator [source]¶
find_all_text
searches for stringtext
occurring in the linear view output starting at the virtual addressstart
until the virtual addressend
. Once a match is found, thematch_callback
is called.- Parameters
start (int) – virtual address to start searching from.
end (int) – virtual address to end the search.
text (str) – text to search for
settings (DisassemblySettings) – DisassemblySettings object used to render the text to be searched
flags (FindFlag) –
(optional) defaults to case-insensitive data search
FindFlag
Description
FindCaseSensitive
Case-sensitive search
FindCaseInsensitive
Case-insensitive search
graph_type (FunctionGraphType) – the IL to search within
progress_func (callback) – optional function to be called with the current progress and total count. This function should return a boolean value that decides whether the search should continue or stop
match_callback (callback) – function that gets called when a match is found. The callback takes three parameters, i.e., the address of the match, and the actual string that satisfies the search, and the LinearDisassemblyLine that contains the matching line. If this parameter is None, this function becomes a generator and yields a tuple of the matching address, the matched string, and the matching LinearDisassemblyLine. This function can return a boolean value that decides whether the search should continue or stop
- Rtype bool
whether any (one or more) match is found for the search
- find_next_constant(start: int, constant: int, settings: Optional[DisassemblySettings] = None, graph_type: FunctionGraphType = FunctionGraphType.NormalFunctionGraph) Optional[int] [source]¶
find_next_constant
searches for integer constantconstant
occurring in the linear view output starting at the virtual addressstart
until the end of the BinaryView.- Parameters
start (int) – virtual address to start searching from.
constant (int) – constant to search for
settings (DisassemblySettings) – disassembly settings
graph_type (FunctionGraphType) – the IL to search within
- Return type
- find_next_data(start: int, data: bytes, flags: FindFlag = FindFlag.FindCaseSensitive) Optional[int] [source]¶
find_next_data
searches for the bytesdata
starting at the virtual addressstart
until the end of the BinaryView.- Parameters
- Return type
- find_next_text(start: int, text: str, settings: Optional[DisassemblySettings] = None, flags: FindFlag = FindFlag.FindCaseSensitive, graph_type: FunctionGraphType = FunctionGraphType.NormalFunctionGraph) Optional[int] [source]¶
find_next_text
searches for stringtext
occurring in the linear view output starting at the virtual addressstart
until the end of the BinaryView.- Parameters
start (int) – virtual address to start searching from.
text (str) – text to search for
settings (DisassemblySettings) – disassembly settings
flags (FindFlag) –
(optional) defaults to case-insensitive data search
FindFlag
Description
FindCaseSensitive
Case-sensitive search
FindCaseInsensitive
Case-insensitive search
graph_type (FunctionGraphType) – the IL to search within
- Return type
- get_address_for_data_offset(offset: int) Optional[int] [source]¶
get_address_for_data_offset
returns the virtual address that maps to the specific file offset.- Parameters
offset (int) – file offset
- Returns
the virtual address of the first segment that contains that file location
- Return type
Int
- get_address_input(prompt: str, title: str, current_address: Optional[int] = None) Optional[int] [source]¶
get_address_input
Gets a virtual address via a prompt displayed to the user
- get_all_fields_referenced(name: _types.QualifiedNameType) List[int] [source]¶
get_all_fields_referenced
returns a list of offsets in the QualifiedName specified by name, which are referenced by code.- Parameters
name (QualifiedName) – name of type to query for references
- Returns
List of offsets
- Return type
list(integer)
- Example
>>> bv.get_all_fields_referenced('A') [0, 8, 16, 24, 32, 40] >>>
- get_all_sizes_referenced(name: _types.QualifiedNameType) Mapping[int, List[int]] [source]¶
get_all_sizes_referenced
returns a map from field offset to a list of sizes of the accesses to it.- Parameters
name (QualifiedName) – name of type to query for references
- Returns
A map from field offset to the size of the code accesses to it
- Return type
map
- Example
>>> bv.get_all_sizes_referenced('B') {0: [1, 8], 8: [8], 16: [1, 8]} >>>
- get_all_types_referenced(name: _types.QualifiedNameType) Mapping[int, List[_types.Type]] [source]¶
get_all_types_referenced
returns a map from field offset to a list of incoming types written to the specified type.- Parameters
name (QualifiedName) – name of type to query for references
- Returns
A map from field offset to a list of incoming types written to it
- Return type
map
- Example
>>> bv.get_all_types_referenced('B') {0: [<type: char, 0% confidence>], 8: [<type: int64_t, 0% confidence>], 16: [<type: char, 0% confidence>, <type: bool>]} >>>
- get_ascii_string_at(addr: int, min_length: int = 4, max_length: Optional[int] = None, require_cstring: bool = True) Optional[StringReference] [source]¶
get_ascii_string_at
returns an ascii string found ataddr
.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
- Returns
the string found at
addr
or None if a string does not exist- Return type
StringReference or None
- Example
>>> s1 = bv.get_ascii_string_at(0x70d0) >>> s1 <AsciiString: 0x70d0, len 0xb> >>> s1.value 'AWAVAUATUSH' >>> s2 = bv.get_ascii_string_at(0x70d1) >>> s2 <AsciiString: 0x70d1, len 0xa> >>> s2.value 'WAVAUATUSH'
- get_auto_data_tags_at(addr: int) List[Tag] [source]¶
get_auto_data_tags_at
gets a list of all auto-definedTag
objects for a data address.
- get_auto_data_tags_in_range(address_range: AddressRange) List[Tuple[int, Tag]] [source]¶
get_auto_data_tags_in_range
gets a list of all auto-defined dataTag
objects in a given range. Range is inclusive at the start, exclusive at the end.- Parameters
address_range (AddressRange) – address range from which to get tags
- Returns
A list of (address, data tag) tuples
- Return type
- get_auto_data_tags_of_type(addr: int, tag_type: TagType) List[Tag] [source]¶
get_auto_data_tags_of_type
gets a list of all auto-definedTag
objects for a data address of a given type.
- get_basic_blocks_at(addr: int) List[BasicBlock] [source]¶
get_basic_blocks_at
get a list ofBasicBlock
objects which exist at the provided virtual address.- Parameters
addr (int) – virtual address of BasicBlock desired
- Returns
a list of
BasicBlock
objects- Return type
- get_basic_blocks_starting_at(addr: int) List[BasicBlock] [source]¶
get_basic_blocks_starting_at
get a list ofBasicBlock
objects which start at the provided virtual address.- Parameters
addr (int) – virtual address of BasicBlock desired
- Returns
a list of
BasicBlock
objects- Return type
- get_callees(addr: int, func: Optional[Function] = None, arch: Optional[Architecture] = None) List[int] [source]¶
get_callees
returns a list of virtual addresses called by the call site in the functionfunc
, of the architecturearch
, and at the addressaddr
. If no function is specified, call sites from all functions and containing the address will be considered. If no architecture is specified, the architecture of the function will be used.- Parameters
addr (int) – virtual address of the call site to query for callees
func (Architecture) – (optional) the function that the call site belongs to
func – (optional) the architecture of the call site
arch (Optional[Architecture]) –
- Returns
list of integers
- Return type
list(integer)
- get_callers(addr: int) Generator[ReferenceSource, None, None] [source]¶
get_callers
returns a list of ReferenceSource objects (xrefs or cross-references) that call the provided virtual address. In this case, tail calls, jumps, and ordinary calls are considered.- Parameters
addr (int) – virtual address of callee to query for callers
- Returns
List of References that call the given virtual address
- Return type
- Example
>>> bv.get_callers(here) [<ref: [email protected]>] >>>
- get_code_refs(addr: int, length: Optional[int] = None) Generator[ReferenceSource, None, None] [source]¶
get_code_refs
returns a generator ofReferenceSource
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, seeadd_user_code_ref
.The related
get_data_refs
is used to find data references to an address unlike this API which returns references that exist in code.Note
Note that get_code_refs returns xrefs to code that references the address being queried. get_data_refs on the other hand returns references that exist in data (pointers in global variables for example). The related
get_refs_from
looks for references that are outgoing from the queried address to other locations.- Parameters
- Returns
A generator of References for the given virtual address
- Return type
Generator[ReferenceSource, None, None]
- Example
>>> bv.get_code_refs(here) [<ref: [email protected]>] >>>
- get_code_refs_for_type(name: str) Generator[ReferenceSource, None, None] [source]¶
get_code_refs_for_type
returns a Generator[ReferenceSource] objects (xrefs or cross-references) that reference the provided QualifiedName.- Parameters
name (QualifiedName) – name of type to query for references
- Returns
List of References for the given type
- Return type
- Example
>>> bv.get_code_refs_for_type('A') [<ref: [email protected]>] >>>
- get_code_refs_for_type_field(name: str, offset: int) Generator[TypeFieldReference, None, None] [source]¶
get_code_refs_for_type
returns a Generator[TypeFieldReference] objects (xrefs or cross-references) that reference the provided type field.- Parameters
name (QualifiedName) – name of type to query for references
offset (int) – offset of the field, relative to the type
- Returns
Generator of References for the given type
- Return type
Generator[TypeFieldReference]
- Example
>>> bv.get_code_refs_for_type_field('A', 0x8) [<ref: [email protected]>] >>>
- get_code_refs_for_type_fields_from(addr: int, func: Optional[Function] = None, arch: Optional[Architecture] = None, length: Optional[int] = None) List[TypeReferenceSource] [source]¶
get_code_refs_for_type_fields_from
returns a list of type fields referenced by code in the functionfunc
, of the architecturearch
, and at the addressaddr
. 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
- Returns
list of references
- Return type
- get_code_refs_for_type_from(addr: int, func: Optional[Function] = None, arch: Optional[Architecture] = None, length: Optional[int] = None) List[TypeReferenceSource] [source]¶
get_code_refs_for_type_from
returns a list of types referenced by code in the functionfunc
, of the architecturearch
, and at the addressaddr
. 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
- Returns
list of references
- Return type
- get_code_refs_from(addr: int, func: Optional[Function] = None, arch: Optional[Architecture] = None, length: Optional[int] = None) List[int] [source]¶
get_code_refs_from
returns a list of virtual addresses referenced by code in the functionfunc
, of the architecturearch
, and at the addressaddr
. 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, seeadd_user_code_ref
.
- 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 eachFunction
. For more information, seeaddress_comments
.
- get_component_by_path(path: str) Optional[Component] [source]¶
Lookup a Component by its pathname
- Note
This is a convenience method, and for performance-sensitive lookups, GetComponentByGuid is very highly recommended.
- Parameters
path (str) –
- Return type
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
- get_constant_data(addr: int) DataBuffer [source]¶
- Parameters
addr (int) –
- Return type
- get_data_offset_for_address(address: int) Optional[int] [source]¶
get_data_offset_for_address
returns the file offset that maps to the given virtual address, if possible.If address falls within a bss segment or an external segment, for example, no mapping is possible, and None will be returned.
- Parameters
address (int) – virtual address
- Returns
the file location that is mapped to the given virtual address, or None if no such mapping is possible
- Return type
Int
- get_data_refs(addr: int, length: Optional[int] = None) Generator[int, None, None] [source]¶
get_data_refs
returns a list of virtual addresses of _data_ (not code) which referencesaddr
, optionally specifying a length. Whenlength
is setget_data_refs
returns the data which references in the rangeaddr
-addr``+``length
. This function returns both autoanalysis (“auto”) and user-specified (“user”) xrefs. To add a user-specified reference, seeadd_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).
- 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 typename
. 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 typename
. Note, the returned addresses are the actual start of the queried type field. For example, suppose there is a DataVariable at 0x1000 that has type A, and type A contains type B at offset 0x10. Then get_data_refs_for_type_field(‘B’, 0x8) will return 0x1018 for it.- Parameters
name (QualifiedName) – name of type to query for references
offset (int) – offset of the field, relative to the type
- Returns
list of integers
- Return type
list(integer)
- Example
>>> bv.get_data_refs_for_type_field('A', 0x8) [4203812] >>>
- get_data_refs_from(addr: int, length: Optional[int] = None) Generator[int, None, None] [source]¶
get_data_refs_from
returns a list of virtual addresses referenced by the addressaddr
. Optionally specifying a length. Whenlength
is setget_data_refs_from
returns the data referenced in the rangeaddr
-addr``+``length
. This function returns both autoanalysis (“auto”) and user-specified (“user”) xrefs. To add a user-specified reference, seeadd_user_data_ref
.
- get_data_tags_at(addr: int) List[Tag] [source]¶
get_data_tags_at
gets a list of allTag
objects for a data address.
- get_data_tags_in_range(address_range: AddressRange) List[Tuple[int, Tag]] [source]¶
get_data_tags_in_range
gets a list of all dataTag
objects in a given range. Range is inclusive at the start, exclusive at the end.- Parameters
address_range (AddressRange) – address range from which to get tags
- Returns
A list of (address, data tag) tuples
- Return type
- get_data_tags_of_type(addr: int, tag_type: TagType) List[Tag] [source]¶
get_data_tags_of_type
gets a list of allTag
objects for a data address of a given type.
- get_data_var_at(addr: int) Optional[DataVariable] [source]¶
get_data_var_at
returns the data type at a given virtual address.- Parameters
addr (int) – virtual address to get the data type from
- Returns
returns the DataVariable at the given virtual address, None on error
- Return type
- Example
>>> t = bv.parse_type_string("int foo") >>> bv.define_data_var(bv.entry_point, t[0]) >>> bv.get_data_var_at(bv.entry_point) <var 0x100001174: int32_t>
- get_disassembly(addr: int, arch: Optional[Architecture] = None) Optional[str] [source]¶
get_disassembly
simple helper function for printing disassembly of a given address- Parameters
addr (int) – virtual address of instruction
arch (Architecture) – optional Architecture,
self.arch
is used if this parameter is None
- Returns
a str representation of the instruction at virtual address
addr
or None- Return type
str or None
- Example
>>> bv.get_disassembly(bv.entry_point) 'push ebp' >>>
Note
This API is very simplistic and only returns text. See
disassembly_text
and instructions for more capable APIs.
- get_entropy(addr: int, length: int, block_size: int = 0) List[float] [source]¶
get_entropy
returns the shannon entropy given the startaddr
,length
in bytes, and optionally inblock_size
chunks.
- get_function_at(addr: int, plat: Optional[Platform] = None) Optional[Function] [source]¶
get_function_at
gets a Function object for the function that starts at virtual addressaddr
:- Parameters
- Returns
returns a Function object or None for the function at the virtual address provided
- Return type
- Example
>>> bv.get_function_at(bv.entry_point) <func: [email protected]> >>>
- get_functions_at(addr: int) List[Function] [source]¶
get_functions_at
get a list ofFunction
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
- get_functions_by_name(name: str, plat: Optional[Platform] = None, ordered_filter: Optional[List[SymbolType]] = None) List[Function] [source]¶
get_functions_by_name
returns a list ofFunction
objects function with aSymbol
ofname
.- 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
- Example
>>> bv.get_functions_by_name("main") [<func: [email protected]>] >>>
- get_functions_containing(addr: int, plat: Optional[Platform] = None) List[Function] [source]¶
get_functions_containing
returns a list ofFunction
objects which contain the given address.
- get_instruction_length(addr: int, arch: Optional[Architecture] = None) int [source]¶
get_instruction_length
returns the number of bytes in the instruction of Architecturearch
at the virtual addressaddr
- Parameters
addr (int) – virtual address of the instruction query
arch (Architecture) – (optional) the architecture of the instructions if different from the default
- Returns
Number of bytes in instruction
- Return type
- Example
>>> bv.get_disassembly(0x100012f1) 'xor eax, eax' >>> bv.get_instruction_length(0x100012f1) 2L >>>
- get_linear_disassembly(settings: Optional[DisassemblySettings] = None) Iterator[LinearDisassemblyLine] [source]¶
get_linear_disassembly
gets an iterator for all lines in the linear disassembly of the view for the given disassembly settings.Note
linear_disassembly doesn’t just return disassembly; it will return a single line from the linear view, and thus will contain both data views, and disassembly.
- Parameters
settings (DisassemblySettings) – instance specifying the desired output formatting. Defaults to None which will use default settings.
- Returns
An iterator containing formatted disassembly lines.
- Return type
LinearDisassemblyIterator
- Example
>>> settings = DisassemblySettings() >>> lines = bv.get_linear_disassembly(settings) >>> for line in lines: ... print(line) ... break ... cf fa ed fe 07 00 00 01 ........
- get_linear_disassembly_position_at(addr: int, settings: Optional[DisassemblySettings] = None) LinearViewCursor [source]¶
get_linear_disassembly_position_at
instantiates aLinearViewCursor
object for use inget_previous_linear_disassembly_lines
orget_next_linear_disassembly_lines
.- Parameters
addr (int) – virtual address of linear disassembly position
settings (DisassemblySettings) – an instantiated
DisassemblySettings
object, defaults to None which will use default settings
- Returns
An instantiated
LinearViewCursor
object for the provided virtual address- Return type
- Example
>>> settings = DisassemblySettings() >>> pos = bv.get_linear_disassembly_position_at(0x1000149f, settings) >>> lines = bv.get_previous_linear_disassembly_lines(pos) >>> lines [<0x1000149a: pop esi>, <0x1000149b: pop ebp>, <0x1000149c: retn 0xc>, <0x1000149f: >]
- get_load_settings(type_name: str) Optional[Settings] [source]¶
get_load_settings
retrieve aSettings
object which defines the load settings for the givenBinaryViewType
type_name
- Parameters
type_name (str) – the
BinaryViewType
name- Returns
the load settings
- Return type
Settings
, orNone
- get_load_settings_type_names() List[str] [source]¶
get_load_settings_type_names
retrieve a listBinaryViewType
names for which load settings exist in thisBinaryView
context- Returns
list of
BinaryViewType
names- Return type
- get_modification(addr: int, length: Optional[int] = None) List[ModificationStatus] [source]¶
get_modification
returns the modified bytes of up tolength
bytes from virtual addressaddr
, or iflength
is None returns the ModificationStatus.- Parameters
- 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 virtualaddress
addr
- get_next_data_after(addr: int) int [source]¶
get_next_data_after
retrieves the virtual address of the next non-code byte.
- get_next_data_var_after(addr: int) Optional[DataVariable] [source]¶
get_next_data_var_after
retrieves the nextDataVariable
, or None.- Parameters
addr (int) – the virtual address to start looking from.
- Returns
the next
DataVariable
- Return type
- 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 nextDataVariable
- Parameters
addr (int) – the virtual address to start looking from.
- Returns
the virtual address of the next
DataVariable
- Return type
- Example
>>> hex(bv.get_next_data_var_start_after(0x10000000)) '0x1000003cL' >>> bv.get_data_var_at(0x1000003c) <var 0x1000003c: int32_t> >>>
- get_next_function_start_after(addr: int) int [source]¶
get_next_function_start_after
returns the virtual address of the Function that occurs after the virtual addressaddr
- Parameters
addr (int) – the virtual address to start looking from.
- Returns
the virtual address of the next Function
- Return type
- 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 ofLinearDisassemblyLine
objects for the next disassembly lines, and updates the LinearViewCursor passed in. This function can be called repeatedly to get more lines of linear disassembly.- Parameters
pos (LinearViewCursor) – Position to start retrieving linear disassembly lines from
- Returns
a list of
LinearDisassemblyLine
objects for the next lines.- Example
>>> settings = DisassemblySettings() >>> pos = bv.get_linear_disassembly_position_at(0x10001483, settings) >>> bv.get_next_linear_disassembly_lines(pos) [<0x10001483: xor eax, eax {0x0}>, <0x10001485: inc eax {0x1}>, ... , <0x10001488: >] >>> bv.get_next_linear_disassembly_lines(pos) [<0x10001488: push dword [ebp+0x10 {arg_c}]>, ... , <0x1000149a: >] >>>
- Return type
- get_next_valid_offset(addr: int) int [source]¶
get_next_valid_offset
returns the next valid offset afteraddr
.
- get_previous_basic_block_end_before(addr: int) int [source]¶
get_previous_basic_block_end_before
- Parameters
addr (int) – the virtual address to start looking from.
- Returns
the virtual address of the previous BasicBlock end
- Return type
- Example
>>> hex(bv.entry_point) '0x1000149fL' >>> hex(bv.get_next_basic_block_start_after(bv.entry_point)) '0x100014a8L' >>> hex(bv.get_previous_basic_block_end_before(0x100014a8)) '0x100014a8L'
- get_previous_basic_block_start_before(addr: int) int [source]¶
get_previous_basic_block_start_before
returns the virtual address of the BasicBlock that occurs prior to the provided virtual address- Parameters
addr (int) – the virtual address to start looking from.
- Returns
the virtual address of the previous BasicBlock
- Return type
- Example
>>> hex(bv.entry_point) '0x1000149fL' >>> hex(bv.get_next_basic_block_start_after(bv.entry_point)) '0x100014a8L' >>> hex(bv.get_previous_basic_block_start_before(0x100014a8)) '0x1000149fL' >>>
- get_previous_data_var_before(addr: int) Optional[DataVariable] [source]¶
get_previous_data_var_before
retrieves the previousDataVariable
, or None.- Parameters
addr (int) – the virtual address to start looking from.
- Returns
the previous
DataVariable
- Return type
- Example
>>> bv.get_previous_data_var_before(0x1000003c) <var 0x10000000: int16_t> >>>
- get_previous_data_var_start_before(addr: int) int [source]¶
get_previous_data_var_start_before
- Parameters
addr (int) – the virtual address to start looking from.
- Returns
the virtual address of the previous
DataVariable
- Return type
- Example
>>> hex(bv.get_previous_data_var_start_before(0x1000003c)) '0x10000000L' >>> bv.get_data_var_at(0x10000000) <var 0x10000000: int16_t> >>>
- get_previous_function_start_before(addr: int) int [source]¶
get_previous_function_start_before
returns the virtual address of the Function that occurs prior to the virtual address provided- Parameters
addr (int) – the virtual address to start looking from.
- Returns
the virtual address of the previous Function
- Return type
- 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 ofLinearDisassemblyLine
objects for the previous disassembly lines, and updates the LinearViewCursor passed in. This function can be called repeatedly to get more lines of linear disassembly.- Parameters
pos (LinearViewCursor) – Position to start retrieving linear disassembly lines from
- Returns
a list of
LinearDisassemblyLine
objects for the previous lines.- Example
>>> settings = DisassemblySettings() >>> pos = bv.get_linear_disassembly_position_at(0x1000149a, settings) >>> bv.get_previous_linear_disassembly_lines(pos) [<0x10001488: push dword [ebp+0x10 {arg_c}]>, ... , <0x1000149a: >] >>> bv.get_previous_linear_disassembly_lines(pos) [<0x10001483: xor eax, eax {0x0}>, ... , <0x10001488: >]
- Return type
- get_recent_basic_block_at(addr: int) Optional[BasicBlock] [source]¶
- Parameters
addr (int) –
- Return type
- get_segment_at(addr: int) Optional[Segment] [source]¶
get_segment_at
gets the Segment a given virtual address is located in
- 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
- Example
>>> bv.get_sizes_referenced('B', 16) [1, 8] >>>
- get_string_at(addr: int, partial: bool = False) Optional[StringReference] [source]¶
get_string_at
returns the string that falls on given virtual address.Note
This returns discovered strings and is therefore governed by analysis.limits.minStringLength and other settings. For an alternative API that simply returns any potential c-string at a given location, use
get_ascii_string_at
.- Parameters
- Returns
returns the StringReference at the given virtual address, otherwise None.
- Return type
- Example
>>> bv.get_string_at(0x40302f) <StringType.AsciiString: 0x403028, len 0x12>
- get_strings(start: Optional[int] = None, length: Optional[int] = None) List[StringReference] [source]¶
get_strings
returns a list of strings defined in the binary in the optional virtual address range:start-(start+length)
Note that this API will only return strings that have been identified by the string-analysis and thus governed by the minimum and maximum length settings and unrelated to the type system.
- Parameters
- Returns
a list of all strings or a list of strings defined between
start
andstart+length
- Return type
- Example
>>> bv.get_strings(0x1000004d, 1) [<AsciiString: 0x1000004d, len 0x2c>] >>>
- get_symbol_at(addr: int, namespace: _types.NameSpaceType = None) Optional[_types.CoreSymbol] [source]¶
get_symbol_at
returns the Symbol at the provided virtual address.- Parameters
addr (int) – virtual address to query for symbol
namespace (_types.NameSpaceType) – (optional) the namespace of the symbols to retrieve
- Returns
CoreSymbol for the given virtual address
- Return type
- Example
>>> bv.get_symbol_at(bv.entry_point) <FunctionSymbol: "_start" @ 0x100001174> >>>
- get_symbol_by_raw_name(name: str, namespace: _types.NameSpaceType = None) Optional[_types.CoreSymbol] [source]¶
get_symbol_by_raw_name
retrieves a Symbol object for the given raw (mangled) name.- Parameters
name (str) – raw (mangled) name of Symbol to be retrieved
namespace (_types.NameSpaceType) – (optional) the namespace to search for the given symbol
- Returns
CoreSymbol object corresponding to the provided raw name
- Return type
- Example
>>> bv.get_symbol_by_raw_name('[email protected]@@[email protected]@[email protected]@Z') <FunctionSymbol: "public: static enum Foobar::foo __cdecl Foobar::testf(enum Foobar::foo)" @ 0x10001100> >>>
- get_symbols(start: Optional[int] = None, length: Optional[int] = None, namespace: _types.NameSpaceType = None) List[_types.CoreSymbol] [source]¶
get_symbols
retrieves the list of all Symbol objects in the optionally provided range.- Parameters
- Returns
list of all Symbol objects, or those Symbol objects in the range of
start
-start+length
- Return type
- Example
>>> bv.get_symbols(0x1000200c, 1) [<ImportAddressSymbol: "KERNEL32!IsProcessorFeaturePresent" @ 0x1000200c>] >>>
- get_symbols_by_name(name: str, namespace: _types.NameSpaceType = None, ordered_filter: Optional[List[SymbolType]] = None) List[_types.CoreSymbol] [source]¶
get_symbols_by_name
retrieves a list of Symbol objects for the given symbol name and ordered filter- Parameters
name (str) – name of Symbol object to be retrieved
namespace (_types.NameSpaceType) – (optional) the namespace to search for the given symbol
namespace – (optional) the namespace to search for the given symbol
ordered_filter (Optional[List[SymbolType]]) – (optional) an ordered filter based on SymbolType
- Returns
Symbol object corresponding to the provided name
- Return type
- Example
>>> bv.get_symbols_by_name('[email protected]@@[email protected]@[email protected]@Z') [<FunctionSymbol: "public: static enum Foobar::foo __cdecl Foobar::testf(enum Foobar::foo)" @ 0x10001100>] >>>
- get_symbols_by_raw_name(name: str, namespace: _types.NameSpaceType = None) List[_types.CoreSymbol] [source]¶
- get_symbols_of_type(sym_type: SymbolType, start: Optional[int] = None, length: Optional[int] = None, namespace: _types.NameSpaceType = None) List[_types.CoreSymbol] [source]¶
get_symbols_of_type
retrieves a list of allSymbol
objects of the provided symbol type in the optionallyprovided range.
- Parameters
sym_type (SymbolType) – A Symbol type:
SymbolType
namespace (_types.NameSpaceType) –
- Returns
list of all
Symbol
objects of typesym_type
, or thoseSymbol
objects in the range ofstart
-start+length
- Return type
- Example
>>> bv.get_symbols_of_type(SymbolType.ImportAddressSymbol, 0x10002028, 1) [<ImportAddressSymbol: "KERNEL32!GetCurrentThreadId" @ 0x10002028>] >>>
- get_tag(id: str) Optional[Tag] [source]¶
Get a tag by its id. Note this does not tell you anything about where it is used.
- get_tag_type(name: str) Optional[TagType] [source]¶
Get a tag type by its name. Shorthand for get_tag_type_by_name()
- get_type_by_id(id: str) Optional[Type] [source]¶
get_type_by_id
returns the defined type whose unique identifier corresponds with the providedid
- Parameters
id (str) – Unique identifier to lookup
- Returns
A
Type
or None if the type does not exist- Return type
Type or None
- Example
>>> type, name = bv.parse_type_string("int foo") >>> type_id = Type.generate_auto_type_id("source", name) >>> bv.define_type(type_id, name, type) >>> bv.get_type_by_id(type_id) <type: int32_t> >>>
- get_type_by_name(name: _types.QualifiedNameType) Optional[_types.Type] [source]¶
get_type_by_name
returns the defined type whose name corresponds with the providedname
- 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 providedname
- Parameters
name (QualifiedName) – Type name to lookup
- Returns
The unique identifier of the type
- Return type
- Example
>>> type, name = bv.parse_type_string("int foo") >>> type_id = Type.generate_auto_type_id("source", name) >>> registered_name = bv.define_type(type_id, name, type) >>> bv.get_type_id(registered_name) == type_id True >>>
- get_type_library(name: str) Optional[TypeLibrary] [source]¶
get_type_library
returns the TypeLibrary- Parameters
name (str) – Library name to lookup
- Returns
The Type Library object, if any
- Return type
TypeLibrary or None
- Example
- get_type_name_by_id(id: str) Optional[QualifiedName] [source]¶
get_type_name_by_id
returns the defined type name whose unique identifier corresponds with the providedid
- Parameters
id (str) – Unique identifier to lookup
- Returns
A QualifiedName or None if the type does not exist
- Return type
QualifiedName or None
- Example
>>> type, name = bv.parse_type_string("int foo") >>> type_id = Type.generate_auto_type_id("source", name) >>> bv.define_type(type_id, name, type) 'foo' >>> bv.get_type_name_by_id(type_id) 'foo' >>>
- get_type_refs_for_type(name: _types.QualifiedNameType) List[_types.TypeReferenceSource] [source]¶
get_type_refs_for_type
returns a list of TypeReferenceSource objects (xrefs or cross-references) that reference the provided QualifiedName.- Parameters
name (QualifiedName) – name of type to query for references
- Returns
List of references for the given type
- Return type
- Example
>>> bv.get_type_refs_for_type('A') ['<type D, offset 0x8, direct>', '<type C, offset 0x10, indirect>'] >>>
- get_type_refs_for_type_field(name: _types.QualifiedNameType, offset: int) List[_types.TypeReferenceSource] [source]¶
get_type_refs_for_type
returns a list of TypeReferenceSource objects (xrefs or cross-references) that reference the provided type field.- Parameters
name (QualifiedName) – name of type to query for references
offset (int) – offset of the field, relative to the type
- Returns
List of references for the given type
- Return type
- Example
>>> bv.get_type_refs_for_type_field('A', 0x8) ['<type D, offset 0x8, direct>', '<type C, offset 0x10, indirect>'] >>>
- get_types_referenced(name: QualifiedName, offset: int) List[Type] [source]¶
get_types_referenced
returns a list of types related to the type field access.- Parameters
name (QualifiedName) – name of type to query for references
offset (int) – offset of the field
- Returns
a list of types related to the type field access.
- Return type
- Example
>>> bv.get_types_referenced('B', 0x10) [<type: bool>, <type: char, 0% confidence>] >>>
- get_user_data_tags_at(addr: int) List[Tag] [source]¶
get_user_data_tags_at
gets a list of all userTag
objects for a data address.
- get_user_data_tags_in_range(address_range: AddressRange) List[Tuple[int, Tag]] [source]¶
get_user_data_tags_in_range
gets a list of all user dataTag
objects in a given range. Range is inclusive at the start, exclusive at the end.- Parameters
address_range (AddressRange) – address range from which to get tags
- Returns
A list of (address, data tag) tuples
- Return type
- get_user_data_tags_of_type(addr: int, tag_type: TagType) List[Tag] [source]¶
get_user_data_tags_of_type
gets a list of all userTag
objects for a data address of a given type.
- get_view_of_type(name: str) Optional[BinaryView] [source]¶
get_view_of_type
returns the BinaryView associated with the provided name if it exists.- Parameters
name (str) – Name of the view to be retrieved
- Returns
BinaryView object associated with the provided name or None on failure
- Return type
BinaryView or None
- has_initial_analysis() bool [source]¶
has_initial_analysis
check for the presence of an initial analysis in this BinaryView.- Returns
True if the BinaryView has a valid initial analysis, False otherwise
- Return type
- hlil_functions(preload_limit: Optional[int] = None, function_generator: Optional[Generator[Function, None, None]] = None) Generator[HighLevelILFunction, None, None] [source]¶
Generates a list of il functions. This method should be used instead of ‘functions’ property if HLIL is needed and performance is a concern.
- import_library_object(name: str, lib: Optional[TypeLibrary] = None) Optional[Type] [source]¶
import_library_object
recursively imports an object from the specified type library, or, if no library was explicitly provided, the first type library associated with the currentBinaryView
that provides the name requested.This may have the impact of loading other type libraries as dependencies on other type libraries are lazily resolved when references to types provided by them are first encountered.
Note
If you are implementing a custom BinaryView and use this method to import object types,
you should then call
record_imported_object
with the details of where the object is located.- Parameters
name (QualifiedName) –
lib (TypeLibrary) –
- Returns
the object type, with any interior NamedTypeReferences renamed as necessary to be appropriate for the current view
- Return type
- import_library_type(name: str, lib: Optional[TypeLibrary] = None) Optional[Type] [source]¶
import_library_type
recursively imports a type from the specified type library, or, if no library was explicitly provided, the first type library associated with the currentBinaryView
that provides the name requested.This may have the impact of loading other type libraries as dependencies on other type libraries are lazily resolved when references to types provided by them are first encountered.
Note that the name actually inserted into the view may not match the name as it exists in the type library in the event of a name conflict. To aid in this, the
Type
object returned is a NamedTypeReference to the deconflicted name used.- Parameters
name (QualifiedName) –
lib (TypeLibrary) –
- Returns
a NamedTypeReference to the type, taking into account any renaming performed
- Return type
- insert(addr: int, data: bytes) int [source]¶
insert
inserts the bytes indata
to the virtual addressaddr
.
- static internal_namespace() NameSpace [source]¶
Internal namespace for the current BinaryView
- Return type
- invert_branch(addr: int, arch: Optional[Architecture] = None) bool [source]¶
invert_branch
convert the branch instruction of architecturearch
at the virtual addressaddr
to the inverse branch.Note
This API performs a binary patch, analysis may need to be updated afterward. Additionally the binary file must be saved in order to preserve the changes made.
- Parameters
addr (int) – virtual address of the instruction to be modified
arch (Architecture) – (optional) the architecture of the instructions if different from the default
- Returns
True on success, False on failure.
- Return type
- Example
>>> bv.get_disassembly(0x1000130e) 'je 0x10001317' >>> bv.invert_branch(0x1000130e) True >>> >>> bv.get_disassembly(0x1000130e) 'jne 0x10001317' >>>
- is_always_branch_patch_available(addr: int, arch: Optional[Architecture] = None) bool [source]¶
is_always_branch_patch_available
queries the architecture plugin to determine if the instruction ataddr
can be made to always branch. The actual logic of which is implemented in theperform_is_always_branch_patch_available
in the corresponding architecture.- Parameters
addr (int) – the virtual address of the instruction to be patched
arch (Architecture) – (optional) the architecture for the current view
- Returns
True if the instruction can be patched, False otherwise
- Return type
- Example
>>> bv.get_disassembly(0x100012ed) 'test eax, eax' >>> bv.is_always_branch_patch_available(0x100012ed) False >>> bv.get_disassembly(0x100012ef) 'jg 0x100012f5' >>> bv.is_always_branch_patch_available(0x100012ef) True >>>
- is_invert_branch_patch_available(addr: int, arch: Optional[Architecture] = None) bool [source]¶
is_invert_branch_patch_available
queries the architecture plugin to determine if the instruction ataddr
is a branch that can be inverted. The actual logic of which is implemented in theperform_is_invert_branch_patch_available
in the corresponding architecture.- Parameters
addr (int) – the virtual address of the instruction to be patched
arch (Architecture) – (optional) the architecture of the instructions if different from the default
- Returns
True if the instruction can be patched, False otherwise
- Return type
- Example
>>> bv.get_disassembly(0x100012ed) 'test eax, eax' >>> bv.is_invert_branch_patch_available(0x100012ed) False >>> bv.get_disassembly(0x100012ef) 'jg 0x100012f5' >>> bv.is_invert_branch_patch_available(0x100012ef) True >>>
- is_never_branch_patch_available(addr: int, arch: Optional[Architecture] = None) bool [source]¶
is_never_branch_patch_available
queries the architecture plugin to determine if the instruction at the instruction ataddr
can be made to never branch. The actual logic of which is implemented in theperform_is_never_branch_patch_available
in the corresponding architecture.- Parameters
addr (int) – the virtual address of the instruction to be patched
arch (Architecture) – (optional) the architecture of the instructions if different from the default
- Returns
True if the instruction can be patched, False otherwise
- Return type
- Example
>>> bv.get_disassembly(0x100012ed) 'test eax, eax' >>> bv.is_never_branch_patch_available(0x100012ed) False >>> bv.get_disassembly(0x100012ef) 'jg 0x100012f5' >>> bv.is_never_branch_patch_available(0x100012ef) True >>>
- is_offset_code_semantics(addr: int) bool [source]¶
is_offset_code_semantics
checks if a virtual addressaddr
is semantically valid for code.
- is_offset_executable(addr: int) bool [source]¶
is_offset_executable
checks if a virtual addressaddr
is valid for executing.
- is_offset_extern_semantics(addr: int) bool [source]¶
is_offset_extern_semantics
checks if a virtual addressaddr
is semantically valid for external references.
- is_offset_readable(addr: int) bool [source]¶
is_offset_readable
checks if a virtual addressaddr
is valid for reading.
- is_offset_writable(addr: int) bool [source]¶
is_offset_writable
checks if a virtual addressaddr
is valid for writing.
- is_offset_writable_semantics(addr: int) bool [source]¶
is_offset_writable_semantics
checks if a virtual addressaddr
is semantically writable. Some sections may have writable permissions for linking purposes but can be treated as read-only for the purposes of analysis.
- is_skip_and_return_value_patch_available(addr: int, arch: Optional[Architecture] = None) bool [source]¶
is_skip_and_return_value_patch_available
queries the architecture plugin to determine if the instruction ataddr
is similar to an x86 “call” instruction which can be made to return a value. The actual logic of which is implemented in theperform_is_skip_and_return_value_patch_available
in the corresponding architecture.- Parameters
addr (int) – the virtual address of the instruction to be patched
arch (Architecture) – (optional) the architecture of the instructions if different from the default
- Returns
True if the instruction can be patched, False otherwise
- Return type
- Example
>>> bv.get_disassembly(0x100012f6) 'mov dword [0x10003020], eax' >>> bv.is_skip_and_return_value_patch_available(0x100012f6) False >>> bv.get_disassembly(0x100012fb) 'call 0x10001629' >>> bv.is_skip_and_return_value_patch_available(0x100012fb) True >>>
- is_skip_and_return_zero_patch_available(addr: int, arch: Optional[Architecture] = None) bool [source]¶
is_skip_and_return_zero_patch_available
queries the architecture plugin to determine if the instruction ataddr
is similar to an x86 “call” instruction which can be made to return zero. The actual logic of which is implemented in theperform_is_skip_and_return_zero_patch_available
in the corresponding architecture.- Parameters
addr (int) – the virtual address of the instruction to be patched
arch (Architecture) – (optional) the architecture of the instructions if different from the default
- Returns
True if the instruction can be patched, False otherwise
- Return type
- Example
>>> bv.get_disassembly(0x100012f6) 'mov dword [0x10003020], eax' >>> bv.is_skip_and_return_zero_patch_available(0x100012f6) False >>> bv.get_disassembly(0x100012fb) 'call 0x10001629' >>> bv.is_skip_and_return_zero_patch_available(0x100012fb) True >>>
- is_type_auto_defined(name: _types.QualifiedNameType) bool [source]¶
is_type_auto_defined
queries the user type list of name. If name is not in the user type list then the name is considered an auto type.- Parameters
name (QualifiedName) – Name of type to query
- Returns
True if the type is not a user type. False if the type is a user type.
- Example
>>> bv.is_type_auto_defined("foo") True >>> bv.define_user_type("foo", bv.parse_type_string("struct {int x,y;}")[0]) >>> bv.is_type_auto_defined("foo") False >>>
- Return type
- is_valid_offset(addr: int) bool [source]¶
is_valid_offset
checks if a virtual addressaddr
is valid .
- lookup_imported_object_library(addr: int, platform: Optional[Platform] = None) Optional[Tuple[TypeLibrary, str]] [source]¶
lookup_imported_object_library
gives you details of which type library and name was used to determine the type of a symbol at a given address- Parameters
- Returns
A tuple of [TypeLibrary, str] with the library and name used, or None if it was not imported
- Return type
Tuple[TypeLibrary, str]
- mlil_functions(preload_limit: Optional[int] = None, function_generator: Optional[Generator[Function, None, None]] = None) Generator[MediumLevelILFunction, None, None] [source]¶
Generates a list of il functions. This method should be used instead of ‘functions’ property if MLIL is needed and performance is a concern.
navigate
navigates the UI to the specified virtual address in the specified ViewThe 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
- Returns
whether navigation succeeded
- Return type
- Example
>>> bv.navigate(bv.view, bv.start) True >>> bv.file.existing_views ['Mach-O', 'Raw'] >>> import binaryninjaui >>> [i.getName() for i in binaryninjaui.ViewType.getTypes()] ['Graph', 'Hex', 'Linear', 'Strings', 'Types', 'Triage', 'Bytes'] >>> bv.navigate('Graph:Mach-O', bv.entry_point) True
- never_branch(addr: int, arch: Optional[Architecture] = None) bool [source]¶
never_branch
convert the branch instruction of architecturearch
at the virtual addressaddr
to a fall through.Note
This API performs a binary patch, analysis may need to be updated afterward. Additionally the binary file must be saved in order to preserve the changes made.
- Parameters
addr (int) – virtual address of the instruction to be modified
arch (Architecture) – (optional) the architecture of the instructions if different from the default
- Returns
True on success, False on failure.
- Return type
- Example
>>> bv.get_disassembly(0x1000130e) 'jne 0x10001317' >>> bv.never_branch(0x1000130e) True >>> bv.get_disassembly(0x1000130e) 'nop' >>>
- static new(data: Optional[Union[bytes, bytearray, DataBuffer]] = None, file_metadata: Optional[FileMetadata] = None) Optional[BinaryView] [source]¶
- Parameters
data (Optional[Union[bytes, bytearray, DataBuffer]]) –
file_metadata (Optional[FileMetadata]) –
- Return type
- static open(src, file_metadata=None) Optional[BinaryView] [source]¶
- Return type
- 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 quotesSymbols 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
- Hexadecimal0n
- Decimal0
- Octal
In the case of an ambiguous number/symbol (one with no prefix) for instance
12345
we will first attempt to look up the string as a symbol, if a symbol is found its address is used, otherwise we attempt to convert it to a hexadecimal number.The following operations are valid:
+, -, \*, /, %, (), &, \|, ^, ~
In addition to the above operators there are dereference operators similar to BNIL style IL:
[<expression>]
- read the current address size at<expression>
[<expression>].b
- read the byte at<expression>
[<expression>].w
- read the word (2 bytes) at<expression>
[<expression>].d
- read the dword (4 bytes) at<expression>
[<expression>].q
- read the quadword (8 bytes) at<expression>
The
$here
(or more succinctly:$
) keyword can be used in calculations and is defined as thehere
parameter, or the currently selected addressThe
$start
/$end
keyword represents the address of the first/last bytes in the file respectively
- 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 aConstantValue [0x4000].d
can be provided given that 4 bytes can be read at0x4000
. 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
- Example
>>> psv_c = bv.parse_possiblevalueset("400", RegisterValueType.ConstantValue) >>> psv_c <const 0x400> >>> psv_ur = bv.parse_possiblevalueset("1:10:1", RegisterValueType.UnsignedRangeValue) >>> psv_ur <unsigned ranges: [<range: 0x1 to 0x10>]> >>> psv_is = bv.parse_possiblevalueset("1,2,3", RegisterValueType.InSetOfValues) >>> psv_is <in set([0x1, 0x2, 0x3])> >>>
- parse_type_string(text: str) Tuple[Type, QualifiedName] [source]¶
parse_type_string
parses string containing C into a single typeType
. In contrast to theparse_types_from_source
orparse_types_from_source_file
,parse_type_string
can only load a single type, though it can take advantage of existing type information in the binary view, while those two APIs do not.- Parameters
text (str) – C source code string of type to create
- Returns
A tuple of a
Type
and type name- Return type
- Example
>>> bv.parse_type_string("int foo") (<type: int32_t>, 'foo') >>>
- parse_types_from_string(text: str, options: Optional[List[str]] = None, include_dirs: Optional[List[str]] = None) TypeParserResult [source]¶
parse_types_from_string
parses string containing C into aTypeParserResult
objects. This API unlike theparse_types_from_source
allows the reference of types already defined in the BinaryView.- Parameters
- Returns
TypeParserResult
(a SyntaxError is thrown on parse error)- Return type
- Example
>>> bv.parse_types_from_string('int foo;\nint bar(int x);\nstruct bas{int x,y;};\n') ({types: {'bas': <type: struct bas>}, variables: {'foo': <type: int32_t>}, functions:{'bar': <type: int32_t(int32_t x)>}}, '') >>>
- perform_get_default_endianness() Endianness [source]¶
perform_get_default_endianness
implements a check which returns the Endianness of the BinaryViewNote
This method may be implemented for custom BinaryViews that are not LittleEndian.
Warning
This method must not be called directly.
- Returns
either
Endianness.LittleEndian
orEndianness.BigEndian
- Return type
- perform_get_entry_point() int [source]¶
perform_get_entry_point
implements a query for the initial entry point for code execution.Note
This method should be implemented for custom BinaryViews that are executable.
Warning
This method must not be called directly.
- Returns
the virtual address of the entry point
- Return type
- perform_get_length() int [source]¶
perform_get_length
implements a query for the size of the virtual address range used by the BinaryView.Note
This method may be overridden by custom BinaryViews. Use
add_auto_segment
to provide data without overriding this method.Warning
This method must not be called directly.
- Returns
returns the size of the virtual address range used by the BinaryView
- Return type
- perform_get_modification(addr: int) ModificationStatus [source]¶
perform_get_modification
implements query to the whether the virtual addressaddr
is modified.Note
This method may be overridden by custom BinaryViews. Use
add_auto_segment
to provide data without overriding this method.Warning
This method must not be called directly.
- Parameters
addr (int) – a virtual address to be checked
- Returns
one of the following: Original = 0, Changed = 1, Inserted = 2
- Return type
- perform_get_next_valid_offset(addr: int) int [source]¶
perform_get_next_valid_offset
implements a query for the next valid readable, writable, or executable virtual memory address.Note
This method may be overridden by custom BinaryViews. Use
add_auto_segment
to provide data without overriding this method.Warning
This method must not be called directly.
- perform_get_start() int [source]¶
perform_get_start
implements a query for the first readable, writable, or executable virtual address in the BinaryView.Note
This method may be overridden by custom BinaryViews. Use
add_auto_segment
to provide data without overriding this method.Warning
This method must not be called directly.
- Returns
returns the first virtual address in the BinaryView
- Return type
- perform_insert(addr: int, data: bytes) int [source]¶
perform_insert
implements a mapping between a virtual address and an absolute file offset, inserting the bytesdata
to rebased addressaddr
.Note
This method may be overridden by custom BinaryViews. If not overridden, inserting is disallowed
Warning
This method must not be called directly.
- perform_is_executable() bool [source]¶
perform_is_executable
implements a check which returns true if the BinaryView is executable.Note
This method must be implemented for custom BinaryViews that are executable.
Warning
This method must not be called directly.
- Returns
true if the current BinaryView is executable, false if it is not executable or on error
- Return type
- perform_is_offset_executable(addr: int) bool [source]¶
perform_is_offset_executable
implements a check if a virtual addressaddr
is executable.Note
This method may be overridden by custom BinaryViews. Use
add_auto_segment
to provide data without overriding this method.Warning
This method must not be called directly.
- perform_is_offset_readable(offset: int) bool [source]¶
perform_is_offset_readable
implements a check if a virtual address is readable.Note
This method may be overridden by custom BinaryViews. Use
add_auto_segment
to provide data without overriding this method.Warning
This method must not be called directly.
- perform_is_offset_writable(addr: int) bool [source]¶
perform_is_offset_writable
implements a check if a virtual addressaddr
is writable.Note
This method may be overridden by custom BinaryViews. Use
add_auto_segment
to provide data without overriding this method.Warning
This method must not be called directly.
- perform_is_relocatable() bool [source]¶
perform_is_relocatable
implements a check which returns true if the BinaryView is relocatable. Defaults to FalseNote
This method may be implemented for custom BinaryViews that are relocatable.
Warning
This method must not be called directly.
- Returns
True if the BinaryView is relocatable, False otherwise
- Return type
boolean
- perform_is_valid_offset(addr: int) bool [source]¶
perform_is_valid_offset
implements a check if a virtual addressaddr
is valid.Note
This method may be overridden by custom BinaryViews. Use
add_auto_segment
to provide data without overriding this method.Warning
This method must not be called directly.
- perform_read(addr: int, length: int) bytes [source]¶
perform_read
implements a mapping between a virtual address and an absolute file offset, readinglength
bytes from the rebased addressaddr
.Note
This method may be overridden by custom BinaryViews. Use
add_auto_segment
to provide data without overriding this method.Warning
This method must not be called directly.
- perform_remove(addr: int, length: int) int [source]¶
perform_remove
implements a mapping between a virtual address and an absolute file offset, removinglength
bytes from the rebased addressaddr
.Note
This method may be overridden by custom BinaryViews. If not overridden, removing data is disallowed
Warning
This method must not be called directly.
- perform_write(addr: int, data: bytes) int [source]¶
perform_write
implements a mapping between a virtual address and an absolute file offset, writing the bytesdata
to rebased addressaddr
.Note
This method may be overridden by custom BinaryViews. Use
add_auto_segment
to provide data without overriding this method.Warning
This method must not be called directly.
- query_metadata(key: str) metadata.MetadataValueType [source]¶
query_metadata retrieves a metadata associated with the given key stored in the current BinaryView.
- Parameters
key (str) – key to query
- Return type
metadata associated with the key
- Example
>>> bv.store_metadata("integer", 1337) >>> bv.query_metadata("integer") 1337L >>> bv.store_metadata("list", [1,2,3]) >>> bv.query_metadata("list") [1L, 2L, 3L] >>> bv.store_metadata("string", "my_data") >>> bv.query_metadata("string") 'my_data'
- range_contains_relocation(addr: int, size: int) bool [source]¶
Checks if the specified range overlaps with a relocation
- read(addr: int, length: int) bytes [source]¶
read
returns the data reads at mostlength
bytes from virtual addressaddr
.Note
Python2 returns a str, but Python3 returns a bytes object. str(DataBufferObject) will still get you a str in either case.
- Parameters
- Returns
at most
length
bytes from the virtual addressaddr
, empty string on error or no data- Return type
- Example
>>> #Opening a x86_64 Mach-O binary >>> bv = BinaryViewType['Raw'].open("/bin/ls") #note that we are using open instead of get_view_of_file to get the raw view >>> bv.read(0,4) b'\xcf\xfa\xed\xfe'
- read_int(address: int, size: int, sign: bool = True, endian: Optional[Endianness] = None) int [source]¶
- reader(address: Optional[int] = None) BinaryReader [source]¶
- Parameters
- Return type
- reanalyze() None [source]¶
reanalyze
causes all functions to be reanalyzed. This function does not wait for the analysis to finish.- Return type
None
- rebase(address: int, force: Optional[bool] = False, progress_func: Optional[Callable[[int, int], bool]] = None) Optional[BinaryView] [source]¶
rebase
rebase the existingBinaryView
into a newBinaryView
at the specified virtual addressNote
This method does not update corresponding UI components. If the BinaryView is associated with UI components then initiate the rebase operation within the UI, e.g. using the command palette. If working with views that are not associated with UI components while the UI is active, then set
force
toTrue
to enable rebasing.- Parameters
- Returns
the new
BinaryView
object orNone
on failure- Return type
BinaryView
orNone
- record_imported_object_library(lib: TypeLibrary, name: str, addr: int, platform: Optional[Platform] = None) None [source]¶
record_imported_object_library
should be called by custom py:py:class:BinaryView implementations when they have successfully imported an object from a type library (eg a symbol’s type). Values recorded with this function will then be queryable vialookup_imported_object_library
.- Parameters
lib (TypeLibrary) – Type Library containing the imported type
name (str) – Name of the object in the type library
addr (int) – address of symbol at import site
platform (Optional[Platform]) – Platform of symbol at import site
- Return type
None
- redo() None [source]¶
redo
redo the last committed action in the undo database.- Return type
None
- Example
>>> bv.get_disassembly(0x100012f1) 'xor eax, eax' >>> bv.begin_undo_actions() >>> bv.convert_to_nop(0x100012f1) True >>> bv.commit_undo_actions() >>> bv.get_disassembly(0x100012f1) 'nop' >>> bv.undo() >>> bv.get_disassembly(0x100012f1) 'xor eax, eax' >>> bv.redo() >>> bv.get_disassembly(0x100012f1) 'nop' >>>
- register_notification(notify: BinaryDataNotification) None [source]¶
register_notification provides a mechanism for receiving callbacks for various analysis events. A full list of callbacks can be seen in
BinaryDataNotification
.- Parameters
notify (BinaryDataNotification) – notify is a subclassed instance of
BinaryDataNotification
.- Return type
None
- register_platform_types(platform: Platform) None [source]¶
register_platform_types
ensures that the platform-specific types for aPlatform
are available for the currentBinaryView
. This is automatically performed when adding a new function or setting the default platform.- Parameters
platform (Platform) – Platform containing types to be registered
- Return type
None
- Example
>>> platform = Platform["linux-x86"] >>> bv.register_platform_types(platform) >>>
- relocation_ranges_at(addr: int) List[Tuple[int, int]] [source]¶
List of relocation range tuples for a given address
- remove(addr: int, length: int) int [source]¶
remove
removes at mostlength
bytes from virtual addressaddr
.
- remove_auto_data_tag(addr: int, tag: Tag) None [source]¶
remove_auto_data_tag
removes a Tag object at a data address.
- remove_auto_data_tags_of_type(addr: int, tag_type: TagType) None [source]¶
remove_auto_data_tags_of_type
removes all data tags at the given address of the given type.
- remove_auto_segment(start: int, length: int) None [source]¶
remove_auto_segment
removes an automatically generated segment from the current segment mapping.- Parameters
- Return type
None
Warning
This action is not persistent across saving of a BNDB and must be re-applied each time a BNDB is loaded.
- remove_component(_component: Union[Component, str]) bool [source]¶
Remove a component from the tree entirely.
- remove_expression_parser_magic_value(name: str) None [source]¶
- Parameters
name (str) –
- Return type
None
- remove_function(func: Function) None [source]¶
remove_function
removes the functionfunc
from the list of functionsWarning
This method should only be used when the function that is removed is expected to re-appear after any other analysis executes that could re-add it. Most users will want to use
remove_user_function
in their scripts.- Parameters
func (Function) – a Function object.
- Return type
None
- Example
>>> bv.functions [<func: [email protected]>] >>> bv.remove_function(next(bv.functions)) >>> bv.functions []
- remove_metadata(key: str) None [source]¶
remove_metadata removes the metadata associated with key from the current BinaryView.
- Parameters
key (str) – key associated with metadata to remove from the BinaryView
- Return type
None
- Example
>>> bv.store_metadata("integer", 1337) >>> bv.remove_metadata("integer")
- remove_tag_type(tag_type: TagType) None [source]¶
remove_tag_type
removes aTagType
and all tags that use it
- remove_user_data_ref(from_addr: int, to_addr: int) None [source]¶
remove_user_data_ref
removes a user-specified data cross-reference (xref) from the addressfrom_addr
to the addressto_addr
. This function will only remove user-specified references, not ones generated during autoanalysis. If the reference does not exist, no action is performed.
- remove_user_data_tag(addr: int, tag: Tag) None [source]¶
remove_user_data_tag
removes aTag
object at a data address. Since this removes a user tag, it will be added to the current undo buffer.
- remove_user_data_tags_of_type(addr: int, tag_type: TagType) None [source]¶
remove_user_data_tags_of_type
removes all data tags at the given address of the given type. Since this removes user tags, it will be added to the current undo buffer.
- remove_user_function(func: Function) None [source]¶
remove_user_function
removes the functionfunc
from the list of functions as a user action.Note
This API will prevent the function from being re-created if any analysis later triggers that would re-add it, unlike
remove_function
.- Parameters
func (Function) – a Function object.
- Return type
None
- Example
>>> bv.functions [<func: [email protected]>] >>> bv.remove_user_function(next(bv.functions)) >>> bv.functions []
- rename_type(old_name: _types.QualifiedNameType, new_name: _types.QualifiedNameType) None [source]¶
rename_type
renames a type in the global list of types for the currentBinaryView
- Parameters
old_name (QualifiedName) – Existing name of type to be renamed
new_name (QualifiedName) – New name of type to be renamed
- Return type
None
- Example
>>> type, name = bv.parse_type_string("int foo") >>> bv.define_user_type(name, type) >>> bv.get_type_by_name("foo") <type: int32_t> >>> bv.rename_type("foo", "bar") >>> bv.get_type_by_name("bar") <type: int32_t> >>>
- save(dest: Union[FileAccessor, str]) bool [source]¶
save
saves the original binary file to the provided destinationdest
along with any modifications.
- save_auto_snapshot(progress_func: Optional[Callable[[int, int], bool]] = None, settings: Optional[SaveSettings] = None) bool [source]¶
save_auto_snapshot
saves the current database to the already created file.Note
create_database
should have been called prior to executing this method- Parameters
progress_func (callback) – optional function to be called with the current progress and total count.
settings (SaveSettings) – optional argument for special save options.
- Returns
True if it successfully saved the snapshot, False otherwise
- Return type
- set_analysis_hold(enable: bool) None [source]¶
set_analysis_hold
control the analysis hold for this BinaryView. Enabling analysis hold defers all future analysis updates, therefore causingupdate_analysis
orupdate_analysis_and_wait
to take no action.- Return type
None
- Parameters
enable (bool) –
- set_comment_at(addr: int, comment: str) None [source]¶
set_comment_at
sets a comment for the BinaryView at the address specifiedNote that these are different from function-level comments which are specific to each
Function
. For more information, seeaddress_comments
.
- static set_default_session_data(name: str, value: str) None [source]¶
set_default_session_data
saves a variable to the BinaryView.
- set_load_settings(type_name: str, settings: Settings) None [source]¶
set_load_settings
set aSettings
object which defines the load settings for the givenBinaryViewType
type_name
- Parameters
type_name (str) – the
BinaryViewType
namesettings (Settings) – the load settings
- Return type
None
- show_graph_report(title: str, graph: FlowGraph) None [source]¶
show_graph_report
displays aFlowGraph
object graph in a new tab withtitle
.- Parameters
title (Plain text string title) – Title of the graph
graph (
FlowGraph
object) – The graph you wish to display
- Return type
None
- show_html_report(title: str, contents: str, plaintext: str = '') None [source]¶
show_html_report
displays the HTML contents in UI applications and plaintext in command-line applications. HTML reports support hyperlinking into the BinaryView. Hyperlinks can be specified as follows:binaryninja://?expr=_start
Whereexpr=
specifies an expression parsable by theparse_expression
API.Note
This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line a simple text prompt is used.
- show_markdown_report(title: str, contents: str, plaintext: str = '') None [source]¶
show_markdown_report
displays the markdown contents in UI applications and plaintext in command-line applications. Markdown reports support hyperlinking into the BinaryView. Hyperlinks can be specified as follows:binaryninja://?expr=_start
Whereexpr=
specifies an expression parsable by theparse_expression
API.Note
This API functions differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line a simple text prompt is used.