# coding=utf-8
# Copyright (c) 2015-2024 Vector 35 Inc
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.
import struct
import threading
import queue
import traceback
import ctypes
import abc
import json
import pprint
import inspect
import os
import uuid
from typing import Callable, Generator, Optional, Union, Tuple, List, Mapping, Any, \
Iterator, Iterable, KeysView, ItemsView, ValuesView, Dict, overload
from dataclasses import dataclass
from enum import IntFlag
import collections
from collections import defaultdict, OrderedDict, deque
# Binary Ninja components
import binaryninja
from . import _binaryninjacore as core
from . import decorators
from .enums import (
AnalysisState, SymbolType, Endianness, ModificationStatus, StringType, SegmentFlag, SectionSemantics, FindFlag,
TypeClass, BinaryViewEventType, FunctionGraphType, TagReferenceType, TagTypeType, RegisterValueType, DisassemblyOption,
RelocationType
)
from .exceptions import RelocationWriteException, ILException, ExternalLinkException
from . import associateddatastore # required for _BinaryViewAssociatedDataStore
from .log import log_warn, log_error, Logger
from . import typelibrary
from . import fileaccessor
from . import databuffer
from . import basicblock
from . import component
from . import lineardisassembly
from . import metadata
from . import highlight
from . import settings
from . import variable
from . import architecture
from . import filemetadata
from . import lowlevelil
from . import mainthread
from . import mediumlevelil
from . import highlevelil
from . import debuginfo
from . import flowgraph
from . import project
from . import typearchive
# The following are imported as such to allow the type checker disambiguate the module name
# from properties and methods of the same name
from . import workflow as _workflow
from . import function as _function
from . import types as _types
from . import platform as _platform
from . import deprecation
from . import typecontainer
from . import externallibrary
from . import project
from . import undo
PathType = Union[str, os.PathLike]
InstructionsType = Generator[Tuple[List['_function.InstructionTextToken'], int], None, None]
NotificationType = Mapping['BinaryDataNotification', 'BinaryDataNotificationCallbacks']
ProgressFuncType = Callable[[int, int], bool]
DataMatchCallbackType = Callable[[int, 'databuffer.DataBuffer'], bool]
LineMatchCallbackType = Callable[[int, 'lineardisassembly.LinearDisassemblyLine'], bool]
StringOrType = Union[str, '_types.Type', '_types.TypeBuilder']
[docs]
@dataclass(frozen=True)
class ReferenceSource:
function: Optional['_function.Function']
arch: Optional['architecture.Architecture']
address: int
def __repr__(self):
if self.arch:
return f"<ref: {self.arch.name}@{self.address:#x}>"
else:
return f"<ref: {self.address:#x}>"
@classmethod
def _from_core_struct(cls, view: 'BinaryView', ref: core.BNReferenceSource) -> 'ReferenceSource':
if ref.func:
func = _function.Function(view, core.BNNewFunctionReference(ref.func))
else:
func = None
if ref.arch:
arch = architecture.CoreArchitecture._from_cache(ref.arch)
else:
arch = None
return ReferenceSource(func, arch, ref.addr)
@property
def llil(self) -> Optional[lowlevelil.LowLevelILInstruction]:
"""Returns the low level il instruction at the current location if one exists"""
if self.function is None or self.arch is None:
return None
return self.function.get_low_level_il_at(self.address, self.arch)
@property
def mlil(self) -> Optional[mediumlevelil.MediumLevelILInstruction]:
"""Returns the medium level il instruction at the current location if one exists"""
llil = self.llil
return llil.mlil if llil is not None else None
@property
def hlil(self) -> Optional[highlevelil.HighLevelILInstruction]:
"""Returns the high level il instruction at the current location if one exists"""
mlil = self.mlil
return mlil.hlil if mlil is not None else None
[docs]
class NotificationType(IntFlag):
NotificationBarrier = 1 << 0
DataWritten = 1 << 1
DataInserted = 1 << 2
DataRemoved = 1 << 3
FunctionAdded = 1 << 4
FunctionRemoved = 1 << 5
FunctionUpdated = 1 << 6
FunctionUpdateRequested = 1 << 7
DataVariableAdded = 1 << 8
DataVariableRemoved = 1 << 9
DataVariableUpdated = 1 << 10
DataMetadataUpdated = 1 << 11
TagTypeUpdated = 1 << 12
TagAdded = 1 << 13
TagRemoved = 1 << 14
TagUpdated = 1 << 15
SymbolAdded = 1 << 16
SymbolRemoved = 1 << 17
SymbolUpdated = 1 << 18
StringFound = 1 << 19
StringRemoved = 1 << 20
TypeDefined = 1 << 21
TypeUndefined = 1 << 22
TypeReferenceChanged = 1 << 23
TypeFieldReferenceChanged = 1 << 24
SegmentAdded = 1 << 25
SegmentRemoved = 1 << 26
SegmentUpdated = 1 << 27
SectionAdded = 1 << 28
SectionRemoved = 1 << 29
SectionUpdated = 1 << 30
ComponentNameUpdated = 1 << 31
ComponentAdded = 1 << 32
ComponentRemoved = 1 << 33
ComponentMoved = 1 << 34
ComponentFunctionAdded = 1 << 35
ComponentFunctionRemoved = 1 << 36
ComponentDataVariableAdded = 1 << 37
ComponentDataVariableRemoved = 1 << 38
ExternalLibraryAdded = 1 << 39
ExternalLibraryRemoved = 1 << 40
ExternalLibraryUpdated = 1 << 41
ExternalLocationAdded = 1 << 42
ExternalLocationRemoved = 1 << 43
ExternalLocationUpdated = 1 << 44
TypeArchiveAttached = 1 << 45
TypeArchiveDetached = 1 << 46
TypeArchiveConnected = 1 << 47
TypeArchiveDisconnected = 1 << 48
UndoEntryAdded = 1 << 49
UndoEntryTaken = 1 << 50
RedoEntryTaken = 1 << 51
BinaryDataUpdates = DataWritten | DataInserted | DataRemoved
FunctionLifetime = FunctionAdded | FunctionRemoved
FunctionUpdates = FunctionLifetime | FunctionUpdated
DataVariableLifetime = DataVariableAdded | DataVariableRemoved
DataVariableUpdates = DataVariableLifetime | DataVariableUpdated
TagLifetime = TagAdded | TagRemoved
TagUpdates = TagLifetime | TagUpdated
SymbolLifetime = SymbolAdded | SymbolRemoved
SymbolUpdates = SymbolLifetime | SymbolUpdated
StringUpdates = StringFound | StringRemoved
TypeLifetime = TypeDefined | TypeUndefined
TypeUpdates = TypeLifetime | TypeReferenceChanged | TypeFieldReferenceChanged
SegmentLifetime = SegmentAdded | SegmentRemoved
SegmentUpdates = SegmentLifetime | SegmentUpdated
SectionLifetime = SectionAdded | SectionRemoved
SectionUpdates = SectionLifetime | SectionUpdated
ComponentUpdates = ComponentAdded | ComponentRemoved | ComponentMoved | ComponentFunctionAdded | ComponentFunctionRemoved | ComponentDataVariableAdded | ComponentDataVariableRemoved
ExternalLibraryLifetime = ExternalLibraryAdded | ExternalLibraryRemoved
ExternalLibraryUpdates = ExternalLibraryLifetime | ExternalLibraryUpdated
ExternalLocationLifetime = ExternalLocationAdded | ExternalLocationRemoved
ExternalLocationUpdates = ExternalLocationLifetime | ExternalLocationUpdated
TypeArchiveUpdates = TypeArchiveAttached | TypeArchiveDetached | TypeArchiveConnected | TypeArchiveDisconnected
UndoUpdates = UndoEntryAdded | UndoEntryTaken | RedoEntryTaken
[docs]
class BinaryDataNotification:
"""
``class BinaryDataNotification`` provides an interface for receiving event notifications. Usage requires inheriting
from this interface, overriding the relevant event handlers, and registering the `BinaryDataNotification` instance
with a `BinaryView` using the `register_notification` method.
By default, a `BinaryDataNotification` instance receives notifications for all available notification types. It
is recommended for users of this interface to initialize the `BinaryDataNotification` base class with specific
callbacks of interest by passing the appropriate `NotificationType` flags into the `__init__` constructor.
Handlers provided by the user should aim to limit the amount of processing within the callback. The
callback context holds a global lock, preventing other threads from making progress during the callback phase.
While most of the API can be used safely during this time, care must be taken when issuing a call that can block,
as waiting for a thread requiring the global lock can result in deadlock.
The `NotificationBarrier` is a special `NotificationType` that is disabled by default. To enable it, the
`NotificationBarrier` flag must be passed to `__init__`. This notification is designed to facilitate efficient
batch processing of other notification types. The idea is to collect other notifications of interest into a cache,
which can be very efficient as it doesn't require additional locks. After some time, the core generates a
`NotificationBarrier` event, providing a safe context to move the cache for processing by a different thread.
To control the time of the next `NotificationBarrier` event, return the desired number of milliseconds until
the next event from the `NotificationBarrier` callback. Returning zero quiesces future `NotificationBarrier`
events. If the `NotificationBarrier` is quiesced, the reception of a new callback of interest automatically
generates a new `NotificationBarrier` call after that notification is delivered. This mechanism effectively
allows throttling and quiescing when necessary.
.. note:: Note that the core generates a `NotificationBarrier` as part of the `BinaryDataNotification` registration \
process. Registering the same `BinaryDataNotification` instance again results in a gratuitous `NotificationBarrier` \
event, which can be useful in situations requiring a safe context for processing due to some other asynchronous \
event (e.g., user interaction).
:Example:
>>> class NotifyTest(binaryninja.BinaryDataNotification):
... def __init__(self):
... super(NotifyTest, self).__init__(binaryninja.NotificationType.NotificationBarrier | binaryninja.NotificationType.FunctionLifetime | binaryninja.NotificationType.FunctionUpdated)
... self.received_event = False
... def notification_barrier(self, view: 'BinaryView') -> int:
... has_events = self.received_event
... self.received_event = False
... log_info("notification_barrier")
... if has_events:
... return 250
... else:
... return 0
... def function_added(self, view: 'BinaryView', func: '_function.Function') -> None:
... self.received_event = True
... log_info("function_added")
... def function_removed(self, view: 'BinaryView', func: '_function.Function') -> None:
... self.received_event = True
... log_info("function_removed")
... def function_updated(self, view: 'BinaryView', func: '_function.Function') -> None:
... self.received_event = True
... log_info("function_updated")
...
>>>
>>> bv.register_notification(NotifyTest())
>>>
"""
def __init__(self, notifications: NotificationType = None):
self.notifications = notifications
[docs]
def notification_barrier(self, view: 'BinaryView') -> int:
return 0
[docs]
def data_written(self, view: 'BinaryView', offset: int, length: int) -> None:
pass
[docs]
def data_inserted(self, view: 'BinaryView', offset: int, length: int) -> None:
pass
[docs]
def data_removed(self, view: 'BinaryView', offset: int, length: int) -> None:
pass
[docs]
def function_added(self, view: 'BinaryView', func: '_function.Function') -> None:
"""
.. note:: `function_updated` will be triggered instead when a user function is added over an auto function.
"""
pass
[docs]
def function_removed(self, view: 'BinaryView', func: '_function.Function') -> None:
"""
.. note:: `function_updated` will be triggered instead when a user function is removed over an auto function.
"""
pass
[docs]
def function_updated(self, view: 'BinaryView', func: '_function.Function') -> None:
pass
[docs]
def function_update_requested(self, view: 'BinaryView', func: '_function.Function') -> None:
pass
[docs]
def data_var_added(self, view: 'BinaryView', var: 'DataVariable') -> None:
"""
.. note:: `data_var_updated` will be triggered instead when a user data variable is added over an auto data variable.
"""
pass
[docs]
def data_var_removed(self, view: 'BinaryView', var: 'DataVariable') -> None:
"""
.. note:: `data_var_updated` will be triggered instead when a user data variable is removed over an auto data variable.
"""
pass
[docs]
def data_var_updated(self, view: 'BinaryView', var: 'DataVariable') -> None:
pass
[docs]
def tag_type_updated(self, view: 'BinaryView', tag_type) -> None:
pass
[docs]
def tag_added(
self, view: 'BinaryView', tag: 'Tag', ref_type: TagReferenceType, auto_defined: bool,
arch: Optional['architecture.Architecture'], func: Optional[_function.Function], addr: int
) -> None:
pass
[docs]
def tag_updated(
self, view: 'BinaryView', tag: 'Tag', ref_type: TagReferenceType, auto_defined: bool,
arch: Optional['architecture.Architecture'], func: Optional[_function.Function], addr: int
) -> None:
pass
[docs]
def tag_removed(
self, view: 'BinaryView', tag: 'Tag', ref_type: TagReferenceType, auto_defined: bool,
arch: Optional['architecture.Architecture'], func: Optional[_function.Function], addr: int
) -> None:
pass
[docs]
def symbol_added(self, view: 'BinaryView', sym: '_types.CoreSymbol') -> None:
pass
[docs]
def symbol_updated(self, view: 'BinaryView', sym: '_types.CoreSymbol') -> None:
pass
[docs]
def symbol_removed(self, view: 'BinaryView', sym: '_types.CoreSymbol') -> None:
pass
[docs]
def string_found(self, view: 'BinaryView', string_type: StringType, offset: int, length: int) -> None:
pass
[docs]
def string_removed(self, view: 'BinaryView', string_type: StringType, offset: int, length: int) -> None:
pass
[docs]
def type_defined(self, view: 'BinaryView', name: '_types.QualifiedName', type: '_types.Type') -> None:
pass
[docs]
def type_undefined(self, view: 'BinaryView', name: '_types.QualifiedName', type: '_types.Type') -> None:
pass
[docs]
def type_ref_changed(self, view: 'BinaryView', name: '_types.QualifiedName', type: '_types.Type') -> None:
pass
[docs]
def type_field_ref_changed(self, view: 'BinaryView', name: '_types.QualifiedName', offset: int) -> None:
pass
[docs]
def segment_added(self, view: 'BinaryView', segment: 'Segment') -> None:
pass
[docs]
def segment_updated(self, view: 'BinaryView', segment: 'Segment') -> None:
pass
[docs]
def segment_removed(self, view: 'BinaryView', segment: 'Segment') -> None:
pass
[docs]
def section_added(self, view: 'BinaryView', section: 'Section') -> None:
pass
[docs]
def section_updated(self, view: 'BinaryView', section: 'Section') -> None:
pass
[docs]
def section_removed(self, view: 'BinaryView', section: 'Section') -> None:
pass
[docs]
def component_added(self, view: 'BinaryView', _component: component.Component) -> None:
pass
[docs]
def component_removed(self, view: 'BinaryView', formerParent: component.Component,
_component: component.Component) -> None:
pass
[docs]
def component_name_updated(self, view: 'BinaryView', previous_name: str, _component: component.Component) -> None:
pass
[docs]
def component_moved(self, view: 'BinaryView', formerParent: component.Component, newParent: component.Component,
_component: component.Component) -> None:
pass
[docs]
def component_function_added(self, view: 'BinaryView', _component: component.Component, func: '_function.Function'):
pass
[docs]
def component_function_removed(self, view: 'BinaryView', _component: component.Component,
func: '_function.Function'):
pass
[docs]
def component_data_var_added(self, view: 'BinaryView', _component: component.Component, var: 'DataVariable'):
pass
[docs]
def component_data_var_removed(self, view: 'BinaryView', _component: component.Component, var: 'DataVariable'):
pass
[docs]
def type_archive_attached(self, view: 'BinaryView', id: str, path: str):
pass
[docs]
def type_archive_detached(self, view: 'BinaryView', id: str, path: str):
pass
[docs]
def type_archive_connected(self, view: 'BinaryView', archive: 'typearchive.TypeArchive'):
pass
[docs]
def type_archive_disconnected(self, view: 'BinaryView', archive: 'typearchive.TypeArchive'):
pass
[docs]
def undo_entry_added(self, view: 'BinaryView', entry: 'undo.UndoEntry'):
pass
[docs]
def undo_entry_taken(self, view: 'BinaryView', entry: 'undo.UndoEntry'):
pass
[docs]
def redo_entry_taken(self, view: 'BinaryView', entry: 'undo.UndoEntry'):
pass
[docs]
class StringReference:
_decodings = {
StringType.AsciiString: "ascii", StringType.Utf8String: "utf-8", StringType.Utf16String: "utf-16",
StringType.Utf32String: "utf-32",
}
def __init__(self, bv: 'BinaryView', string_type: StringType, start: int, length: int):
self._type = string_type
self._start = start
self._length = length
self._view = bv
def __repr__(self):
return f"<{self._type.name}: {self._start:#x}, len {self._length:#x}>"
def __str__(self):
return self.value
def __len__(self):
return self._length
@property
def value(self) -> str:
return self._view.read(self._start, self._length).decode(self._decodings[self._type])
@property
def raw(self) -> bytes:
return self._view.read(self._start, self._length)
@property
def type(self) -> StringType:
return self._type
@property
def start(self) -> int:
return self._start
@property
def length(self) -> int:
return self._length
@property
def view(self) -> 'BinaryView':
return self._view
[docs]
class AnalysisCompletionEvent:
"""
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)
>>>
"""
_pending_analysis_completion_events = {}
def __init__(
self, view: 'BinaryView', callback: Union[Callable[['AnalysisCompletionEvent'], None], Callable[[], None]]
):
self._view = view
self.callback = callback
self._cb = ctypes.CFUNCTYPE(None, ctypes.c_void_p)(self._notify)
self.handle = core.BNAddAnalysisCompletionEvent(self._view.handle, None, self._cb)
self.__class__._pending_analysis_completion_events[id(self)] = self
def __del__(self):
if id(self) in self.__class__._pending_analysis_completion_events:
del self.__class__._pending_analysis_completion_events[id(self)]
if core is not None:
core.BNFreeAnalysisCompletionEvent(self.handle)
def _notify(self, ctxt):
if id(self) in self.__class__._pending_analysis_completion_events:
del self.__class__._pending_analysis_completion_events[id(self)]
try:
arg_offset = inspect.ismethod(self.callback)
callback_spec = inspect.getfullargspec(self.callback)
if len(callback_spec.args) > arg_offset:
self.callback(self) # type: ignore
else:
self.callback() # type: ignore
except:
log_error(traceback.format_exc())
def _empty_callback(self):
pass
[docs]
def cancel(self) -> None:
"""
The ``cancel`` method will cancel analysis for an :py:class:`AnalysisCompletionEvent`.
.. warning:: This method should only be used when the system is being shut down and no further analysis should be done afterward.
"""
self.callback = self._empty_callback
core.BNCancelAnalysisCompletionEvent(self.handle)
if id(self) in self.__class__._pending_analysis_completion_events:
del self.__class__._pending_analysis_completion_events[id(self)]
@property
def view(self) -> 'BinaryView':
return self._view
[docs]
class BinaryViewEvent:
"""
The ``BinaryViewEvent`` object provides a mechanism for receiving callbacks when a BinaryView
is Finalized or the initial analysis is finished. The BinaryView finalized callbacks run before the
initial analysis starts. The callbacks run one-after-another in the same order as they get registered.
It is a good place to modify the BinaryView to add extra information to it.
For newly opened binaries, the initial analysis completion callbacks run after the initial analysis,
as well as linear sweep and signature matcher (if they are configured to run), completed. For loading
old databases, the callbacks run after the database is loaded, as well as any automatic analysis
update finishes.
The callback function receives a BinaryView as its parameter. It is possible to call
BinaryView.add_analysis_completion_event() on it to set up other callbacks for analysis completion.
:Example:
>>> def callback(bv):
... print('start: 0x%x' % bv.start)
...
>>> BinaryViewType.add_binaryview_finalized_event(callback)
"""
BinaryViewEventCallback = Callable[['BinaryView'], None]
# This has no functional purposes;
# we just need it to stop Python from prematurely freeing the object
_binaryview_events = {}
[docs]
@classmethod
def register(cls, event_type: BinaryViewEventType, callback: BinaryViewEventCallback) -> None:
callback_obj = ctypes.CFUNCTYPE(None, ctypes.c_void_p,
ctypes.POINTER(core.BNBinaryView
))(lambda ctxt, view: cls._notify(view, callback))
core.BNRegisterBinaryViewEvent(event_type, callback_obj, None)
cls._binaryview_events[len(cls._binaryview_events)] = callback_obj
@staticmethod
def _notify(view: core.BNBinaryViewHandle, callback: BinaryViewEventCallback) -> None:
try:
file_metadata = filemetadata.FileMetadata(handle=core.BNGetFileForView(view))
view_obj = BinaryView(file_metadata=file_metadata, handle=core.BNNewViewReference(view))
callback(view_obj)
except:
log_error(traceback.format_exc())
[docs]
@dataclass(frozen=True)
class ActiveAnalysisInfo:
func: '_function.Function'
analysis_time: int
update_count: int
submit_count: int
def __repr__(self):
return f"<ActiveAnalysisInfo {self.func}, analysis_time {self.analysis_time}, update_count {self.update_count}, submit_count {self.submit_count}>"
[docs]
@dataclass(frozen=True)
class AnalysisInfo:
state: AnalysisState
analysis_time: int
active_info: List[ActiveAnalysisInfo]
def __repr__(self):
return f"<AnalysisInfo {self.state}, analysis_time {self.analysis_time}, active_info {self.active_info}>"
[docs]
@dataclass(frozen=True)
class AnalysisProgress:
state: AnalysisState
count: int
total: int
def __str__(self):
if self.state == AnalysisState.InitialState:
return "Initial"
if self.state == AnalysisState.HoldState:
return "Hold"
if self.state == AnalysisState.IdleState:
return "Idle"
if self.state == AnalysisState.DisassembleState:
return "Disassembling (%d/%d)" % (self.count, self.total)
if self.state == AnalysisState.AnalyzeState:
return "Analyzing (%d/%d)" % (self.count, self.total)
return "Extended Analysis"
def __repr__(self):
return f"<progress: {self}>"
[docs]
class BinaryDataNotificationCallbacks:
def __init__(self, view: 'BinaryView', notify: 'BinaryDataNotification'):
self._view = view
self._notify = notify
self._cb = core.BNBinaryDataNotification()
self._cb.context = 0
if (not hasattr(notify, 'notifications')) or (hasattr(notify, 'notifications') and notify.notifications is None):
self._cb.notificationBarrier = self._cb.notificationBarrier
self._cb.dataWritten = self._cb.dataWritten.__class__(self._data_written)
self._cb.dataInserted = self._cb.dataInserted.__class__(self._data_inserted)
self._cb.dataRemoved = self._cb.dataRemoved.__class__(self._data_removed)
self._cb.functionAdded = self._cb.functionAdded.__class__(self._function_added)
self._cb.functionRemoved = self._cb.functionRemoved.__class__(self._function_removed)
self._cb.functionUpdated = self._cb.functionUpdated.__class__(self._function_updated)
self._cb.functionUpdateRequested = self._cb.functionUpdateRequested.__class__(self._function_update_requested)
self._cb.dataVariableAdded = self._cb.dataVariableAdded.__class__(self._data_var_added)
self._cb.dataVariableRemoved = self._cb.dataVariableRemoved.__class__(self._data_var_removed)
self._cb.dataVariableUpdated = self._cb.dataVariableUpdated.__class__(self._data_var_updated)
self._cb.dataMetadataUpdated = self._cb.dataMetadataUpdated.__class__(self._data_metadata_updated)
self._cb.tagTypeUpdated = self._cb.tagTypeUpdated.__class__(self._tag_type_updated)
self._cb.tagAdded = self._cb.tagAdded.__class__(self._tag_added)
self._cb.tagRemoved = self._cb.tagRemoved.__class__(self._tag_removed)
self._cb.tagUpdated = self._cb.tagUpdated.__class__(self._tag_updated)
self._cb.symbolAdded = self._cb.symbolAdded.__class__(self._symbol_added)
self._cb.symbolRemoved = self._cb.symbolRemoved.__class__(self._symbol_removed)
self._cb.symbolUpdated = self._cb.symbolUpdated.__class__(self._symbol_updated)
self._cb.stringFound = self._cb.stringFound.__class__(self._string_found)
self._cb.stringRemoved = self._cb.stringRemoved.__class__(self._string_removed)
self._cb.typeDefined = self._cb.typeDefined.__class__(self._type_defined)
self._cb.typeUndefined = self._cb.typeUndefined.__class__(self._type_undefined)
self._cb.typeReferenceChanged = self._cb.typeReferenceChanged.__class__(self._type_ref_changed)
self._cb.typeFieldReferenceChanged = self._cb.typeFieldReferenceChanged.__class__(self._type_field_ref_changed)
self._cb.segmentAdded = self._cb.segmentAdded.__class__(self._segment_added)
self._cb.segmentRemoved = self._cb.segmentRemoved.__class__(self._segment_removed)
self._cb.segmentUpdated = self._cb.segmentUpdated.__class__(self._segment_updated)
self._cb.sectionAdded = self._cb.sectionAdded.__class__(self._section_added)
self._cb.sectionRemoved = self._cb.sectionRemoved.__class__(self._section_removed)
self._cb.sectionUpdated = self._cb.sectionUpdated.__class__(self._section_updated)
self._cb.componentNameUpdated = self._cb.componentNameUpdated.__class__(self._component_name_updated)
self._cb.componentAdded = self._cb.componentAdded.__class__(self._component_added)
self._cb.componentRemoved = self._cb.componentRemoved.__class__(self._component_removed)
self._cb.componentMoved = self._cb.componentMoved.__class__(self._component_moved)
self._cb.componentFunctionAdded = self._cb.componentFunctionAdded.__class__(self._component_function_added)
self._cb.componentFunctionRemoved = self._cb.componentFunctionRemoved.__class__(self._component_function_removed)
self._cb.componentDataVariableAdded = self._cb.componentDataVariableAdded.__class__(self._component_data_variable_added)
self._cb.componentDataVariableRemoved = self._cb.componentDataVariableRemoved.__class__(self._component_data_variable_removed)
self._cb.typeArchiveAttached = self._cb.typeArchiveAttached.__class__(self._type_archive_attached)
self._cb.typeArchiveDetached = self._cb.typeArchiveDetached.__class__(self._type_archive_detached)
self._cb.typeArchiveConnected = self._cb.typeArchiveConnected.__class__(self._type_archive_connected)
self._cb.typeArchiveDisconnected = self._cb.typeArchiveDisconnected.__class__(self._type_archive_disconnected)
self._cb.undoEntryAdded = self._cb.undoEntryAdded.__class__(self._undo_entry_added)
self._cb.undoEntryTaken = self._cb.undoEntryTaken.__class__(self._undo_entry_taken)
self._cb.redoEntryTaken = self._cb.redoEntryTaken.__class__(self._redo_entry_taken)
else:
if notify.notifications & NotificationType.NotificationBarrier:
self._cb.notificationBarrier = self._cb.notificationBarrier.__class__(self._notification_barrier)
if notify.notifications & NotificationType.DataWritten:
self._cb.dataWritten = self._cb.dataWritten.__class__(self._data_written)
if notify.notifications & NotificationType.DataInserted:
self._cb.dataInserted = self._cb.dataInserted.__class__(self._data_inserted)
if notify.notifications & NotificationType.DataRemoved:
self._cb.dataRemoved = self._cb.dataRemoved.__class__(self._data_removed)
if notify.notifications & NotificationType.FunctionAdded:
self._cb.functionAdded = self._cb.functionAdded.__class__(self._function_added)
if notify.notifications & NotificationType.FunctionRemoved:
self._cb.functionRemoved = self._cb.functionRemoved.__class__(self._function_removed)
if notify.notifications & NotificationType.FunctionUpdated:
self._cb.functionUpdated = self._cb.functionUpdated.__class__(self._function_updated)
if notify.notifications & NotificationType.FunctionUpdateRequested:
self._cb.functionUpdateRequested = self._cb.functionUpdateRequested.__class__(self._function_update_requested)
if notify.notifications & NotificationType.DataVariableAdded:
self._cb.dataVariableAdded = self._cb.dataVariableAdded.__class__(self._data_var_added)
if notify.notifications & NotificationType.DataVariableRemoved:
self._cb.dataVariableRemoved = self._cb.dataVariableRemoved.__class__(self._data_var_removed)
if notify.notifications & NotificationType.DataVariableUpdated:
self._cb.dataVariableUpdated = self._cb.dataVariableUpdated.__class__(self._data_var_updated)
if notify.notifications & NotificationType.DataMetadataUpdated:
self._cb.dataMetadataUpdated = self._cb.dataMetadataUpdated.__class__(self._data_metadata_updated)
if notify.notifications & NotificationType.TagTypeUpdated:
self._cb.tagTypeUpdated = self._cb.tagTypeUpdated.__class__(self._tag_type_updated)
if notify.notifications & NotificationType.TagAdded:
self._cb.tagAdded = self._cb.tagAdded.__class__(self._tag_added)
if notify.notifications & NotificationType.TagRemoved:
self._cb.tagRemoved = self._cb.tagRemoved.__class__(self._tag_removed)
if notify.notifications & NotificationType.TagUpdated:
self._cb.tagUpdated = self._cb.tagUpdated.__class__(self._tag_updated)
if notify.notifications & NotificationType.SymbolAdded:
self._cb.symbolAdded = self._cb.symbolAdded.__class__(self._symbol_added)
if notify.notifications & NotificationType.SymbolRemoved:
self._cb.symbolRemoved = self._cb.symbolRemoved.__class__(self._symbol_removed)
if notify.notifications & NotificationType.SymbolUpdated:
self._cb.symbolUpdated = self._cb.symbolUpdated.__class__(self._symbol_updated)
if notify.notifications & NotificationType.StringFound:
self._cb.stringFound = self._cb.stringFound.__class__(self._string_found)
if notify.notifications & NotificationType.StringRemoved:
self._cb.stringRemoved = self._cb.stringRemoved.__class__(self._string_removed)
if notify.notifications & NotificationType.TypeDefined:
self._cb.typeDefined = self._cb.typeDefined.__class__(self._type_defined)
if notify.notifications & NotificationType.TypeUndefined:
self._cb.typeUndefined = self._cb.typeUndefined.__class__(self._type_undefined)
if notify.notifications & NotificationType.TypeReferenceChanged:
self._cb.typeReferenceChanged = self._cb.typeReferenceChanged.__class__(self._type_ref_changed)
if notify.notifications & NotificationType.TypeFieldReferenceChanged:
self._cb.typeFieldReferenceChanged = self._cb.typeFieldReferenceChanged.__class__(self._type_field_ref_changed)
if notify.notifications & NotificationType.SegmentAdded:
self._cb.segmentAdded = self._cb.segmentAdded.__class__(self._segment_added)
if notify.notifications & NotificationType.SegmentRemoved:
self._cb.segmentRemoved = self._cb.segmentRemoved.__class__(self._segment_removed)
if notify.notifications & NotificationType.SegmentUpdated:
self._cb.segmentUpdated = self._cb.segmentUpdated.__class__(self._segment_updated)
if notify.notifications & NotificationType.SectionAdded:
self._cb.sectionAdded = self._cb.sectionAdded.__class__(self._section_added)
if notify.notifications & NotificationType.SectionRemoved:
self._cb.sectionRemoved = self._cb.sectionRemoved.__class__(self._section_removed)
if notify.notifications & NotificationType.SectionUpdated:
self._cb.sectionUpdated = self._cb.sectionUpdated.__class__(self._section_updated)
if notify.notifications & NotificationType.ComponentNameUpdated:
self._cb.componentNameUpdated = self._cb.componentNameUpdated.__class__(self._component_name_updated)
if notify.notifications & NotificationType.ComponentAdded:
self._cb.componentAdded = self._cb.componentAdded.__class__(self._component_added)
if notify.notifications & NotificationType.ComponentRemoved:
self._cb.componentRemoved = self._cb.componentRemoved.__class__(self._component_removed)
if notify.notifications & NotificationType.ComponentMoved:
self._cb.componentMoved = self._cb.componentMoved.__class__(self._component_moved)
if notify.notifications & NotificationType.ComponentFunctionAdded:
self._cb.componentFunctionAdded = self._cb.componentFunctionAdded.__class__(self._component_function_added)
if notify.notifications & NotificationType.ComponentFunctionRemoved:
self._cb.componentFunctionRemoved = self._cb.componentFunctionRemoved.__class__(self._component_function_removed)
if notify.notifications & NotificationType.ComponentDataVariableAdded:
self._cb.componentDataVariableAdded = self._cb.componentDataVariableAdded.__class__(self._component_data_variable_added)
if notify.notifications & NotificationType.ComponentDataVariableRemoved:
self._cb.componentDataVariableRemoved = self._cb.componentDataVariableRemoved.__class__(self._component_data_variable_removed)
if notify.notifications & NotificationType.TypeArchiveAttached:
self._cb.typeArchiveAttached = self._cb.typeArchiveAttached.__class__(self._type_archive_attached)
if notify.notifications & NotificationType.TypeArchiveDetached:
self._cb.typeArchiveDetached = self._cb.typeArchiveDetached.__class__(self._type_archive_detached)
if notify.notifications & NotificationType.TypeArchiveConnected:
self._cb.typeArchiveConnected = self._cb.typeArchiveConnected.__class__(self._type_archive_connected)
if notify.notifications & NotificationType.TypeArchiveDisconnected:
self._cb.typeArchiveDisconnected = self._cb.typeArchiveDisconnected.__class__(self._type_archive_disconnected)
if notify.notifications & NotificationType.UndoEntryAdded:
self._cb.undoEntryAdded = self._cb.undoEntryAdded.__class__(self._undo_entry_added)
if notify.notifications & NotificationType.UndoEntryTaken:
self._cb.undoEntryTaken = self._cb.undoEntryTaken.__class__(self._undo_entry_taken)
if notify.notifications & NotificationType.RedoEntryTaken:
self._cb.redoEntryTaken = self._cb.redoEntryTaken.__class__(self._redo_entry_taken)
def _register(self) -> None:
core.BNRegisterDataNotification(self._view.handle, self._cb)
def _unregister(self) -> None:
core.BNUnregisterDataNotification(self._view.handle, self._cb)
def _notification_barrier(self, ctxt, view: core.BNBinaryView) -> int:
try:
return self._notify.notification_barrier(self._view)
except OSError:
log_error(traceback.format_exc())
def _data_written(self, ctxt, view: core.BNBinaryView, offset: int, length: int) -> None:
try:
self._notify.data_written(self._view, offset, length)
except OSError:
log_error(traceback.format_exc())
def _data_inserted(self, ctxt, view: core.BNBinaryView, offset: int, length: int) -> None:
try:
self._notify.data_inserted(self._view, offset, length)
except:
log_error(traceback.format_exc())
def _data_removed(self, ctxt, view: core.BNBinaryView, offset: int, length: int) -> None:
try:
self._notify.data_removed(self._view, offset, length)
except:
log_error(traceback.format_exc())
def _function_added(self, ctxt, view: core.BNBinaryView, func: core.BNFunctionHandle) -> None:
try:
self._notify.function_added(self._view, _function.Function(self._view, core.BNNewFunctionReference(func)))
except:
log_error(traceback.format_exc())
def _function_removed(self, ctxt, view: core.BNBinaryView, func: core.BNFunctionHandle) -> None:
try:
self._notify.function_removed(self._view, _function.Function(self._view, core.BNNewFunctionReference(func)))
except:
log_error(traceback.format_exc())
def _function_updated(self, ctxt, view: core.BNBinaryView, func: core.BNFunctionHandle) -> None:
try:
self._notify.function_updated(self._view, _function.Function(self._view, core.BNNewFunctionReference(func)))
except:
log_error(traceback.format_exc())
def _function_update_requested(self, ctxt, view: core.BNBinaryView, func: core.BNFunctionHandle) -> None:
try:
self._notify.function_update_requested(
self._view, _function.Function(self._view, core.BNNewFunctionReference(func))
)
except:
log_error(traceback.format_exc())
def _data_var_added(self, ctxt, view: core.BNBinaryView, var: core.BNDataVariableHandle) -> None:
try:
self._notify.data_var_added(self._view, DataVariable.from_core_struct(var[0], self._view))
except:
log_error(traceback.format_exc())
def _data_var_removed(self, ctxt, view: core.BNBinaryView, var: core.BNDataVariableHandle) -> None:
try:
self._notify.data_var_removed(self._view, DataVariable.from_core_struct(var[0], self._view))
except:
log_error(traceback.format_exc())
def _data_var_updated(self, ctxt, view: core.BNBinaryView, var: core.BNDataVariableHandle) -> None:
try:
self._notify.data_var_updated(self._view, DataVariable.from_core_struct(var[0], self._view))
except:
log_error(traceback.format_exc())
def _data_metadata_updated(self, ctxt, view: core.BNBinaryView, offset: int) -> None:
try:
self._notify.data_metadata_updated(self._view, offset)
except:
log_error(traceback.format_exc())
def _tag_type_updated(self, ctxt, view: core.BNBinaryView, tag_type: core.BNTagTypeHandle) -> None:
try:
core_tag_type = core.BNNewTagTypeReference(tag_type)
assert core_tag_type is not None, "core.BNNewTagTypeReference returned None"
self._notify.tag_type_updated(self._view, TagType(core_tag_type))
except:
log_error(traceback.format_exc())
def _tag_added(self, ctxt, view: core.BNBinaryView, tag_ref: core.BNTagReferenceHandle) -> None:
try:
ref_type = tag_ref[0].refType
auto_defined = tag_ref[0].autoDefined
core_tag = core.BNNewTagReference(tag_ref[0].tag)
assert core_tag is not None, "core.BNNewTagReference returned None"
tag = Tag(core_tag)
# Null for data tags (not in any arch or function)
if ctypes.cast(tag_ref[0].arch, ctypes.c_void_p).value is None:
arch = None
else:
arch = architecture.CoreArchitecture._from_cache(tag_ref[0].arch)
if ctypes.cast(tag_ref[0].func, ctypes.c_void_p).value is None:
func = None
else:
func = _function.Function(self._view, core.BNNewFunctionReference(tag_ref[0].func))
addr = tag_ref[0].addr
self._notify.tag_added(self._view, tag, ref_type, auto_defined, arch, func, addr)
except:
log_error(traceback.format_exc())
def _tag_updated(self, ctxt, view: core.BNBinaryView, tag_ref: core.BNTagReferenceHandle) -> None:
try:
ref_type = tag_ref[0].refType
auto_defined = tag_ref[0].autoDefined
core_tag = core.BNNewTagReference(tag_ref[0].tag)
assert core_tag is not None
tag = Tag(core_tag)
# Null for data tags (not in any arch or function)
if ctypes.cast(tag_ref[0].arch, ctypes.c_void_p).value is None:
arch = None
else:
arch = architecture.CoreArchitecture._from_cache(tag_ref[0].arch)
if ctypes.cast(tag_ref[0].func, ctypes.c_void_p).value is None:
func = None
else:
func = _function.Function(self._view, core.BNNewFunctionReference(tag_ref[0].func))
addr = tag_ref[0].addr
self._notify.tag_updated(self._view, tag, ref_type, auto_defined, arch, func, addr)
except:
log_error(traceback.format_exc())
def _tag_removed(self, ctxt, view: core.BNBinaryView, tag_ref: core.BNTagReferenceHandle) -> None:
try:
ref_type = tag_ref[0].refType
auto_defined = tag_ref[0].autoDefined
core_tag = core.BNNewTagReference(tag_ref[0].tag)
assert core_tag is not None, "core.BNNewTagReference returned None"
tag = Tag(core_tag)
# Null for data tags (not in any arch or function)
if ctypes.cast(tag_ref[0].arch, ctypes.c_void_p).value is None:
arch = None
else:
arch = architecture.CoreArchitecture._from_cache(tag_ref[0].arch)
if ctypes.cast(tag_ref[0].func, ctypes.c_void_p).value is None:
func = None
else:
func = _function.Function(self._view, core.BNNewFunctionReference(tag_ref[0].func))
addr = tag_ref[0].addr
self._notify.tag_removed(self._view, tag, ref_type, auto_defined, arch, func, addr)
except:
log_error(traceback.format_exc())
def _symbol_added(self, ctxt, view: core.BNBinaryView, sym: core.BNSymbol) -> None:
try:
_handle = core.BNNewSymbolReference(sym)
assert _handle is not None, "core.BNNewSymbolReference returned None"
self._notify.symbol_added(self._view, _types.CoreSymbol(_handle))
except:
log_error(traceback.format_exc())
def _symbol_updated(self, ctxt, view: core.BNBinaryView, sym: core.BNSymbol) -> None:
try:
_handle = core.BNNewSymbolReference(sym)
assert _handle is not None, "core.BNNewSymbolReference returned None"
self._notify.symbol_updated(self._view, _types.CoreSymbol(_handle))
except:
log_error(traceback.format_exc())
def _symbol_removed(self, ctxt, view: core.BNBinaryView, sym: core.BNSymbol) -> None:
try:
_handle = core.BNNewSymbolReference(sym)
assert _handle is not None, "core.BNNewSymbolReference returned None"
self._notify.symbol_removed(self._view, _types.CoreSymbol(_handle))
except:
log_error(traceback.format_exc())
def _string_found(self, ctxt, view: core.BNBinaryView, string_type: int, offset: int, length: int) -> None:
try:
self._notify.string_found(self._view, StringType(string_type), offset, length)
except:
log_error(traceback.format_exc())
def _string_removed(self, ctxt, view: core.BNBinaryView, string_type: int, offset: int, length: int) -> None:
try:
self._notify.string_removed(self._view, StringType(string_type), offset, length)
except:
log_error(traceback.format_exc())
def _type_defined(self, ctxt, view: core.BNBinaryView, name: str, type_obj: '_types.Type') -> None:
try:
qualified_name = _types.QualifiedName._from_core_struct(name[0])
self._notify.type_defined(
self._view, qualified_name,
_types.Type.create(core.BNNewTypeReference(type_obj), platform=self._view.platform)
)
except:
log_error(traceback.format_exc())
def _type_undefined(self, ctxt, view: core.BNBinaryView, name: str, type_obj: '_types.Type') -> None:
try:
qualified_name = _types.QualifiedName._from_core_struct(name[0])
self._notify.type_undefined(
self._view, qualified_name,
_types.Type.create(core.BNNewTypeReference(type_obj), platform=self._view.platform)
)
except:
log_error(traceback.format_exc())
def _type_ref_changed(self, ctxt, view: core.BNBinaryView, name: str, type_obj: '_types.Type') -> None:
try:
qualified_name = _types.QualifiedName._from_core_struct(name[0])
self._notify.type_ref_changed(
self._view, qualified_name,
_types.Type.create(core.BNNewTypeReference(type_obj), platform=self._view.platform)
)
except:
log_error(traceback.format_exc())
def _type_field_ref_changed(self, ctxt, view: core.BNBinaryView, name: str, offset: int) -> None:
try:
qualified_name = _types.QualifiedName._from_core_struct(name[0])
self._notify.type_field_ref_changed(self._view, qualified_name, offset)
except:
log_error(traceback.format_exc())
def _segment_added(self, ctxt, view: core.BNBinaryView, segment_obj: core.BNSegment) -> None:
try:
segment_handle = core.BNNewSegmentReference(segment_obj)
assert segment_handle is not None, "core.BNNewSegmentReference returned None"
result = Segment(segment_handle)
self._notify.segment_added(self._view, result)
except:
log_error(traceback.format_exc())
def _segment_updated(self, ctxt, view: core.BNBinaryView, segment_obj: core.BNSegment) -> None:
try:
segment_handle = core.BNNewSegmentReference(segment_obj)
assert segment_handle is not None, "core.BNNewSegmentReference returned None"
result = Segment(segment_handle)
self._notify.segment_updated(self._view, result)
except:
log_error(traceback.format_exc())
def _segment_removed(self, ctxt, view: core.BNBinaryView, segment_obj: core.BNSegment) -> None:
try:
segment_handle = core.BNNewSegmentReference(segment_obj)
assert segment_handle is not None, "core.BNNewSegmentReference returned None"
result = Segment(segment_handle)
self._notify.segment_removed(self._view, result)
except:
log_error(traceback.format_exc())
def _section_added(self, ctxt, view: core.BNBinaryView, section_obj: core.BNSection) -> None:
try:
section_handle = core.BNNewSectionReference(section_obj)
assert section_handle is not None, "core.BNNewSectionReference returned None"
result = Section(section_handle)
self._notify.section_added(self._view, result)
except:
log_error(traceback.format_exc())
def _section_updated(self, ctxt, view: core.BNBinaryView, section_obj: core.BNSection) -> None:
try:
section_handle = core.BNNewSectionReference(section_obj)
assert section_handle is not None, "core.BNNewSectionReference returned None"
result = Section(section_handle)
self._notify.section_updated(self._view, result)
except:
log_error(traceback.format_exc())
def _section_removed(self, ctxt, view: core.BNBinaryView, section_obj: core.BNSection) -> None:
try:
section_handle = core.BNNewSectionReference(section_obj)
assert section_handle is not None, "core.BNNewSectionReference returned None"
result = Section(section_handle)
self._notify.section_removed(self._view, result)
except:
log_error(traceback.format_exc())
def _component_added(self, ctxt, view: core.BNBinaryView, _component: core.BNComponent):
try:
component_handle = core.BNNewComponentReference(_component)
assert component_handle is not None, "core.BNNewComponentReference returned None"
result = component.Component(component_handle)
self._notify.component_added(self._view, result)
except:
log_error(traceback.format_exc())
def _component_removed(self, ctxt, view: core.BNBinaryView, formerParent: core.BNComponent, _component: core.BNComponent):
try:
formerParent_handle = core.BNNewComponentReference(formerParent)
assert formerParent_handle is not None, "core.BNNewComponentReference returned None"
formerParentResult = component.Component(formerParent_handle)
component_handle = core.BNNewComponentReference(_component)
assert component_handle is not None, "core.BNNewComponentReference returned None"
result = component.Component(component_handle)
self._notify.component_removed(self._view, formerParentResult, result)
except:
log_error(traceback.format_exc())
def _component_name_updated(self, ctxt, view: core.BNBinaryView, previous_name: str, _component: core.BNComponent):
try:
component_handle = core.BNNewComponentReference(_component)
assert component_handle is not None, "core.BNNewComponentReference returned None"
result = component.Component(component_handle)
self._notify.component_name_updated(self._view, previous_name, result)
except:
log_error(traceback.format_exc())
def _component_moved(self, ctxt, view: core.BNBinaryView, formerParent: core.BNComponent,
newParent: core.BNComponent, _component: core.BNComponent):
try:
formerParent_handle = core.BNNewComponentReference(formerParent)
assert formerParent_handle is not None, "core.BNNewComponentReference returned None"
formerParentResult = component.Component(formerParent_handle)
newParent_handle = core.BNNewComponentReference(newParent)
assert newParent_handle is not None, "core.BNNewComponentReference returned None"
newParentResult = component.Component(newParent_handle)
component_handle = core.BNNewComponentReference(_component)
assert component_handle is not None, "core.BNNewComponentReference returned None"
result = component.Component(component_handle)
self._notify.component_moved(self._view, formerParentResult, newParentResult, result)
except:
log_error(traceback.format_exc())
def _component_function_added(self, ctxt, view: core.BNBinaryView, _component: core.BNComponent,
func: '_function.Function'):
try:
component_handle = core.BNNewComponentReference(_component)
assert component_handle is not None, "core.BNNewComponentReference returned None"
result = component.Component(component_handle)
function_handle = core.BNNewFunctionReference(func)
assert function_handle is not None, "core.BNNewFunctionReference returned None"
function = _function.Function(self._view, function_handle)
self._notify.component_function_added(self._view, result, function)
except:
log_error(traceback.format_exc())
def _component_function_removed(self, ctxt, view: core.BNBinaryView, _component: core.BNComponent,
func: '_function.Function'):
try:
component_handle = core.BNNewComponentReference(_component)
assert component_handle is not None, "core.BNNewComponentReference returned None"
result = component.Component(component_handle)
function_handle = core.BNNewFunctionReference(func)
assert function_handle is not None, "core.BNNewFunctionReference returned None"
function = _function.Function(self._view, function_handle)
self._notify.component_function_removed(self._view, result, function)
except:
log_error(traceback.format_exc())
def _component_data_variable_added(self, ctxt, view: core.BNBinaryView, _component: core.BNComponent,
var: core.BNDataVariable):
try:
component_handle = core.BNNewComponentReference(_component)
assert component_handle is not None, "core.BNNewComponentReference returned None"
result = component.Component(component_handle)
self._notify.component_data_var_added(self._view, result, DataVariable.from_core_struct(var, self._view))
except:
log_error(traceback.format_exc())
def _component_data_variable_removed(self, ctxt, view: core.BNBinaryView, _component: core.BNComponent,
var: core.BNDataVariable):
try:
component_handle = core.BNNewComponentReference(_component)
assert component_handle is not None, "core.BNNewComponentReference returned None"
result = component.Component(component_handle)
self._notify.component_data_var_removed(self._view, result, DataVariable.from_core_struct(var, self._view))
except:
log_error(traceback.format_exc())
def _type_archive_attached(self, ctxt, view: core.BNBinaryView, id: ctypes.c_char_p, path: ctypes.c_char_p):
try:
self._notify.type_archive_attached(self._view, core.pyNativeStr(id), core.pyNativeStr(path))
except:
log_error(traceback.format_exc())
def _type_archive_detached(self, ctxt, view: core.BNBinaryView, id: ctypes.c_char_p, path: ctypes.c_char_p):
try:
self._notify.type_archive_detached(self._view, core.pyNativeStr(id), core.pyNativeStr(path))
except:
log_error(traceback.format_exc())
def _type_archive_connected(self, ctxt, view: core.BNBinaryView, archive: core.BNTypeArchive):
try:
py_archive = typearchive.TypeArchive(handle=core.BNNewTypeArchiveReference(archive))
self._notify.type_archive_connected(self._view, py_archive)
except:
log_error(traceback.format_exc())
def _type_archive_disconnected(self, ctxt, view: core.BNBinaryView, archive: core.BNTypeArchive):
try:
py_archive = typearchive.TypeArchive(handle=core.BNNewTypeArchiveReference(archive))
self._notify.type_archive_disconnected(self._view, py_archive)
except:
log_error(traceback.format_exc())
def _undo_entry_added(self, ctxt, view: core.BNBinaryView, entry: core.BNUndoEntry):
try:
py_entry = undo.UndoEntry(handle=core.BNNewUndoEntryReference(entry))
self._notify.undo_entry_added(self._view, py_entry)
except:
log_error(traceback.format_exc())
def _undo_entry_taken(self, ctxt, view: core.BNBinaryView, entry: core.BNUndoEntry):
try:
py_entry = undo.UndoEntry(handle=core.BNNewUndoEntryReference(entry))
self._notify.undo_entry_taken(self._view, py_entry)
except:
log_error(traceback.format_exc())
def _redo_entry_taken(self, ctxt, view: core.BNBinaryView, entry: core.BNUndoEntry):
try:
py_entry = undo.UndoEntry(handle=core.BNNewUndoEntryReference(entry))
self._notify.redo_entry_taken(self._view, py_entry)
except:
log_error(traceback.format_exc())
@property
def view(self) -> 'BinaryView':
return self._view
@property
def notify(self) -> 'BinaryDataNotification':
return self._notify
class _BinaryViewTypeMetaclass(type):
def __iter__(self):
binaryninja._init_plugins()
count = ctypes.c_ulonglong()
types = core.BNGetBinaryViewTypes(count)
if types is None:
return
try:
for i in range(0, count.value):
yield BinaryViewType(types[i])
finally:
core.BNFreeBinaryViewTypeList(types)
def __getitem__(self, value):
binaryninja._init_plugins()
view_type = core.BNGetBinaryViewTypeByName(str(value))
if view_type is None:
raise KeyError(f"'{value}' is not a valid view type")
return BinaryViewType(view_type)
[docs]
class BinaryViewType(metaclass=_BinaryViewTypeMetaclass):
"""
The ``BinaryViewType`` object is used internally and should not be directly instantiated.
"""
_platform_recognizers = {} # Used to force Python callback objects to not get garbage collected
def __init__(self, handle: core.BNBinaryViewTypeHandle):
_handle = core.BNBinaryViewTypeHandle
self.handle = ctypes.cast(handle, _handle)
def __repr__(self):
return f"<view type: '{self.name}'>"
def __eq__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return ctypes.addressof(self.handle.contents) == ctypes.addressof(other.handle.contents)
def __ne__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return not (self == other)
def __hash__(self):
return hash(ctypes.addressof(self.handle.contents))
@property
def name(self) -> str:
"""BinaryView name (read-only)"""
return core.BNGetBinaryViewTypeName(self.handle)
@property
def long_name(self) -> str:
"""BinaryView long name (read-only)"""
return core.BNGetBinaryViewTypeLongName(self.handle)
@property
def is_deprecated(self) -> bool:
"""returns if the BinaryViewType is deprecated (read-only)"""
return core.BNIsBinaryViewTypeDeprecated(self.handle)
@property
def is_force_loadable(self) -> bool:
"""returns if the BinaryViewType is force loadable (read-only)"""
return core.BNIsBinaryViewTypeForceLoadable(self.handle)
[docs]
def create(self, data: 'BinaryView') -> Optional['BinaryView']:
view = core.BNCreateBinaryViewOfType(self.handle, data.handle)
if view is None:
return None
return BinaryView(file_metadata=data.file, handle=view)
[docs]
def open(self, src: PathType, file_metadata: 'filemetadata.FileMetadata' = None) -> Optional['BinaryView']:
data = BinaryView.open(src, file_metadata)
if data is None:
return None
return self.create(data)
# TODO : Check if we need binary_view_type's at all after these deprecations? (move add_binaryview_finalized_event and add_binaryview_initial_analysis_completion_event to BinaryView?)
[docs]
def parse(self, data: 'BinaryView') -> Optional['BinaryView']:
view = core.BNParseBinaryViewOfType(self.handle, data.handle)
if view is None:
return None
return BinaryView(file_metadata=data.file, handle=view)
[docs]
def is_valid_for_data(self, data: 'BinaryView') -> bool:
return core.BNIsBinaryViewTypeValidForData(self.handle, data.handle)
[docs]
def get_load_settings_for_data(self, data: 'BinaryView') -> Optional['settings.Settings']:
view_handle = None
if data is not None:
view_handle = data.handle
load_settings = core.BNGetBinaryViewLoadSettingsForData(self.handle, view_handle)
if load_settings is None:
return None
return settings.Settings(handle=load_settings)
[docs]
def register_arch(self, ident: int, endian: Endianness, arch: 'architecture.Architecture') -> None:
core.BNRegisterArchitectureForViewType(self.handle, ident, endian, arch.handle)
[docs]
def get_arch(self, ident: int, endian: Endianness) -> Optional['architecture.Architecture']:
arch = core.BNGetArchitectureForViewType(self.handle, ident, endian)
if arch is None:
return None
return architecture.CoreArchitecture._from_cache(arch)
[docs]
@staticmethod
def add_binaryview_finalized_event(callback: BinaryViewEvent.BinaryViewEventCallback) -> None:
"""
`add_binaryview_finalized_event` adds a callback that gets executed
when new binaryview is finalized.
For more details, please refer to the documentation of BinaryViewEvent.
.. warning:: The callback provided **must** stay in scope for the lifetime of the process, deletion or \
garbage collection of the callback will result in a crash.
"""
BinaryViewEvent.register(BinaryViewEventType.BinaryViewFinalizationEvent, callback)
[docs]
@staticmethod
def add_binaryview_initial_analysis_completion_event(callback: BinaryViewEvent.BinaryViewEventCallback) -> None:
"""
`add_binaryview_initial_analysis_completion_event` adds a callback
that gets executed after the initial analysis, as well as linear
sweep and signature matcher (if they are configured to run) completed.
For more details, please refer to the documentation of BinaryViewEvent.
.. warning:: The callback provided **must** stay in scope for the lifetime of the process, deletion or \
garbage collection of the callback will result in a crash.
"""
BinaryViewEvent.register(BinaryViewEventType.BinaryViewInitialAnalysisCompletionEvent, callback)
[docs]
class Segment:
"""
The ``Segment`` object is returned during BinaryView creation and should not be directly instantiated.
"""
def __init__(self, handle: core.BNSegmentHandle):
self.handle = handle
def __del__(self):
if core is not None:
core.BNFreeSegment(self.handle)
def __repr__(self):
r = "r" if self.readable else "-"
w = "w" if self.writable else "-"
x = "x" if self.executable else "-"
return f"<segment: {self.start:#x}-{self.end:#x}, {r}{w}{x}>"
[docs]
@classmethod
@deprecation.deprecated(deprecated_in="4.3.6653", details="Use `SegmentDescriptorList` instead.")
def serialize(cls, image_base: int, start: int, length: int, data_offset: int=0, data_length: int=0, flags: 'SegmentFlag'=SegmentFlag.SegmentReadable, auto_defined=True, segments: str="[]"):
"""
Serialize segment parameters into a JSON string. This is useful for generating a properly formatted segment description as options when using `load`.
:param int image_base: The base address of the image.
:param int start: The start address of the segment.
:param int length: The length of the segment.
:param int data_offset: The offset of the data within the segment.
:param int data_length: The length of the data within the segment.
:param SegmentFlag flags: The flags of the segment.
:param bool auto_defined: Whether the segment is auto-defined.
:param str segments: An optional, existing array of segments to append to.
:return: A JSON string representing the segment.
:rtype: str
:Example::
>>> base = 0x400000
>>> rom_base = 0xffff0000
>>> segments = SegmentDescriptorList(base)
>>> segments.append(start=base, length=0x1000, data_offset=0, data_length=0x1000, flags=SegmentFlag.SegmentReadable|SegmentFlag.SegmentExecutable)
>>> segments.append(start=rom_base, length=0x1000, flags=SegmentFlag.SegmentReadable)
>>> view = load(bytes.fromhex('5054ebfe'), options={'loader.imageBase': base, 'loader.platform': 'x86', 'loader.segments': json.dumps(segments)})
"""
segments_list = json.loads(segments)
segment_info = {
"auto_defined": auto_defined,
"data_length": data_length,
"data_offset": data_offset,
"flags": flags,
"length": length,
"start": start - image_base
}
segments_list.append(segment_info)
return json.dumps(segments_list)
@property
def length(self):
return int(core.BNSegmentGetLength(self.handle))
def __bool__(self):
return True
def __eq__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return ctypes.addressof(self.handle.contents) == ctypes.addressof(other.handle.contents)
def __ne__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return not (self == other)
def __hash__(self):
return hash(ctypes.addressof(self.handle.contents))
def __contains__(self, i: int):
return i >= self.start and i < self.end
@property
def start(self) -> int:
return core.BNSegmentGetStart(self.handle)
@property
def end(self) -> int:
return core.BNSegmentGetEnd(self.handle)
@property
def executable(self) -> bool:
return (core.BNSegmentGetFlags(self.handle) & SegmentFlag.SegmentExecutable) != 0
@property
def writable(self) -> bool:
return (core.BNSegmentGetFlags(self.handle) & SegmentFlag.SegmentWritable) != 0
@property
def readable(self) -> bool:
return (core.BNSegmentGetFlags(self.handle) & SegmentFlag.SegmentReadable) != 0
@property
def data_length(self) -> int:
return core.BNSegmentGetDataLength(self.handle)
@property
def data_offset(self) -> int:
return core.BNSegmentGetDataOffset(self.handle)
@property
def data_end(self) -> int:
return core.BNSegmentGetDataEnd(self.handle)
@property
def auto_defined(self) -> bool:
return core.BNSegmentIsAutoDefined(self.handle)
[docs]
class SegmentDescriptorList(list):
def __init__(self, image_base: int):
"""
Initialize the SegmentDescriptorList with a base image address.
:param int image_base: The base address of the image.
"""
super().__init__()
self.image_base = image_base
[docs]
def append(self, start: int, length: int, data_offset: int = 0, data_length: int = 0,
flags: 'SegmentFlag' = SegmentFlag.SegmentReadable, auto_defined: bool = True):
"""
Append a segment descriptor to the list.
:param int start: The start address of the segment.
:param int length: The length of the segment.
:param int data_offset: The offset of the data within the segment.
:param int data_length: The length of the data within the segment.
:param SegmentFlag flags: The flags of the segment.
:param bool auto_defined: Whether the segment is auto-defined.
"""
segment_info = {
"start": start - self.image_base,
"length": length,
"data_offset": data_offset,
"data_length": data_length,
"flags": flags,
"auto_defined": auto_defined
}
super().append(segment_info)
[docs]
class Section:
"""
The ``Section`` object is returned during BinaryView creation and should not be directly instantiated.
"""
def __init__(self, handle: core.BNSectionHandle):
self.handle = handle
def __del__(self):
if core is not None:
core.BNFreeSection(self.handle)
def __repr__(self):
return f"<section {self.name}: {self.start:#x}-{self.end:#x}>"
def __bool__(self):
return True
def __eq__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return ctypes.addressof(self.handle.contents) == ctypes.addressof(other.handle.contents)
def __ne__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return not (self == other)
def __hash__(self):
return hash(ctypes.addressof(self.handle.contents))
def __contains__(self, i: int):
return i >= self.start and i < self.end
[docs]
@classmethod
@deprecation.deprecated(deprecated_in="4.3.6653", details="Use `SectionDescriptorList` instead.")
def serialize(cls, image_base: int, name: str, start: int, length: int, semantics: SectionSemantics=SectionSemantics.DefaultSectionSemantics, type: str="", align: int=1, entry_size: int=0, link: str="", info_section: str="", info_data: int=0, auto_defined: bool=True, sections: str="[]"):
"""
Serialize section parameters into a JSON string. This is useful for generating a properly formatted section description as options when using `load`.
:param int image_base: The base address of the image.
:param str name: The name of the section.
:param int start: The start address of the section.
:param int length: The length of the section.
:param SectionSemantics semantics: The semantics of the section.
:param str type: The type of the section.
:param int align: The alignment of the section.
:param int entry_size: The entry size of the section.
:param str link: The linked section of the section.
:param str info_section: The info section of the section.
:param int info_data: The info data of the section.
:param bool auto_defined: Whether the section is auto-defined.
:param str sections: An optional, existing array of sections to append to.
:return: A JSON string representing the section.
:rtype: str
"""
sections_list = json.loads(sections)
section_info = {
"align": align,
"auto_defined": auto_defined,
"entry_size": entry_size,
"info_data": info_data,
"info_section": info_section,
"length": length,
"link": link,
"name": name,
"semantics": semantics,
"start": start - image_base,
"type": type
}
sections_list.append(section_info)
return json.dumps(sections_list)
@property
def name(self) -> str:
return core.BNSectionGetName(self.handle)
@property
def type(self) -> str:
return core.BNSectionGetType(self.handle)
@property
def start(self) -> int:
return core.BNSectionGetStart(self.handle)
@property
def linked_section(self) -> str:
return core.BNSectionGetLinkedSection(self.handle)
@property
def info_section(self) -> str:
return core.BNSectionGetInfoSection(self.handle)
@property
def info_data(self) -> int:
return core.BNSectionGetInfoData(self.handle)
@property
def align(self) -> int:
return core.BNSectionGetAlign(self.handle)
@property
def entry_size(self) -> int:
return core.BNSectionGetEntrySize(self.handle)
@property
def semantics(self) -> SectionSemantics:
return SectionSemantics(core.BNSectionGetSemantics(self.handle))
@property
def auto_defined(self) -> bool:
return core.BNSectionIsAutoDefined(self.handle)
@property
def length(self):
return int(core.BNSectionGetLength(self.handle))
@property
def end(self) -> int:
return self.start + self.length
[docs]
class SectionDescriptorList(list):
def __init__(self, image_base: int):
"""
Initialize the SectionDescriptorList with a base image address.
:param int image_base: The base address of the image.
"""
super().__init__()
self.image_base = image_base
[docs]
def append(self, name: str, start: int, length: int, semantics: 'SectionSemantics' = SectionSemantics.DefaultSectionSemantics,
type: str = "", align: int = 1, entry_size: int = 0, link: str = "", info_section: str = "",
info_data: int = 0, auto_defined: bool = True):
"""
Append a section descriptor to the list.
:param str name: The name of the section.
:param int start: The start address of the section.
:param int length: The length of the section.
:param SectionSemantics semantics: The semantics of the section.
:param str type: The type of the section.
:param int align: The alignment of the section.
:param int entry_size: The size of each entry in the section.
:param str link: An optional link field.
:param str info_section: An optional info_section field.
:param int info_data: An optional info_data field.
:param bool auto_defined: Whether the section is auto-defined.
"""
section_info = {
"name": name,
"start": start - self.image_base,
"length": length,
"semantics": semantics,
"type": type,
"align": align,
"entry_size": entry_size,
"link": link,
"info_section": info_section,
"info_data": info_data,
"auto_defined": auto_defined
}
super().append(section_info)
[docs]
class TagType:
"""
The ``TagType`` object is created by the create_tag_type API and should not be directly instantiated.
"""
def __init__(self, handle: core.BNTagTypeHandle):
self.handle = handle
def __del__(self):
if core is not None:
core.BNFreeTagType(self.handle)
def __repr__(self):
return f"<tag type {self.name}: {self.icon}>"
def __eq__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return ctypes.addressof(self.handle.contents) == ctypes.addressof(other.handle.contents)
def __ne__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return not (self == other)
def __hash__(self):
return hash(ctypes.addressof(self.handle.contents))
@property
def id(self) -> str:
"""Unique id of the TagType"""
return core.BNTagTypeGetId(self.handle)
@property
def name(self) -> str:
"""Name of the TagType"""
return core.BNTagTypeGetName(self.handle)
@name.setter
def name(self, value: str) -> None:
core.BNTagTypeSetName(self.handle, value)
@property
def icon(self) -> str:
"""Unicode str containing an emoji to be used as an icon"""
return core.BNTagTypeGetIcon(self.handle)
@icon.setter
def icon(self, value: str) -> None:
core.BNTagTypeSetIcon(self.handle, value)
@property
def visible(self) -> bool:
"""Boolean for whether the tags of this type are visible"""
return core.BNTagTypeGetVisible(self.handle)
@visible.setter
def visible(self, value: bool) -> None:
core.BNTagTypeSetVisible(self.handle, value)
@property
def type(self) -> TagTypeType:
"""Type from enums.TagTypeType"""
return TagTypeType(core.BNTagTypeGetType(self.handle))
@type.setter
def type(self, value: TagTypeType) -> None:
core.BNTagTypeSetType(self.handle, value)
[docs]
class Tag:
"""
The ``Tag`` object is created by other APIs (create_*_tag) and should not be directly instantiated.
"""
def __init__(self, handle: core.BNTagHandle):
self.handle = handle
def __del__(self):
if core is not None:
core.BNFreeTag(self.handle)
def __repr__(self):
return f"<tag {self.type.icon} {self.type.name}: {self.data}>"
def __eq__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return ctypes.addressof(self.handle.contents) == ctypes.addressof(other.handle.contents)
def __ne__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return not (self == other)
def __hash__(self):
return hash(ctypes.addressof(self.handle.contents))
@property
def id(self) -> str:
return core.BNTagGetId(self.handle)
@property
def type(self) -> TagType:
core_tag_type = core.BNTagGetType(self.handle)
assert core_tag_type is not None, "core.BNTagGetType returned None"
return TagType(core_tag_type)
@property
def data(self) -> str:
return core.BNTagGetData(self.handle)
@data.setter
def data(self, value: str) -> None:
core.BNTagSetData(self.handle, value)
[docs]
@dataclass
class RelocationInfo:
type: RelocationType
pc_relative: bool
base_relative: bool
base: int
size: int
truncate_size: int
native_type: int
addend: int
has_sign: bool
implicit_addend: bool
external: bool
symbol_index: int
section_index: int
address: int
target: int
data_relocation: bool
def __init__(self, info: core.BNRelocationInfo):
self.type = RelocationType(info.type)
self.pc_relative = info.pcRelative
self.base_relative = info.baseRelative
self.base = info.base
self.size = info.size
self.truncate_size = info.truncateSize
self.native_type = info.nativeType
self.addend = info.addend
self.has_sign = info.hasSign
self.implicit_addend = info.implicitAddend
self.external = info.external
self.symbol_index = info.symbolIndex
self.section_index = info.sectionIndex
self.address = info.address
self.target = info.target
self.data_relocation = info.dataRelocation
[docs]
class Relocation:
def __init__(self, handle: core.BNRelocationHandle):
self.handle = handle
def __del__(self):
if core is not None:
core.BNFreeRelocation(self.handle)
def __repr__(self):
if self.symbol is None:
return f"<Relocation: {self.target:#x}>"
try:
return f"<Relocation: \"{self.symbol.full_name}\" @ {self.target:#x}>"
except UnicodeDecodeError:
return f"<Relocation: \"{self.symbol.raw_bytes}\" @ {self.target:#x}>"
def __eq__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return ctypes.addressof(self.handle.contents) == ctypes.addressof(other.handle.contents)
def __ne__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return not (self == other)
def __hash__(self):
return hash(ctypes.addressof(self.handle.contents))
@property
def info(self) -> RelocationInfo:
return RelocationInfo(core.BNRelocationGetInfo(self.handle))
@property
def arch(self) -> Optional['architecture.Architecture']:
"""The architecture associated with the :py:class:`Relocation` (read/write)"""
core_arch = core.BNRelocationGetArchitecture(self.handle)
return architecture.CoreArchitecture._from_cache(handle=core_arch)
@property
def target(self) -> int:
"""Where the reloc needs to point to"""
return core.BNRelocationGetTarget(self.handle)
@property
def reloc(self) -> int:
"""The actual pointer that needs to be relocated"""
return core.BNRelocationGetReloc(self.handle)
@property
def symbol(self) -> Optional['_types.CoreSymbol']:
core_symbol = core.BNRelocationGetSymbol(self.handle)
if core_symbol is None:
return None
return _types.CoreSymbol(core_symbol)
class _BinaryViewAssociatedDataStore(associateddatastore._AssociatedDataStore):
_defaults = {}
[docs]
class SymbolMapping(collections.abc.Mapping): # type: ignore
"""
SymbolMapping object is used to improve performance of the `bv.symbols` API.
This allows pythonic code like this to have reasonable performance characteristics
>>> my_symbols = get_my_symbols()
>>> for symbol in my_symbols:
>>> if bv.symbols[symbol].address == 0x41414141:
>>> print("Found")
"""
def __init__(self, view: 'BinaryView'):
self._symbol_list = None
self._count = None
self._symbol_cache: Optional[Mapping[str, List[_types.CoreSymbol]]] = None
self._view = view
self._n = 0
self._keys = None
def __repr__(self):
return f"<SymbolMapping {len(self)} symbols: {self._symbol_cache}>"
def __del__(self):
if core is not None and self._symbol_list is not None:
core.BNFreeSymbolList(self._symbol_list, len(self))
def __getitem__(self, key: str) -> Optional[List['_types.CoreSymbol']]:
if self._symbol_cache is None:
sym = self._view.get_symbols_by_raw_name(key)
if len(sym) == 0:
raise KeyError(f"'{key}': symbol not found")
return sym
else:
return self._symbol_cache[key]
def _build_symbol_cache(self):
count = ctypes.c_ulonglong(0)
self._symbol_list = core.BNGetSymbols(self._view.handle, count, None)
assert self._symbol_list is not None, "core.BNGetSymbols returned None"
self._symbol_cache = {}
self._count = count.value
for i in range(len(self)):
_handle = core.BNNewSymbolReference(self._symbol_list[i])
assert _handle is not None, "core.BNNewSymbolReference returned None"
sym = _types.CoreSymbol(_handle)
try:
if sym.raw_name in self._symbol_cache:
self._symbol_cache[sym.raw_name].append(sym)
else:
self._symbol_cache[sym.raw_name] = [sym]
except UnicodeDecodeError:
mapped_str = sym.raw_bytes.decode('charmap')
if mapped_str in self._symbol_cache:
self._symbol_cache[mapped_str].append(sym)
else:
self._symbol_cache[mapped_str] = [sym]
def __iter__(self) -> Iterator[str]:
if self._symbol_cache is None:
self._build_symbol_cache()
assert self._symbol_cache is not None
yield from self._symbol_cache
def __next__(self) -> List['_types.CoreSymbol']:
if self._symbol_cache is None:
self._build_symbol_cache()
assert self._symbol_cache is not None
if self._keys is None:
self._keys = list(self._symbol_cache.keys())
self._n += 1
return self._symbol_cache[self._keys[self._n - 1]]
def __len__(self):
if self._symbol_cache is None:
self._build_symbol_cache()
return self._count
def __contains__(self, value: str):
try:
_ = self[value]
return True
except KeyError:
return False
[docs]
def keys(self) -> KeysView[str]:
if self._symbol_cache is None:
self._build_symbol_cache()
assert self._symbol_cache is not None
return self._symbol_cache.keys()
[docs]
def items(self) -> ItemsView[str, List['_types.CoreSymbol']]:
if self._symbol_cache is None:
self._build_symbol_cache()
assert self._symbol_cache is not None
return self._symbol_cache.items()
[docs]
def values(self) -> ValuesView[List['_types.CoreSymbol']]:
if self._symbol_cache is None:
self._build_symbol_cache()
assert self._symbol_cache is not None
return self._symbol_cache.values()
[docs]
def get(self, key: str, default: Optional[List['_types.CoreSymbol']] = None) -> Optional[List['_types.CoreSymbol']]:
try:
return self[key]
except KeyError:
return default
[docs]
class TypeMapping(collections.abc.Mapping): # type: ignore
"""
TypeMapping object is used to improve performance of the `bv.types` API.
This allows pythonic code like this to have reasonable performance characteristics
>>> my_types = get_my_types()
>>> for type_name in my_types:
>>> if bv.types[type_name].width == 4:
>>> print("Found")
"""
def __init__(self, view: 'BinaryView', get_list_fn=core.BNGetAnalysisTypeList):
self._type_list = None
self._count = None
self._type_cache: Optional[Mapping[_types.QualifiedName, _types.Type]] = None
self._view = view
self._get_list_fn = get_list_fn
def __repr__(self):
return f"<TypeMapping {len(self)} symbols: {self._type_cache}>"
def __del__(self):
if core is not None and self._type_list is not None:
core.BNFreeTypeAndNameList(self._type_list, len(self))
def __getitem__(self, key):
if self._type_cache is None:
result = self._view.get_type_by_name(key)
if result is None:
raise KeyError(key)
return result
else:
return self._type_cache[key]
def __iter__(self):
if self._type_cache is not None:
yield from self._type_cache
count = ctypes.c_ulonglong(0)
type_list = self._get_list_fn(self._view.handle, count)
assert type_list is not None, "core.BNGetAnalysisTypeList returned None"
self._type_list = type_list
self._type_cache = {}
self._count = count.value
for i in range(len(self)):
name = _types.QualifiedName._from_core_struct(self._type_list[i].name)
type = _types.Type.create(core.BNNewTypeReference(self._type_list[i].type), platform=self._view.platform)
self._type_cache[name] = type
yield name, type
def _build_type_cache(self):
for _, _ in self:
pass
def __len__(self):
if self._type_cache is None:
self._build_type_cache()
return self._count
def __contains__(self, value):
try:
self[value]
return True
except KeyError:
return False
def __eq__(self, other):
return self._view == other._view
def __ne__(self, other):
return not (self == other)
[docs]
def keys(self):
if self._type_cache is None:
self._build_type_cache()
assert self._type_cache is not None
return self._type_cache.keys()
[docs]
def items(self):
if self._type_cache is None:
self._build_type_cache()
assert self._type_cache is not None
return self._type_cache.items()
[docs]
def values(self):
if self._type_cache is None:
self._build_type_cache()
assert self._type_cache is not None
return self._type_cache.values()
[docs]
def get(self, value, default = None):
try:
return self[value]
except KeyError:
return default
[docs]
class FunctionList:
def __init__(self, view: 'BinaryView'):
count = ctypes.c_ulonglong(0)
_funcs = core.BNGetAnalysisFunctionList(view.handle, count)
assert _funcs is not None, "core.BNGetAnalysisFunctionList returned None"
self._funcs = _funcs
self._count = count.value
self._view = view
self._n = 0
def __iter__(self):
for i in range(0, len(self)):
yield _function.Function(self._view, core.BNNewFunctionReference(self._funcs[i]))
def __next__(self):
if self._n >= len(self):
raise StopIteration
func = core.BNNewFunctionReference(self._funcs[self._n])
assert func is not None, "core.BNNewFunctionReference returned None"
self._n += 1
return _function.Function(self._view, func)
@overload
def __getitem__(self, i: int) -> '_function.Function': ...
@overload
def __getitem__(self, i: slice) -> List['_function.Function']: ...
def __getitem__(self, i: Union[int, slice]) -> Union['_function.Function', List['_function.Function']]:
if isinstance(i, int):
if i < 0:
i = len(self) + i
if i >= len(self):
raise IndexError(f"Index {i} out of bounds for FunctionList of size {len(self)}")
return _function.Function(self._view, core.BNNewFunctionReference(self._funcs[i]))
elif isinstance(i, slice):
result = []
if i.start < 0 or i.start >= len(self) or i.stop < 0 or i.stop >= len(self):
raise IndexError(f"Slice {i} out of bounds for FunctionList of size {len(self)}")
for j in range(i.start, i.stop, i.step if i.step is not None else 1):
result.append(_function.Function(self._view, core.BNNewFunctionReference(self._funcs[j])))
return result
raise ValueError("FunctionList.__getitem__ supports argument of type integer or slice")
def __del__(self):
if core is not None:
core.BNFreeFunctionList(self._funcs, len(self))
def __len__(self) -> int:
return self._count
[docs]
class AdvancedILFunctionList:
"""
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
"""
def __init__(self, view: 'BinaryView', preload_limit: int = mainthread.get_worker_thread_count(), functions: Optional[Iterable] = None):
self._view = view
self._func_queue = deque()
self._preload_limit = preload_limit
if functions is None:
self._functions = FunctionList(self._view)
else:
self._functions = iter(functions)
def __iter__(self):
while True:
while len(self._func_queue) < self._preload_limit:
try:
self._func_queue.append(_function.AdvancedFunctionAnalysisDataRequestor(next(self._functions)))
except StopIteration:
break
if not self._func_queue:
break
yield self._func_queue.popleft().function
[docs]
class MemoryMap:
r"""
The MemoryMap object is used to describe a system level MemoryMap for which a BinaryView is loaded into. A loaded
BinaryView has a view into the MemoryMap which is described by the Segments defined in that BinaryView. The MemoryMap
object allows for the addition of multiple, arbitrary overlapping regions of memory. Segmenting of the address space is
automatically handled when the MemoryMap is modified and in the case where a portion of the system address space has
multiple defined regions, the default ordering gives priority to the most recently added region. This feature is
experimental and under active development.
:Example:
.. code-block:: python
>>> base = 0x10000
>>> rom_base = 0xc0000000
>>> segments = SegmentDescriptorList(base)
>>> segments.append(start=base, length=0x1000, data_offset=0, data_length=0x1000, flags=SegmentFlag.SegmentReadable|SegmentFlag.SegmentExecutable)
>>> segments.append(start=rom_base, length=0x1000, flags=SegmentFlag.SegmentReadable)
>>> view = load(bytes.fromhex('5054ebfe'), options={'loader.imageBase': base, 'loader.platform': 'x86', 'loader.segments': json.dumps(segments)})
>>> view.memory_map
<region: 0x10000 - 0x10004>
size: 0x4
objects:
'origin<Mapped>@0x0' | Mapped<Absolute> | <r-x>
<region: 0xc0000000 - 0xc0001000>
size: 0x1000
objects:
'origin<Mapped>@0xbfff0000' | Unmapped | <r--> | FILL<0x0>
<region: 0xc0001000 - 0xc0001014>
size: 0x14
objects:
'origin<Mapped>@0xbfff1000' | Unmapped | <---> | FILL<0x0>
>>> view.memory_map.add_memory_region("rom", rom_base, b'\x90' * 4096, SegmentFlag.SegmentReadable | SegmentFlag.SegmentExecutable)
True
>>> view.memory_map
<region: 0x10000 - 0x10004>
size: 0x4
objects:
'origin<Mapped>@0x0' | Mapped<Absolute> | <r-x>
<region: 0xc0000000 - 0xc0001000>
size: 0x1000
objects:
'rom' | Mapped<Relative> | <r-x>
'origin<Mapped>@0xbfff0000' | Unmapped | <r--> | FILL<0x0>
<region: 0xc0001000 - 0xc0001014>
size: 0x14
objects:
'origin<Mapped>@0xbfff1000' | Unmapped | <---> | FILL<0x0>
>>> view.read(rom_base, 16)
b'\x90\x90\x90\x90\x90\x90\x90\x90\x90\x90\x90\x90\x90\x90\x90\x90'
>>> view.memory_map.add_memory_region("pad", rom_base, b'\xa5' * 8)
True
>>> view.read(rom_base, 16)
b'\xa5\xa5\xa5\xa5\xa5\xa5\xa5\xa5\x90\x90\x90\x90\x90\x90\x90\x90'
>>> view.memory_map
<region: 0x10000 - 0x10004>
size: 0x4
objects:
'origin<Mapped>@0x0' | Mapped<Absolute> | <r-x>
<region: 0xc0000000 - 0xc0000008>
size: 0x8
objects:
'pad' | Mapped<Relative> | <--->
'rom' | Mapped<Relative> | <r-x>
'origin<Mapped>@0xbfff0000' | Unmapped | <r--> | FILL<0x0>
<region: 0xc0000008 - 0xc0001000>
size: 0xff8
objects:
'rom' | Mapped<Relative> | <r-x>
'origin<Mapped>@0xbfff0000' | Unmapped | <r--> | FILL<0x0>
<region: 0xc0001000 - 0xc0001014>
size: 0x14
objects:
'origin<Mapped>@0xbfff1000' | Unmapped | <---> | FILL<0x0>
"""
def __repr__(self):
return self.__str__()
def __str__(self):
description = self.description()
return self.format_description(description)
def __len__(self):
mm_json = self.description()
if 'MemoryMap' in mm_json:
return len(mm_json['MemoryMap'])
else:
return 0
def __init__(self, handle: 'BinaryView'):
self.handle = handle
[docs]
def description(self, base: bool = False) -> dict:
if base:
return json.loads(core.BNGetBaseMemoryMapDescription(self.handle))
return json.loads(core.BNGetMemoryMapDescription(self.handle))
@property
def base(self):
"""Formatted string of the base memory map, consisting of unresolved auto and user segments (read-only)."""
return self.format_description(self.description(base=True))
[docs]
def set_logical_memory_map_enabled(self, enabled: bool) -> None:
"""
Enable or disable the logical memory map.
When enabled, the memory map will present a simplified, logical view that merges and abstracts virtual memory
regions based on criteria such as contiguity and flag consistency. This view is designed to provide a higher-level
representation for user analysis, hiding underlying mapping details.
When disabled, the memory map will revert to displaying the virtual view, which corresponds directly to the individual
segments mapped from the raw file without any merging or abstraction.
:param enabled: True to enable the logical view, False to revert to the virtual view.
"""
core.BNSetLogicalMemoryMapEnabled(self.handle, enabled)
[docs]
def add_memory_region(self, name: str, start: int, source: Union['os.PathLike', str, bytes, bytearray, 'BinaryView', 'databuffer.DataBuffer', 'fileaccessor.FileAccessor'], flags: SegmentFlag = 0) -> bool:
"""
Adds a memory region to the memory map. Depending on the source parameter, the memory region is created as one of the following types:
- **BinaryMemoryRegion** (***Unimplemented***): Represents a memory region loaded from a binary format, providing persistence across sessions.
- **DataMemoryRegion**: Represents a memory region loaded from flat files or raw bytes, providing persistence across sessions.
- **RemoteMemoryRegion**: Represents a memory region managed via a proxy callback interface. This region is ephemeral and not persisted across sessions.
The type of memory region created is determined by the `source` parameter:
- `os.PathLike` or `str`: Treated as a file path to be loaded into memory as a `DataMemoryRegion`.
- `bytes` or `bytearray`: Directly loaded into memory as a `DataMemoryRegion`.
- `databuffer.DataBuffer`: Loaded as a `DataMemoryRegion`.
- `fileaccessor.FileAccessor`: Creates a `RemoteMemoryRegion` that fetches data via a remote source.
- `BinaryView`: (Not yet implemented) Intended for future exploration.
.. note:: If no flags are specified and the new memory region overlaps with one or more existing regions, the overlapping portions of the new region will inherit the flags of the respective underlying regions.
Parameters:
name (str): A unique name for the memory region.
start (int): The starting address in memory for the region.
source (Union[os.PathLike, str, bytes, bytearray, BinaryView, databuffer.DataBuffer, fileaccessor.FileAccessor]): The source from which the memory is loaded.
flags (SegmentFlag, optional): Flags to apply to the memory region. Defaults to 0 (no flags).
Returns:
bool: `True` if the memory region was successfully added, `False` otherwise.
Raises:
NotImplementedError: If the specified `source` type is unsupported.
"""
if isinstance(source, os.PathLike):
source = str(source)
if isinstance(source, bytes) or isinstance(source, bytearray):
source = databuffer.DataBuffer(source)
if isinstance(source, str):
with open(source, "rb") as f:
source = databuffer.DataBuffer(f.read())
if name is None:
name = ""
if isinstance(source, BinaryView):
return core.BNAddBinaryMemoryRegion(self.handle, name, start, source.handle, flags)
elif isinstance(source, databuffer.DataBuffer):
return core.BNAddDataMemoryRegion(self.handle, name, start, source.handle, flags)
elif isinstance(source, fileaccessor.FileAccessor):
return core.BNAddRemoteMemoryRegion(self.handle, name, start, source._cb, flags)
else:
raise NotImplementedError
[docs]
def remove_memory_region(self, name: str) -> bool:
return core.BNRemoveMemoryRegion(self.handle, name)
[docs]
def get_active_memory_region_at(self, addr: int) -> str:
return core.BNGetActiveMemoryRegionAt(self.handle, addr)
[docs]
def get_memory_region_flags(self, name: str) -> set:
flags = core.BNGetMemoryRegionFlags(self.handle, name)
return {flag for flag in SegmentFlag if flags & flag}
[docs]
def set_memory_region_flags(self, name: str, flags: SegmentFlag) -> bool:
return core.BNSetMemoryRegionFlags(self.handle, name, flags)
[docs]
def is_memory_region_enabled(self, name: str) -> bool:
return core.BNIsMemoryRegionEnabled(self.handle, name)
[docs]
def set_memory_region_enabled(self, name: str, enabled: bool = True) -> bool:
return core.BNSetMemoryRegionEnabled(self.handle, name, enabled)
[docs]
def is_memory_region_rebaseable(self, name: str) -> bool:
return core.BNIsMemoryRegionRebaseable(self.handle, name)
[docs]
def set_memory_region_rebaseable(self, name: str, rebaseable: bool = True) -> bool:
return core.BNSetMemoryRegionRebaseable(self.handle, name, rebaseable)
[docs]
def get_memory_region_fill(self, name: str) -> int:
return core.BNGetMemoryRegionFill(self.handle, name)
[docs]
def set_memory_region_fill(self, name: str, fill: int) -> bool:
return core.BNSetMemoryRegionFill(self.handle, name, fill)
[docs]
def reset(self):
core.BNResetMemoryMap(self.handle)
[docs]
class BinaryView:
"""
``class BinaryView`` implements a view on binary data, and presents a queryable interface of a binary file. One key
job of BinaryView is file format parsing which allows Binary Ninja to read, write, insert, remove portions
of the file given a virtual address. For the purposes of this documentation we define a virtual address as the
memory address that the various pieces of the physical file will be loaded at.
A binary file does not have to have just one BinaryView, thus much of the interface to manipulate disassembly exists
within or is accessed through a BinaryView. All files are guaranteed to have at least the ``Raw`` BinaryView. The
``Raw`` BinaryView is simply a hex editor, but is helpful for manipulating binary files via their absolute addresses.
BinaryViews are plugins and thus registered with Binary Ninja at startup, and thus should **never** be instantiated
directly as this is already done. The list of available BinaryViews can be seen in the BinaryViewType class which
provides an iterator and map of the various installed BinaryViews::
>>> list(BinaryViewType)
[<view type: 'Raw'>, <view type: 'ELF'>, <view type: 'Mach-O'>, <view type: 'PE'>]
>>> BinaryViewType['ELF']
<view type: 'ELF'>
To open a file with a given BinaryView the following code is recommended:
>>> with load("/bin/ls") as bv:
... bv
<BinaryView: '/bin/ls', start 0x100000000, len 0x142c8>
`By convention in the rest of this document we will use bv to mean an open and, analyzed, BinaryView of an executable file.`
When a BinaryView is open on an executable view analysis is automatically run unless specific named parameters are used
to disable updates. If such a parameter is used, updates can be triggered using the :py:func:`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 :py:func:`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. :py:func:`remove_user_function` rather than :py:func:`remove_function`). Thus use ``_user_`` methods if saving \
to the database is desired.
"""
name: Optional[str] = None
long_name: Optional[str] = None
_registered = False
_registered_cb = None
registered_view_type = None
_associated_data = {}
_registered_instances = []
_cached_instances = {}
@classmethod
def _cache_insert(cls, instance):
key = ctypes.addressof(instance.handle.contents)
if key not in cls._cached_instances:
cls._cached_instances[ctypes.addressof(instance.handle.contents)] = instance
@classmethod
def _cache_remove(cls, handle):
key = ctypes.addressof(handle.contents)
if key in cls._cached_instances:
cls._cached_instances.pop(key)
@classmethod
def _cache_contains(cls, handle):
return ctypes.addressof(handle.contents) in cls._cached_instances
def __new__(cls, file_metadata=None, parent_view=None, handle=None):
if handle:
key = ctypes.addressof(handle.contents)
if key in cls._cached_instances:
core.BNFreeBinaryView(handle) # release the already taken reference since we are pulling from the cache
return cls._cached_instances[key]
return super().__new__(cls)
def __init__(
self, file_metadata: Optional['filemetadata.FileMetadata'] = None, parent_view: Optional['BinaryView'] = None,
handle: Optional[core.BNBinaryViewHandle] = None
):
if handle is not None:
if self.__class__._cache_contains(handle):
return
_handle = handle
if file_metadata is None:
self._file = filemetadata.FileMetadata(handle=core.BNGetFileForView(handle))
else:
self._file = file_metadata
elif self.__class__ is BinaryView:
binaryninja._init_plugins()
if file_metadata is None:
file_metadata = filemetadata.FileMetadata()
_handle = core.BNCreateBinaryDataView(file_metadata.handle)
self._file = filemetadata.FileMetadata(handle=core.BNNewFileReference(file_metadata.handle))
else:
binaryninja._init_plugins()
if not self.__class__._registered:
raise TypeError("view type not registered")
self._cb = core.BNCustomBinaryView()
self._cb.context = 0
self._cb.init = self._cb.init.__class__(self._init)
self._cb.externalRefTaken = self._cb.externalRefTaken.__class__(self._external_ref_taken)
self._cb.externalRefReleased = self._cb.externalRefReleased.__class__(self._external_ref_released)
self._cb.read = self._cb.read.__class__(self._read)
self._cb.write = self._cb.write.__class__(self._write)
self._cb.insert = self._cb.insert.__class__(self._insert)
self._cb.remove = self._cb.remove.__class__(self._remove)
self._cb.getModification = self._cb.getModification.__class__(self._get_modification)
self._cb.isValidOffset = self._cb.isValidOffset.__class__(self._is_valid_offset)
self._cb.isOffsetReadable = self._cb.isOffsetReadable.__class__(self._is_offset_readable)
self._cb.isOffsetWritable = self._cb.isOffsetWritable.__class__(self._is_offset_writable)
self._cb.isOffsetExecutable = self._cb.isOffsetExecutable.__class__(self._is_offset_executable)
self._cb.getNextValidOffset = self._cb.getNextValidOffset.__class__(self._get_next_valid_offset)
self._cb.getStart = self._cb.getStart.__class__(self._get_start)
self._cb.getLength = self._cb.getLength.__class__(self._get_length)
self._cb.getEntryPoint = self._cb.getEntryPoint.__class__(self._get_entry_point)
self._cb.isExecutable = self._cb.isExecutable.__class__(self._is_executable)
self._cb.getDefaultEndianness = self._cb.getDefaultEndianness.__class__(self._get_default_endianness)
self._cb.isRelocatable = self._cb.isRelocatable.__class__(self._is_relocatable)
self._cb.getAddressSize = self._cb.getAddressSize.__class__(self._get_address_size)
self._cb.save = self._cb.save.__class__(self._save)
if file_metadata is None:
raise Exception("Attempting to create a BinaryView with FileMetadata which is None")
self._file = file_metadata
_parent_view = None
if parent_view is not None:
_parent_view = parent_view.handle
_handle = core.BNCreateCustomBinaryView(self.__class__.name, file_metadata.handle, _parent_view, self._cb)
assert _handle is not None
self.handle = _handle
self._notifications = {}
self._parse_only = False
self._preload_limit = 5
self._platform = None
self._endianness = None
def __enter__(self) -> 'BinaryView':
return self
def __exit__(self, type, value, traceback):
self.file.close()
def __del__(self):
if core is None:
return
for i in self._notifications.values():
i._unregister()
core.BNFreeBinaryView(self.handle)
def __repr__(self):
start = self.start
length = self.length
if start != 0:
size = f"start {start:#x}, len {length:#x}"
else:
size = f"len {length:#x}"
filename = self._file.filename
if len(filename) > 0:
return f"<BinaryView: '{filename}', {size}>"
return f"<BinaryView: {size}>"
@property
def length(self):
return int(core.BNGetViewLength(self.handle))
def __bool__(self):
return True
def __eq__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return ctypes.addressof(self.handle.contents) == ctypes.addressof(other.handle.contents)
def __ne__(self, other):
if not isinstance(other, self.__class__):
return NotImplemented
return not (self == other)
def __hash__(self):
return hash(ctypes.addressof(self.handle.contents))
def __iter__(self) -> Generator['_function.Function', None, None]:
yield from self.functions
def __getitem__(self, i) -> bytes:
if isinstance(i, tuple):
result = bytes()
for s in i:
result += self.__getitem__(s)
return result
elif isinstance(i, slice):
if i.step is not None:
raise IndexError("step not implemented")
i = i.indices(self.end)
start = i[0]
stop = i[1]
if stop <= start:
return b""
return self.read(start, stop - start)
elif i < 0:
if i >= -self.length:
value = self.read(self.start + int(self.length + i), 1)
if len(value) == 0:
raise IndexError("index not readable")
return value
raise IndexError("index out of range")
elif (i >= self.start) and (i < self.end):
value = self.read(int(i), 1)
if len(value) == 0:
raise IndexError("index not readable")
return value
else:
raise IndexError("index out of range")
def __setitem__(self, i, value):
if isinstance(i, slice):
if i.step is not None:
raise IndexError("step not supported on assignment")
i = i.indices(self.end)
start = i[0]
stop = i[1]
if stop < start:
stop = start
if len(value) != (stop - start):
self.remove(start, stop - start)
self.insert(start, value)
else:
self.write(start, value)
elif i < 0:
if i >= -self.length:
if len(value) != 1:
raise ValueError("expected single byte for assignment")
if self.write(self.start + int(self.length + i), value) != 1:
raise IndexError("index not writable")
else:
raise IndexError("index out of range")
elif (i >= self.start) and (i < self.end):
if len(value) != 1:
raise ValueError("expected single byte for assignment")
if self.write(int(i), value) != 1:
raise IndexError("index not writable")
else:
raise IndexError("index out of range")
def __contains__(self, i: int):
for s in self.segments:
if i in s:
return True
return False
[docs]
@classmethod
def register(cls) -> None:
binaryninja._init_plugins()
if cls.name is None:
raise ValueError("view 'name' not defined")
if cls.long_name is None:
cls.long_name = cls.name
cls._registered_cb = core.BNCustomBinaryViewType()
cls._registered_cb.context = 0
cls._registered_cb.create = cls._registered_cb.create.__class__(cls._create)
cls._registered_cb.parse = cls._registered_cb.parse.__class__(cls._parse)
cls._registered_cb.isValidForData = cls._registered_cb.isValidForData.__class__(cls._is_valid_for_data)
cls._registered_cb.isDeprecated = cls._registered_cb.isDeprecated.__class__(cls._is_deprecated)
cls._registered_cb.isForceLoadable = cls._registered_cb.isForceLoadable.__class__(cls._is_force_loadable)
cls._registered_cb.getLoadSettingsForData = cls._registered_cb.getLoadSettingsForData.__class__(
cls._get_load_settings_for_data
)
view_handle = core.BNRegisterBinaryViewType(cls.name, cls.long_name, cls._registered_cb)
assert view_handle is not None, "core.BNRegisterBinaryViewType returned None"
cls.registered_view_type = BinaryViewType(view_handle)
cls._registered = True
@property
def parse_only(self) -> bool:
return self._parse_only
@parse_only.setter
def parse_only(self, value: bool) -> None:
self._parse_only = value
@classmethod
def _create(cls, ctxt, data: core.BNBinaryView):
try:
file_metadata = filemetadata.FileMetadata(handle=core.BNGetFileForView(data))
view = cls(BinaryView(file_metadata=file_metadata, handle=core.BNNewViewReference(data))) # type: ignore
if view is None:
return None
view.parse_only = False
view_handle = core.BNNewViewReference(view.handle)
assert view_handle is not None, "core.BNNewViewReference returned None"
return ctypes.cast(view_handle, ctypes.c_void_p).value
except:
log_error(traceback.format_exc())
return None
@classmethod
def _parse(cls, ctxt, data: core.BNBinaryView):
try:
file_metadata = filemetadata.FileMetadata(handle=core.BNGetFileForView(data))
view = cls(BinaryView(file_metadata=file_metadata, handle=core.BNNewViewReference(data))) # type: ignore
if view is None:
return None
view.parse_only = True
view_handle = core.BNNewViewReference(view.handle)
assert view_handle is not None, "core.BNNewViewReference returned None"
return ctypes.cast(view_handle, ctypes.c_void_p).value
except:
log_error(traceback.format_exc())
return None
@classmethod
def _is_valid_for_data(cls, ctxt, data):
try:
# I'm not sure whats going on here even so I've suppressed the linter warning
return cls.is_valid_for_data(BinaryView(handle=core.BNNewViewReference(data))) # type: ignore
except:
log_error(traceback.format_exc())
return False
@classmethod
def _is_deprecated(cls, ctxt):
# Since the is_deprecated() method is newly added, existing code may not have it at all
# So here we do not consider it as an error
if not callable(getattr(cls, 'is_deprecated', None)):
return False
try:
return cls.is_deprecated() # type: ignore
except:
log_error(traceback.format_exc())
return False
@classmethod
def _is_force_loadable(cls, ctxt):
if not callable(getattr(cls, 'is_force_loadable', None)):
return False
try:
return cls.is_force_loadable() # type: ignore
except:
log_error(traceback.format_exc())
return False
@classmethod
def _get_load_settings_for_data(cls, ctxt, data):
try:
attr = getattr(cls, "get_load_settings_for_data", None)
if callable(attr):
result = cls.get_load_settings_for_data(
BinaryView(handle=core.BNNewViewReference(data))
) # type: ignore
settings_handle = core.BNNewSettingsReference(result.handle)
assert settings_handle is not None, "core.BNNewSettingsReference returned None"
return ctypes.cast(settings_handle, ctypes.c_void_p).value
else:
return None
except:
log_error(traceback.format_exc())
return None
[docs]
@staticmethod
def open(src, file_metadata=None) -> Optional['BinaryView']:
binaryninja._init_plugins()
if isinstance(src, fileaccessor.FileAccessor):
if file_metadata is None:
file_metadata = filemetadata.FileMetadata()
view = core.BNCreateBinaryDataViewFromFile(file_metadata.handle, src._cb)
else:
if file_metadata is None:
file_metadata = filemetadata.FileMetadata(str(src))
view = core.BNCreateBinaryDataViewFromFilename(file_metadata.handle, str(src))
if view is None:
return None
return BinaryView(file_metadata=file_metadata, handle=view)
[docs]
@staticmethod
def new(data: Optional[Union[bytes, bytearray, 'databuffer.DataBuffer']] = None, file_metadata: Optional['filemetadata.FileMetadata'] = None) -> Optional['BinaryView']:
"""
``new`` creates a new, Raw :py:class:`BinaryView` for the provided data.
:param data: path to file/bndb, raw bytes, or raw view to load
:type data: Union[:py:class:`str`, :py:class:`bytes`, :py:class:`bytearray`, :py:class:`~binaryninja.databuffer.DataBuffer`, :py:class:`os.PathLike`, :py:class:`BinaryView`]
:param file_metadata: Optional FileMetadata object for this new view
:type file_metadata: :py:class:`~binaryninja.filemetadata.FileMetadata`
:return: returns a :py:class:`BinaryView` object for the given filename or ``None``
:rtype: :py:class:`BinaryView` or ``None``
:Example:
>>> binaryninja.load('/bin/ls', options={'loader.imageBase': 0xfffffff0000, 'loader.macho.processFunctionStarts' : False})
<BinaryView: '/bin/ls', start 0xfffffff0000, len 0xa290>
>>>
"""
binaryninja._init_plugins()
if file_metadata is None:
file_metadata = filemetadata.FileMetadata()
if data is None:
view = core.BNCreateBinaryDataView(file_metadata.handle)
elif isinstance(data, databuffer.DataBuffer):
view = core.BNCreateBinaryDataViewFromBuffer(file_metadata.handle, data.handle)
else:
buf = databuffer.DataBuffer(data)
view = core.BNCreateBinaryDataViewFromBuffer(file_metadata.handle, buf.handle)
if view is None:
return None
return BinaryView(file_metadata=file_metadata, handle=view)
[docs]
@staticmethod
def load(source: Union[str, bytes, bytearray, 'databuffer.DataBuffer', 'os.PathLike', 'BinaryView', 'project.ProjectFile'], update_analysis: bool = True,
progress_func: Optional[ProgressFuncType] = None, options: Mapping[str, Any] = {}) -> Optional['BinaryView']:
"""
``load`` opens, generates default load options (which are overridable), and returns the first available \
:py:class:`BinaryView`. If no :py:class:`BinaryViewType` is available, then a ``Mapped`` :py:class:`BinaryViewType` is used to load \
the :py:class:`BinaryView` with the specified load options. The ``Mapped`` view type attempts to auto-detect the architecture of the \
file during initialization. If no architecture is detected or specified in the load options, then the ``Mapped`` view type fails to \
initialize and returns ``None``.
.. note:: Although general container file support is not complete, support for Universal archives exists. It's possible to control the architecture preference \
with the **'files.universal.architecturePreference'** setting. This setting is scoped to SettingsUserScope and can be modified as follows ::
>>> Settings().set_string_list("files.universal.architecturePreference", ["arm64"])
It's also possible to override the **'files.universal.architecturePreference'** user setting by specifying it directly with :py:func:`load`.
This specific usage of this setting is experimental and may change in the future ::
>>> bv = binaryninja.load('/bin/ls', options={'files.universal.architecturePreference': ['arm64']})
.. warning:: The recommended code pattern for opening a BinaryView is to use the \
:py:func:`~binaryninja.load` API as a context manager like ``with load('/bin/ls') as bv:`` \
which will automatically clean up when done with the view. If using this API directly \
you will need to call `bv.file.close()` before the BinaryView leaves scope to ensure the \
reference is properly removed and prevents memory leaks.
:param Union[str, bytes, bytearray, 'databuffer.DataBuffer', 'os.PathLike', 'BinaryView'] source: path to file/bndb, raw bytes, or raw view to load
:param bool update_analysis: whether or not to run :py:func:`~BinaryView.update_analysis_and_wait` after opening a :py:class:`BinaryView`, defaults to ``True``
:param callback progress_func: optional function to be called with the current progress and total count
:param dict options: a dictionary in the form {setting identifier string : object value}
:return: returns a :py:class:`BinaryView` object for the given filename or ``None``
:rtype: :py:class:`BinaryView` or ``None``
:Example:
>>> binaryninja.load('/bin/ls', options={'loader.imageBase': 0xfffffff0000, 'loader.macho.processFunctionStarts' : False})
<BinaryView: '/bin/ls', start 0xfffffff0000, len 0xa290>
>>>
"""
binaryninja._init_plugins()
if progress_func is None:
progress_cfunc = ctypes.CFUNCTYPE(ctypes.c_bool, ctypes.c_void_p, ctypes.c_ulonglong, ctypes.c_ulonglong)(lambda ctxt, cur, total: True)
else:
progress_cfunc = ctypes.CFUNCTYPE(ctypes.c_bool, ctypes.c_void_p, ctypes.c_ulonglong, ctypes.c_ulonglong)(lambda ctxt, cur, total: progress_func(cur, total))
if isinstance(source, os.PathLike):
source = str(source)
if isinstance(source, BinaryView):
handle = core.BNLoadBinaryView(source.handle, update_analysis, json.dumps(options), progress_cfunc, None)
elif isinstance(source, project.ProjectFile):
handle = core.BNLoadProjectFile(source._handle, update_analysis, json.dumps(options), progress_cfunc, None)
elif isinstance(source, str):
handle = core.BNLoadFilename(source, update_analysis, json.dumps(options), progress_cfunc, None)
elif isinstance(source, bytes) or isinstance(source, bytearray) or isinstance(source, databuffer.DataBuffer):
raw_view = BinaryView.new(source)
handle = core.BNLoadBinaryView(raw_view.handle, update_analysis, json.dumps(options), progress_cfunc, None)
else:
raise NotImplementedError
return BinaryView(handle=handle) if handle else None
@classmethod
def _unregister(cls, view: core.BNBinaryView) -> None:
handle = ctypes.cast(view, ctypes.c_void_p)
if handle.value in cls._associated_data:
del cls._associated_data[handle.value]
[docs]
@staticmethod
def set_default_session_data(name: str, value: str) -> None:
"""
``set_default_session_data`` saves a variable to the BinaryView. Session data is ephemeral not saved to a database. Consider using :py:func:`store_metadata` if permanence is needed.
:param str name: name of the variable to be saved
:param str value: value of the variable to be saved
:Example:
>>> BinaryView.set_default_session_data("variable_name", "value")
>>> bv.session_data.variable_name
'value'
"""
_BinaryViewAssociatedDataStore.set_default(name, value)
@property
def preload_limit(self) -> int:
return self._preload_limit
@preload_limit.setter
def preload_limit(self, value: int) -> None:
self._preload_limit = value
@property
def basic_blocks(self) -> Generator['basicblock.BasicBlock', None, None]:
"""A generator of all BasicBlock objects in the BinaryView"""
for func in self:
yield from func.basic_blocks
@property
def llil_basic_blocks(self) -> Generator['lowlevelil.LowLevelILBasicBlock', None, None]:
"""A generator of all LowLevelILBasicBlock objects in the BinaryView"""
for func in self:
llil = func.low_level_il
if llil is not None:
yield from llil.basic_blocks
@property
def mlil_basic_blocks(self) -> Generator['mediumlevelil.MediumLevelILBasicBlock', None, None]:
"""A generator of all MediumLevelILBasicBlock objects in the BinaryView"""
for func in self.mlil_functions():
yield from func.basic_blocks
@property
def hlil_basic_blocks(self) -> Generator['highlevelil.HighLevelILBasicBlock', None, None]:
"""A generator of all HighLevelILBasicBlock objects in the BinaryView"""
for func in self.hlil_functions():
yield from func.basic_blocks
@property
def instructions(self) -> InstructionsType:
"""A generator of instruction tokens and their start addresses"""
for block in self.basic_blocks:
start = block.start
for i in block:
yield (i[0], start)
start += i[1]
@property
def llil_instructions(self) -> 'lowlevelil.LLILInstructionsType':
"""A generator of llil instructions"""
for block in self.llil_basic_blocks:
yield from block
@property
def mlil_instructions(self) -> Generator['mediumlevelil.MediumLevelILInstruction', None, None]:
"""A generator of mlil instructions"""
for block in self.mlil_basic_blocks:
yield from block
@property
def hlil_instructions(self) -> 'highlevelil.HLILInstructionsType':
"""A generator of hlil instructions"""
for block in self.hlil_basic_blocks:
yield from block
@property
def parent_view(self) -> Optional['BinaryView']:
"""View that contains the raw data used by this view (read-only)"""
result = core.BNGetParentView(self.handle)
if result is None:
return None
return BinaryView(handle=result)
@property
def modified(self) -> bool:
"""boolean modification state of the BinaryView (read/write)"""
return self._file.modified
@modified.setter
def modified(self, value: bool) -> None:
self._file.modified = value
@property
def analysis_changed(self) -> bool:
"""boolean analysis state changed of the currently running analysis (read-only)"""
return self._file.analysis_changed
@property
def has_database(self) -> bool:
"""boolean has a database been written to disk (read-only)"""
return self._file.has_database
@property
def view(self) -> 'str':
return self._file.view
@view.setter
def view(self, value: str) -> None:
self._file.view = value
@property
def offset(self) -> int:
return self._file.offset
@offset.setter
def offset(self, value: int) -> None:
self._file.offset = value
@property
def file(self) -> 'filemetadata.FileMetadata':
""":py:class:`~binaryninja.filemetadata.FileMetadata` backing the BinaryView """
return self._file
@property
def image_base(self) -> int:
"""Image base of the binary"""
return core.BNGetImageBase(self.handle)
@property
def original_image_base(self) -> int:
"""Original image base of the binary"""
return core.BNGetOriginalImageBase(self.handle)
@original_image_base.setter
def original_image_base(self, image_base: int) -> None:
"""Set original image base of the binary. Only intended for binary view implementations"""
return core.BNSetOriginalImageBase(self.handle, image_base)
@property
def original_base(self) -> int:
"""Original image base of the binary. Deprecated: 4.1.5902 Use `original_image_base` instead."""
return core.BNGetOriginalImageBase(self.handle)
@original_base.setter
def original_base(self, base: int) -> None:
"""Set original image base of the binary. Only intended for binary view implementations. Deprecated: 4.1.5902 Use `original_image_base` instead."""
return core.BNSetOriginalImageBase(self.handle, base)
@property
def start(self) -> int:
"""Start offset of the binary (read-only)"""
return core.BNGetStartOffset(self.handle)
@property
def end(self) -> int:
"""End offset of the binary (read-only)"""
return core.BNGetEndOffset(self.handle)
@property
def entry_point(self) -> int:
"""Entry point of the binary (read-only)"""
return core.BNGetEntryPoint(self.handle)
@property
def arch(self) -> Optional['architecture.Architecture']:
"""The architecture associated with the current :py:class:`BinaryView` (read/write)"""
arch = core.BNGetDefaultArchitecture(self.handle)
if arch is None:
return None
return architecture.CoreArchitecture._from_cache(handle=arch)
@arch.setter
def arch(self, value: 'architecture.Architecture') -> None:
if value is None:
core.BNSetDefaultArchitecture(self.handle, None)
else:
core.BNSetDefaultArchitecture(self.handle, value.handle)
@property
def platform(self) -> Optional['_platform.Platform']:
"""The platform associated with the current BinaryView (read/write)"""
if self._platform is not None:
return self._platform
plat = core.BNGetDefaultPlatform(self.handle)
if plat is None:
return None
self._platform = _platform.CorePlatform._from_cache(handle=plat)
return self._platform
@platform.setter
def platform(self, value: Optional['_platform.Platform']) -> None:
if value is None:
core.BNSetDefaultPlatform(self.handle, None)
else:
core.BNSetDefaultPlatform(self.handle, value.handle)
self._platform = None
@property
def endianness(self) -> Endianness:
"""Endianness of the binary (read-only)"""
if self._endianness is None:
self._endianness = Endianness(core.BNGetDefaultEndianness(self.handle))
return self._endianness
@property
def relocatable(self) -> bool:
"""Boolean - is the binary relocatable (read-only)"""
return core.BNIsRelocatable(self.handle)
@property
def address_size(self) -> int:
"""Address size of the binary (read-only)"""
return core.BNGetViewAddressSize(self.handle)
@property
def executable(self) -> bool:
"""Whether the binary is an executable (read-only)"""
return core.BNIsExecutableView(self.handle)
@property
def functions(self) -> FunctionList:
"""returns a FunctionList object (read-only)"""
return FunctionList(self)
[docs]
def mlil_functions(
self, preload_limit: Optional[int] = None,
function_generator: Optional[Generator['_function.Function', None, None]] = None
) -> Generator['mediumlevelil.MediumLevelILFunction', None, None]:
"""
Generates a list of il functions. This method should be used instead of 'functions' property if
MLIL is needed and performance is a concern.
"""
for func in AdvancedILFunctionList(
self, self.preload_limit if preload_limit is None else preload_limit, function_generator
):
try:
yield func.mlil
except ILException:
pass
[docs]
def hlil_functions(
self, preload_limit: Optional[int] = None,
function_generator: Optional[Generator['_function.Function', None, None]] = None
) -> Generator['highlevelil.HighLevelILFunction', None, None]:
"""
Generates a list of il functions. This method should be used instead of 'functions' property if
HLIL is needed and performance is a concern.
"""
for func in AdvancedILFunctionList(
self, self.preload_limit if preload_limit is None else preload_limit, function_generator
):
try:
yield func.hlil
except ILException:
pass
@property
def has_functions(self) -> bool:
"""Boolean whether the binary has functions (read-only)"""
return core.BNHasFunctions(self.handle)
@property
def has_symbols(self) -> bool:
"""Boolean whether the binary has symbols (read-only)"""
return core.BNHasSymbols(self.handle)
@property
def has_data_variables(self) -> bool:
"""Boolean whether the binary has data variables (read-only)"""
return core.BNHasDataVariables(self.handle)
@property
def entry_function(self) -> Optional['_function.Function']:
"""Entry function (read-only)"""
func = core.BNGetAnalysisEntryPoint(self.handle)
if func is None:
return None
return _function.Function(self, func)
@property
def entry_functions(self) -> FunctionList:
"""A List of entry functions (read-only)
This list contains vanilla entry function, and functions like init_array, fini_array, and TLS callbacks etc.
User-added entry functions(via `add_entry_point`) are also included.
We see `entry_functions` as good starting points for analysis, these functions normally don't have internal references.
However, note that exported functions in a dll/so file are not included.
Note the difference with `entry_function`
:Example:
>>> bv.entry_function
<func: x86@0x4014c8>
>>> bv.entry_functions
[<func: x86@0x4014c8>, <func: x86@0x401618>]
:return: a list of functions, containing the vanilla entry and other platform-specific entry functions
:rtype: list(Function)
"""
count = ctypes.c_ulonglong(0)
funcs = core.BNGetAllEntryFunctions(self.handle, count)
assert funcs is not None, "core.BNGetAllEntryFunctions returned None"
result = []
try:
for i in range(0, count.value):
result.append(_function.Function(self, core.BNNewFunctionReference(funcs[i])))
return result
finally:
core.BNFreeFunctionList(funcs, count.value)
@property
def symbols(self) -> SymbolMapping:
"""
Dict of symbols (read-only)
Items in the dict are lists of all symbols matching that name.
:Example:
>>> bv.symbols['_main']
[<FunctionSymbol: "_main" @ 0x1dd0>]
>>> list(bv.symbols)
['_start', '_main', '_printf', '_scanf', ...]
>>> bv.symbols['foo']
KeyError: "'foo': symbol not found"
:return: a dict-like generator of symbol names and values
:rtype: Generator[str, None, None]
"""
return SymbolMapping(self)
[docs]
@staticmethod
def internal_namespace() -> '_types.NameSpace':
"""Internal namespace for the current BinaryView"""
ns = core.BNGetInternalNameSpace()
try:
return _types.NameSpace._from_core_struct(ns)
finally:
core.BNFreeNameSpace(ns)
[docs]
@staticmethod
def external_namespace() -> '_types.NameSpace':
"""External namespace for the current BinaryView"""
ns = core.BNGetExternalNameSpace()
try:
return _types.NameSpace._from_core_struct(ns)
finally:
core.BNFreeNameSpace(ns)
@property
def namespaces(self) -> List['_types.NameSpace']:
"""Returns a list of namespaces for the current BinaryView"""
count = ctypes.c_ulonglong(0)
nameSpaceList = core.BNGetNameSpaces(self.handle, count)
assert nameSpaceList is not None, "core.BNGetNameSpaces returned None"
result = []
try:
for i in range(count.value):
result.append(_types.NameSpace._from_core_struct(nameSpaceList[i]))
return result
finally:
core.BNFreeNameSpaceList(nameSpaceList, count.value)
@property
def view_type(self) -> str:
"""View type (read-only)"""
return core.BNGetViewType(self.handle)
@property
def available_view_types(self) -> List[BinaryViewType]:
"""Available view types (read-only)"""
count = ctypes.c_ulonglong(0)
types = core.BNGetBinaryViewTypesForData(self.handle, count)
result = []
if types is None:
return result
try:
for i in range(0, count.value):
result.append(BinaryViewType(types[i]))
return result
finally:
core.BNFreeBinaryViewTypeList(types)
@property
def strings(self) -> List['StringReference']:
"""List of strings (read-only)"""
return self.get_strings()
@property
def saved(self) -> bool:
"""boolean state of whether or not the file has been saved (read/write)"""
return self._file.saved
@saved.setter
def saved(self, value: bool) -> None:
self._file.saved = value
@property
def analysis_info(self) -> AnalysisInfo:
"""Provides instantaneous analysis state information and a list of current functions under analysis (read-only).
All times are given in units of milliseconds (ms). Per-function `analysis_time` is the aggregation of time spent
performing incremental updates and is reset on a full function update. Per-function `update_count` tracks the
current number of incremental updates and is reset on a full function update. Per-function `submit_count` tracks the
current number of full updates that have completed.
.. note:: `submit_count` is currently not reset across analysis updates.
"""
info_ref = core.BNGetAnalysisInfo(self.handle)
assert info_ref is not None, "core.BNGetAnalysisInfo returned None"
info = info_ref[0]
active_info_list: List[ActiveAnalysisInfo] = []
try:
for i in range(0, info.count):
func = _function.Function(self, core.BNNewFunctionReference(info.activeInfo[i].func))
active_info = ActiveAnalysisInfo(
func, info.activeInfo[i].analysisTime, info.activeInfo[i].updateCount,
info.activeInfo[i].submitCount
)
active_info_list.append(active_info)
return AnalysisInfo(info.state, info.analysisTime, active_info_list)
finally:
core.BNFreeAnalysisInfo(info_ref)
@property
def analysis_progress(self) -> AnalysisProgress:
"""Status of current analysis (read-only)"""
result = core.BNGetAnalysisProgress(self.handle)
return AnalysisProgress(result.state, result.count, result.total)
@property
def linear_disassembly(self) -> Iterator['lineardisassembly.LinearDisassemblyLine']:
"""Iterator for all lines in the linear disassembly of the view"""
return self.get_linear_disassembly(None)
@property
def data_vars(self) -> Mapping[int, 'DataVariable']:
"""List of data variables (read-only)"""
count = ctypes.c_ulonglong(0)
var_list = core.BNGetDataVariables(self.handle, count)
assert var_list is not None, "core.BNGetDataVariables returned None"
result = {}
try:
for i in range(0, count.value):
result[var_list[i].address] = DataVariable.from_core_struct(var_list[i], self)
return result
finally:
core.BNFreeDataVariables(var_list, count.value)
@property
def types(self) -> TypeMapping:
return TypeMapping(self)
@property
def dependency_sorted_types(self) -> TypeMapping:
"""
List of all types, sorted such that types are after all types on which they depend (read-only)
Order is guaranteed for any collection of types with no cycles. If you have cycles \
in type dependencies, order for types in a cycle is not guaranteed.
.. note:: Dependency order is based on named type references for all non-structure types, i.e. \
``struct Foo m_foo`` will induce a dependency, whereas ``struct Foo* m_pFoo`` will not.
:return: sorted types as defined above
"""
return TypeMapping(self, core.BNGetAnalysisDependencySortedTypeList)
@property
def type_names(self) -> List['_types.QualifiedName']:
"""List of defined type names (read-only)"""
count = ctypes.c_ulonglong(0)
name_list = core.BNGetAnalysisTypeNames(self.handle, count, "")
assert name_list is not None, "core.BNGetAnalysisTypeNames returned None"
result = []
try:
for i in range(0, count.value):
result.append(_types.QualifiedName._from_core_struct(name_list[i]))
return result
finally:
core.BNFreeTypeNameList(name_list, count.value)
@property
def type_libraries(self) -> List['typelibrary.TypeLibrary']:
"""List of imported type libraries (read-only)"""
count = ctypes.c_ulonglong(0)
libraries = core.BNGetBinaryViewTypeLibraries(self.handle, count)
assert libraries is not None, "core.BNGetBinaryViewTypeLibraries returned None"
result = []
try:
for i in range(0, count.value):
result.append(typelibrary.TypeLibrary(core.BNNewTypeLibraryReference(libraries[i])))
return result
finally:
core.BNFreeTypeLibraryList(libraries, count.value)
@property
def attached_type_archives(self) -> Mapping['str', 'str']:
"""All attached type archive ids and paths (read-only)"""
ids = ctypes.POINTER(ctypes.c_char_p)()
paths = ctypes.POINTER(ctypes.c_char_p)()
count = core.BNBinaryViewGetTypeArchives(self.handle, ids, paths)
result = {}
try:
for i in range(0, count):
result[core.pyNativeStr(ids[i])] = core.pyNativeStr(paths[i])
return result
finally:
core.BNFreeStringList(ids, count)
core.BNFreeStringList(paths, count)
@property
def connected_type_archives(self) -> List['typearchive.TypeArchive']:
"""All connected type archive objects (read-only)"""
result = []
for (id, path) in self.attached_type_archives.items():
archive = self.get_type_archive(id)
if archive is not None:
result.append(archive)
return result
@property
def segments(self) -> List['Segment']:
"""List of resolved segments (read-only)"""
count = ctypes.c_ulonglong(0)
segment_list = core.BNGetSegments(self.handle, count)
assert segment_list is not None, "core.BNGetSegments returned None"
result = []
try:
for i in range(0, count.value):
segment_handle = core.BNNewSegmentReference(segment_list[i])
assert segment_handle is not None, "core.BNNewSegmentReference returned None"
result.append(Segment(segment_handle))
return result
finally:
core.BNFreeSegmentList(segment_list, count.value)
@property
def sections(self) -> Mapping[str, 'Section']:
"""Dictionary of sections (read-only)"""
count = ctypes.c_ulonglong(0)
section_list = core.BNGetSections(self.handle, count)
assert section_list is not None, "core.BNGetSections returned None"
result = {}
try:
for i in range(0, count.value):
section_handle = core.BNNewSectionReference(section_list[i])
assert section_handle is not None, "core.BNNewSectionReference returned None"
result[core.BNSectionGetName(section_list[i])] = Section(section_handle)
return result
finally:
core.BNFreeSectionList(section_list, count.value)
@property
def allocated_ranges(self) -> List['variable.AddressRange']:
"""List of valid address ranges for this view (read-only) Deprecated: 4.1.5902 Use mapped_address_ranges instead."""
count = ctypes.c_ulonglong(0)
range_list = core.BNGetAllocatedRanges(self.handle, count)
assert range_list is not None, "core.BNGetAllocatedRanges returned None"
result = []
try:
for i in range(0, count.value):
result.append(variable.AddressRange(range_list[i].start, range_list[i].end))
return result
finally:
core.BNFreeAddressRanges(range_list)
@property
def mapped_address_ranges(self) -> List['variable.AddressRange']:
"""List of mapped address ranges for this view (read-only)"""
count = ctypes.c_ulonglong(0)
range_list = core.BNGetMappedAddressRanges(self.handle, count)
assert range_list is not None, "core.BNGetMappedAddressRanges returned None"
result = []
try:
for i in range(0, count.value):
result.append(variable.AddressRange(range_list[i].start, range_list[i].end))
return result
finally:
core.BNFreeAddressRanges(range_list)
@property
def backed_address_ranges(self) -> List['variable.AddressRange']:
"""List of backed address ranges for this view (read-only)"""
count = ctypes.c_ulonglong(0)
range_list = core.BNGetBackedAddressRanges(self.handle, count)
assert range_list is not None, "core.BNGetBackedAddressRanges returned None"
result = []
try:
for i in range(0, count.value):
result.append(variable.AddressRange(range_list[i].start, range_list[i].end))
return result
finally:
core.BNFreeAddressRanges(range_list)
@property
def session_data(self): # TODO add type hint
"""Dictionary object where plugins can store arbitrary data associated with the view. This data is ephemeral and not saved to a database. Consider using :py:func:`store_metadata` if permanence is needed."""
handle = ctypes.cast(self.handle, ctypes.c_void_p)
if handle.value not in BinaryView._associated_data:
obj = _BinaryViewAssociatedDataStore()
BinaryView._associated_data[handle.value] = obj
return obj
else:
return BinaryView._associated_data[handle.value]
@property
def global_pointer_value(self) -> 'variable.RegisterValue':
"""Discovered value of the global pointer register, if the binary uses one (read-only)"""
result = core.BNGetGlobalPointerValue(self.handle)
return variable.RegisterValue.from_BNRegisterValue(result, self.arch)
@property
def user_global_pointer_value_set(self) -> bool:
"""Check whether a user global pointer value has been set"""
return core.BNUserGlobalPointerValueSet(self.handle)
[docs]
def clear_user_global_pointer_value(self):
"""Clear a previously set user global pointer value, so the auto-analysis can calculate a new value"""
core.BNClearUserGlobalPointerValue(self.handle)
[docs]
def set_user_global_pointer_value(self, value: variable.RegisterValue, confidence = 255):
"""
Set a user global pointer value. This is useful when the auto analysis fails to find out the value of the global
pointer, or the value is wrong. In this case, we can call `set_user_global_pointer_value` with a
`ConstantRegisterValue` or `ConstantPointerRegisterValue`to provide a user global pointer value to assist the
analysis.
On the other hand, if the auto analysis figures out a global pointer value, but there should not be one, we can
call `set_user_global_pointer_value` with an `Undetermined` value to override it.
Whenever a user global pointer value is set/cleared, an analysis update must occur for it to take effect and
all functions using the global pointer to be updated.
We can use `user_global_pointer_value_set` to query whether a user global pointer value is set, and use
`clear_user_global_pointer_value` to clear a user global pointer value. Note, `clear_user_global_pointer_value`
is different from calling `set_user_global_pointer_value` with an `Undetermined` value. The former clears the
user global pointer value and let the analysis decide the global pointer value, whereas the latte forces the
global pointer value to become undetermined.
:param variable.RegisterValue value: the user global pointer value to be set
:param int confidence: the confidence value of the user global pointer value. In most cases this should be set
to 255. Setting a value lower than the confidence of the global pointer value from the auto analysis will cause
undesired effect.
:return:
:Example:
>>> bv.global_pointer_value
<const ptr 0x3fd4>
>>> bv.set_user_global_pointer_value(ConstantPointerRegisterValue(0x12345678))
>>> bv.global_pointer_value
<const ptr 0x12345678>
>>> bv.user_global_pointer_value_set
True
>>> bv.clear_user_global_pointer_value()
>>> bv.global_pointer_value
<const ptr 0x3fd4>
>>> bv.set_user_global_pointer_value(Undetermined())
>>> bv.global_pointer_value
<undetermined>
"""
val = core.BNRegisterValueWithConfidence()
val.value = value._to_core_struct()
val.confidence = confidence
core.BNSetUserGlobalPointerValue(self.handle, val)
@property
def parameters_for_analysis(self):
return core.BNGetParametersForAnalysis(self.handle)
@parameters_for_analysis.setter
def parameters_for_analysis(self, params):
core.BNSetParametersForAnalysis(self.handle, params)
@property
def max_function_size_for_analysis(self) -> int:
"""Maximum size of function (sum of basic block sizes in bytes) for auto analysis"""
return core.BNGetMaxFunctionSizeForAnalysis(self.handle)
@max_function_size_for_analysis.setter
def max_function_size_for_analysis(self, size: int) -> None:
core.BNSetMaxFunctionSizeForAnalysis(self.handle, size)
[docs]
def relocations_at(self, addr: int) -> List[Relocation]:
"""List of relocations for a given address"""
count = ctypes.c_ulonglong()
relocs = core.BNGetRelocationsAt(self.handle, addr, count)
assert relocs is not None, "core.BNGetRelocationRanges returned None"
result = []
try:
for i in range(0, count.value):
reloc_handle = core.BNNewRelocationReference(relocs[i])
assert reloc_handle is not None, "core.BNNewRelocationReference is not None"
result.append(Relocation(reloc_handle))
return result
finally:
core.BNFreeRelocationList(relocs, count)
@property
def relocation_ranges(self) -> List[Tuple[int, int]]:
"""List of relocation range tuples (read-only)"""
count = ctypes.c_ulonglong()
ranges = core.BNGetRelocationRanges(self.handle, count)
assert ranges is not None, "core.BNGetRelocationRanges returned None"
try:
return [(ranges[i].start, ranges[i].end) for i in range(count.value)]
finally:
core.BNFreeRelocationRanges(ranges)
[docs]
def relocation_ranges_at(self, addr: int) -> List[Tuple[int, int]]:
"""List of relocation range tuples for a given address"""
count = ctypes.c_ulonglong()
ranges = core.BNGetRelocationRangesAtAddress(self.handle, addr, count)
assert ranges is not None, "core.BNGetRelocationRangesAtAddress returned None"
try:
return [(ranges[i].start, ranges[i].end) for i in range(count.value)]
finally:
core.BNFreeRelocationRanges(ranges)
[docs]
def relocation_ranges_in_range(self, addr: int, size: int) -> List[Tuple[int, int]]:
"""List of relocation range tuples for a given range"""
count = ctypes.c_ulonglong()
ranges = core.BNGetRelocationRangesInRange(self.handle, addr, size, count)
assert ranges is not None, "core.BNGetRelocationRangesInRange returned None"
try:
return [(ranges[i].start, ranges[i].end) for i in range(count.value)]
finally:
core.BNFreeRelocationRanges(ranges)
[docs]
def range_contains_relocation(self, addr: int, size: int) -> bool:
"""Checks if the specified range overlaps with a relocation"""
return core.BNRangeContainsRelocation(self.handle, addr, size)
@property
def new_auto_function_analysis_suppressed(self) -> bool:
"""Whether or not automatically discovered functions will be analyzed"""
return core.BNGetNewAutoFunctionAnalysisSuppressed(self.handle)
@new_auto_function_analysis_suppressed.setter
def new_auto_function_analysis_suppressed(self, suppress: bool) -> None:
core.BNSetNewAutoFunctionAnalysisSuppressed(self.handle, suppress)
@property
def project(self) -> Optional['project.Project']:
return self.file.project
@property
def project_file(self) -> Optional['project.ProjectFile']:
return self.file.project_file
def _init(self, ctxt):
try:
return self.init()
except:
log_error(traceback.format_exc())
return False
def _external_ref_taken(self, ctxt):
try:
self.__class__._registered_instances.append(self)
except:
log_error(traceback.format_exc())
def _external_ref_released(self, ctxt):
try:
self.__class__._registered_instances.remove(self)
except:
log_error(traceback.format_exc())
def _read(self, ctxt, dest, offset, length):
try:
data = self.perform_read(offset, length)
if data is None:
return 0
if len(data) > length:
data = data[0:length]
ctypes.memmove(dest, data, len(data))
return len(data)
except:
log_error(traceback.format_exc())
return 0
def _write(self, ctxt, offset, src, length):
try:
data = ctypes.create_string_buffer(length)
ctypes.memmove(data, src, length)
return self.perform_write(offset, data.raw)
except:
log_error(traceback.format_exc())
return 0
def _insert(self, ctxt, offset, src, length):
try:
data = ctypes.create_string_buffer(length)
ctypes.memmove(data, src, length)
return self.perform_insert(offset, data.raw)
except:
log_error(traceback.format_exc())
return 0
def _remove(self, ctxt, offset, length):
try:
return self.perform_remove(offset, length)
except:
log_error(traceback.format_exc())
return 0
def _get_modification(self, ctxt, offset):
try:
return self.perform_get_modification(offset)
except:
log_error(traceback.format_exc())
return ModificationStatus.Original
def _is_valid_offset(self, ctxt, offset):
try:
return self.perform_is_valid_offset(offset)
except:
log_error(traceback.format_exc())
return False
def _is_offset_readable(self, ctxt, offset):
try:
return self.perform_is_offset_readable(offset)
except:
log_error(traceback.format_exc())
return False
def _is_offset_writable(self, ctxt, offset):
try:
return self.perform_is_offset_writable(offset)
except:
log_error(traceback.format_exc())
return False
def _is_offset_executable(self, ctxt, offset):
try:
return self.perform_is_offset_executable(offset)
except:
log_error(traceback.format_exc())
return False
def _get_next_valid_offset(self, ctxt, offset):
try:
return self.perform_get_next_valid_offset(offset)
except:
log_error(traceback.format_exc())
return offset
def _get_start(self, ctxt):
try:
return self.perform_get_start()
except:
log_error(traceback.format_exc())
return 0
def _get_length(self, ctxt):
try:
return self.perform_get_length()
except:
log_error(traceback.format_exc())
return 0
def _get_entry_point(self, ctxt):
try:
return self.perform_get_entry_point()
except:
log_error(traceback.format_exc())
return 0
def _is_executable(self, ctxt):
try:
return self.perform_is_executable()
except:
log_error(traceback.format_exc())
return False
def _get_default_endianness(self, ctxt):
try:
return self.perform_get_default_endianness()
except:
log_error(traceback.format_exc())
return Endianness.LittleEndian
def _is_relocatable(self, ctxt):
try:
return self.perform_is_relocatable()
except:
log_error(traceback.format_exc())
return False
def _get_address_size(self, ctxt):
try:
return self.perform_get_address_size()
except:
log_error(traceback.format_exc())
return 8
def _save(self, ctxt, file_accessor):
try:
return self.perform_save(fileaccessor.CoreFileAccessor(file_accessor))
except:
log_error(traceback.format_exc())
return False
[docs]
def init(self) -> bool:
return True
[docs]
def disassembly_tokens(
self, addr: int, arch: Optional['architecture.Architecture'] = None
) -> Generator[Tuple[List['_function.InstructionTextToken'], int], None, None]:
if arch is None:
if self.arch is None:
raise Exception("Can not call method disassembly with no Architecture specified")
arch = self.arch
size = 1
while size != 0:
tokens, size = arch.get_instruction_text(self.read(addr, arch.max_instr_length), addr)
addr += size
if size == 0 or tokens is None:
break
yield (tokens, size)
[docs]
def disassembly_text(self, addr: int,
arch: Optional['architecture.Architecture'] = None) -> Generator[Tuple[str, int], None, None]:
"""
``disassembly_text`` helper function for getting disassembly of a given address
:param int addr: virtual address of instruction
:param Architecture arch: optional Architecture, ``self.arch`` is used if this parameter is None
:return: a str representation of the instruction at virtual address ``addr`` or None
:rtype: str or None
:Example:
>>> next(bv.disassembly_text(bv.entry_point))
'push ebp', 1
>>>
"""
if arch is None:
if self.arch is None:
raise Exception("Can not call method disassembly with no Architecture specified")
arch = self.arch
size = 1
while size != 0:
tokens, size = arch.get_instruction_text(self.read(addr, arch.max_instr_length), addr)
addr += size
if size == 0 or tokens is None:
break
yield (''.join(str(a) for a in tokens).strip(), size)
[docs]
def get_disassembly(self, addr: int, arch: Optional['architecture.Architecture'] = None) -> Optional[str]:
"""
``get_disassembly`` simple helper function for printing disassembly of a given address
:param int addr: virtual address of instruction
:param Architecture arch: optional Architecture, ``self.arch`` is used if this parameter is None
:return: a str representation of the instruction at virtual address ``addr`` or None
:rtype: str or None
:Example:
>>> bv.get_disassembly(bv.entry_point)
'push ebp'
>>>
.. note:: This API is very simplistic and only returns text. See :py:func:`disassembly_text` and \
`instructions` for more capable APIs.
"""
if arch is None:
if self.arch is None:
raise Exception("Can not call method disassembly with no Architecture specified")
arch = self.arch
txt, _ = arch.get_instruction_text(self.read(addr, arch.max_instr_length), addr)
if txt is None:
return None
return ''.join(str(a) for a in txt).strip()
[docs]
def perform_get_entry_point(self) -> int:
"""
``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.
:return: the virtual address of the entry point
:rtype: int
"""
return 0
[docs]
def create_database(
self, filename: str, progress_func: Optional[ProgressFuncType] = None,
settings: Optional['filemetadata.SaveSettings'] = None
) -> bool:
"""
``create_database`` writes the current database (.bndb) out to the specified file.
:param str filename: path and filename to write the bndb to, this string `should` have ".bndb" appended to it.
:param callback progress_func: optional function to be called with the current progress and total count.
:param SaveSettings settings: optional argument for special save options.
:return: True on success, False on failure
:rtype: bool
.. warning:: The calling thread must not hold a lock on the BinaryView instance as this action is run on the main thread which requires the lock.
:Example:
>>> settings = SaveSettings()
>>> bv.create_database(f"{bv.file.filename}.bndb", None, settings)
True
"""
return self._file.create_database(filename, progress_func, settings)
[docs]
def save_auto_snapshot(
self, progress_func: Optional[ProgressFuncType] = None, settings: Optional['filemetadata.SaveSettings'] = None
) -> bool:
"""
``save_auto_snapshot`` saves the current database to the already created file.
.. note:: :py:func:`create_database` should have been called prior to executing this method
:param callback progress_func: optional function to be called with the current progress and total count.
:param SaveSettings settings: optional argument for special save options.
:return: True if it successfully saved the snapshot, False otherwise
:rtype: bool
"""
return self._file.save_auto_snapshot(progress_func, settings)
[docs]
def get_view_of_type(self, name: str) -> Optional['BinaryView']:
"""
``get_view_of_type`` returns the BinaryView associated with the provided name if it exists.
:param str name: Name of the view to be retrieved
:return: BinaryView object associated with the provided name or None on failure
:rtype: BinaryView or None
"""
return self._file.get_view_of_type(name)
[docs]
def undoable_transaction(self) -> Generator:
"""
``undoable_transaction`` gives you a context in which you can make changes to analysis,
and creates an Undo state containing those actions. If an exception is thrown, any
changes made to the analysis inside the transaction are reverted.
:return: Transaction context manager, which will commit/revert actions depending on if an exception
is thrown when it goes out of scope.
:rtype: Generator
:Example:
>>> bv.get_disassembly(0x100012f1)
'xor eax, eax'
>>> # Actions inside the transaction will be committed to the undo state upon exit
>>> with bv.undoable_transaction():
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'xor eax, eax'
>>> # A thrown exception inside the transaction will undo all changes made inside it
>>> with bv.undoable_transaction():
>>> bv.convert_to_nop(0x100012f1) # Reverted on thrown exception
>>> raise RuntimeError("oh no")
RuntimeError: oh no
>>> bv.get_disassembly(0x100012f1)
'xor eax, eax'
"""
return self._file.undoable_transaction()
[docs]
def begin_undo_actions(self, anonymous_allowed: bool = True) -> str:
"""
``begin_undo_actions`` starts recording actions taken so they can be undone at some point.
:param bool anonymous_allowed: Legacy interop: prevent empty calls to :py:func:`commit_undo_actions`` from
affecting this undo state. Specifically for :py:func:`undoable_transaction``
:return: Id of undo state, for passing to :py:func:`commit_undo_actions`` or :py:func:`revert_undo_actions`.
:rtype: str
:Example:
>>> bv.get_disassembly(0x100012f1)
'xor eax, eax'
>>> state = bv.begin_undo_actions()
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.commit_undo_actions(state)
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'xor eax, eax'
>>>
"""
return self._file.begin_undo_actions(anonymous_allowed)
[docs]
def commit_undo_actions(self, id: Optional[str] = None) -> None:
"""
``commit_undo_actions`` commits the actions taken since a call to :py:func:`begin_undo_actions`
Pass as `id` the value returned by :py:func:`begin_undo_actions`. Empty values of
`id` will commit all changes since the last call to :py:func:`begin_undo_actions`.
:param Optional[str] id: id of undo state, from :py:func:`begin_undo_actions`
:rtype: None
:Example:
>>> bv.get_disassembly(0x100012f1)
'xor eax, eax'
>>> state = bv.begin_undo_actions()
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.commit_undo_actions(state)
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'xor eax, eax'
>>>
"""
self._file.commit_undo_actions(id)
[docs]
def revert_undo_actions(self, id: Optional[str] = None) -> None:
"""
``revert_undo_actions`` reverts the actions taken since a call to :py:func:`begin_undo_actions`
Pass as `id` the value returned by :py:func:`begin_undo_actions`. Empty values of
`id` will revert all changes since the last call to :py:func:`begin_undo_actions`.
:param Optional[str] id: id of undo state, from :py:func:`begin_undo_actions`
:rtype: None
:Example:
>>> bv.get_disassembly(0x100012f1)
'xor eax, eax'
>>> state = bv.begin_undo_actions()
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.revert_undo_actions(state)
>>> bv.get_disassembly(0x100012f1)
'xor eax, eax'
>>>
"""
self._file.revert_undo_actions(id)
[docs]
def undo(self) -> None:
"""
``undo`` undo the last committed transaction in the undo database.
:rtype: None
:Example:
>>> bv.get_disassembly(0x100012f1)
'xor eax, eax'
>>> with bv.undoable_transaction():
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'xor eax, eax'
>>> bv.redo()
>>> bv.get_disassembly(0x100012f1)
'nop'
>>>
"""
self._file.undo()
[docs]
def redo(self) -> None:
"""
``redo`` redo the last committed transaction in the undo database.
:rtype: None
:Example:
>>> bv.get_disassembly(0x100012f1)
'xor eax, eax'
>>> with bv.undoable_transaction():
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'xor eax, eax'
>>> bv.redo()
>>> bv.get_disassembly(0x100012f1)
'nop'
>>>
"""
self._file.redo()
[docs]
def navigate(self, view_name: str, offset: int) -> bool:
"""
``navigate`` navigates the UI to the specified virtual address in the specified View
The View name is created by combining a View type (e.g. "Graph") with a BinaryView type (e.g. "Mach-O"),
separated by a colon, resulting in something like "Graph:Mach-O".
:param str view_name: view name
:param int offset: address to navigate to
:return: whether navigation succeeded
:rtype: bool
:Example:
>>> bv.navigate(bv.view, bv.start)
True
>>> bv.file.existing_views
['Mach-O', 'Raw']
>>> import binaryninjaui
>>> [i.getName() for i in binaryninjaui.ViewType.getTypes()]
['Graph', 'Hex', 'Linear', 'Strings', 'Types', 'Triage', 'Bytes']
>>> bv.navigate('Graph:Mach-O', bv.entry_point)
True
"""
return self._file.navigate(view_name, offset)
[docs]
def read(self, addr: int, length: int) -> bytes:
r"""
``read`` returns the data reads at most ``length`` bytes from virtual address ``addr``.
:param int addr: virtual address to read from.
:param int length: number of bytes to read.
:return: at most ``length`` bytes from the virtual address ``addr``, empty string on error or no data
:rtype: bytes
:Example:
>>> #Opening a x86_64 Mach-O binary
>>> bv = BinaryView.new("/bin/ls") # note that we are using `new` instead of `load` to get the raw view
>>> bv.read(0,4)
b'\xcf\xfa\xed\xfe'
"""
if (addr < 0) or (length < 0):
raise ValueError("length and address must both be positive")
buf = databuffer.DataBuffer(handle=core.BNReadViewBuffer(self.handle, addr, length))
return bytes(buf)
[docs]
def read_int(self, address: int, size: int, sign: bool = True, endian: Optional[Endianness] = None) -> int:
_endian = self.endianness
if endian is not None:
_endian = endian
data = self.read(address, size)
if len(data) != size:
raise ValueError(f"Couldn't read {size} bytes from address: {address:#x}")
return TypedDataAccessor.int_from_bytes(data, size, sign, _endian)
[docs]
def read_pointer(self, address: int, size: Optional[int] = None) -> int:
if size is None:
if self.arch is None:
raise ValueError("Can't read pointer for BinaryView without an architecture")
size = self.arch.address_size
return self.read_int(address, size, False, self.endianness)
[docs]
def read_uuid(self, address: int, ms_format: bool = True) -> uuid.UUID:
"""
Reads a UUID from the specified address in the binary view.
:param address: The address to read the UUID from.
:param ms_format: Whether to return the UUID in Microsoft format (True) or standard format (False).
:return: A UUID object
:raises ValueError: If 16 bytes couldn't be read from the specified address.
"""
data = self.read(address, 16)
if len(data) != 16:
raise ValueError(f"Couldn't read 16 bytes from address: {address:#x}")
if ms_format:
reordered = data[3::-1] + data[5:3:-1] + data[7:5:-1] + data[8:]
return uuid.UUID(bytes=reordered)
else:
return uuid.UUID(bytes=data)
[docs]
def write(self, addr: int, data: bytes, except_on_relocation: bool = True) -> int:
"""
``write`` writes the bytes in ``data`` to the virtual address ``addr``.
:param int addr: virtual address to write to.
:param bytes data: data to be written at addr.
:param bool except_on_relocation: (default True) raise exception when write overlaps a relocation
:return: number of bytes written to virtual address ``addr``
:rtype: int
:Example:
>>> bv.read(0,4)
b'BBBB'
>>> bv.write(0, b"AAAA")
4
>>> bv.read(0,4)
b'AAAA'
"""
if not (isinstance(data, bytes) or isinstance(data, bytearray) or isinstance(data, str)):
raise TypeError("Must be bytes, bytearray, or str")
buf = databuffer.DataBuffer(data)
if except_on_relocation and self.range_contains_relocation(addr, len(data)):
raise RelocationWriteException("Attempting to write to a location which has a relocation")
return core.BNWriteViewBuffer(self.handle, addr, buf.handle)
[docs]
def insert(self, addr: int, data: bytes) -> int:
"""
``insert`` inserts the bytes in ``data`` to the virtual address ``addr``.
:param int addr: virtual address to write to.
:param bytes data: data to be inserted at addr.
:return: number of bytes inserted to virtual address ``addr``
:rtype: int
:Example:
>>> bv.insert(0,"BBBB")
4
>>> bv.read(0,8)
'BBBBAAAA'
"""
if not (isinstance(data, bytes) or isinstance(data, bytearray) or isinstance(data, str)):
raise TypeError("Must be bytes, bytearray, or str")
else:
buf = databuffer.DataBuffer(data)
return core.BNInsertViewBuffer(self.handle, addr, buf.handle)
[docs]
def remove(self, addr: int, length: int) -> int:
"""
``remove`` removes at most ``length`` bytes from virtual address ``addr``.
:param int addr: virtual address to remove from.
:param int length: number of bytes to remove.
:return: number of bytes removed from virtual address ``addr``
:rtype: int
:Example:
>>> bv.read(0,8)
'BBBBAAAA'
>>> bv.remove(0,4)
4
>>> bv.read(0,4)
'AAAA'
"""
return core.BNRemoveViewData(self.handle, addr, length)
[docs]
def get_entropy(self, addr: int, length: int, block_size: int = 0) -> List[float]:
"""
``get_entropy`` returns the shannon entropy given the start ``addr``, ``length`` in bytes, and optionally in
``block_size`` chunks.
:param int addr: virtual address
:param int length: total length in bytes
:param int block_size: optional block size
:return: list of entropy values for each chunk
:rtype: list(float)
"""
result = []
if length == 0:
return result
if block_size == 0:
block_size = length
data = (ctypes.c_float * ((length//block_size) + 1))()
length = core.BNGetEntropy(self.handle, addr, length, block_size, data)
for i in range(0, length):
result.append(float(data[i]))
return result
[docs]
def get_modification(self, addr: int, length: Optional[int] = None) -> List[ModificationStatus]:
"""
``get_modification`` returns the modified bytes of up to ``length`` bytes from virtual address ``addr``, or if
``length`` is None returns the ModificationStatus.
:param int addr: virtual address to get modification from
:param int length: optional length of modification
:return: List of ModificationStatus values for each byte in range
:rtype: List[ModificationStatus]
"""
if length is None:
return [ModificationStatus(core.BNGetModification(self.handle, addr))]
data = (ctypes.c_int * length)()
length = core.BNGetModificationArray(self.handle, addr, data, length)
return [ModificationStatus(a) for a in data[:length]]
[docs]
def get_next_valid_offset(self, addr: int) -> int:
"""
``get_next_valid_offset`` returns the next valid offset in the BinaryView starting from the given virtual address ``addr``.
:param int addr: a virtual address to start checking from.
:return: The minimum of the next valid offset in the BinaryView and the end address of the BinaryView
:rtype: int
"""
return core.BNGetNextValidOffset(self.handle, addr)
[docs]
def is_valid_offset(self, addr: int) -> bool:
"""
``is_valid_offset`` checks if a virtual address ``addr`` is valid .
:param int addr: a virtual address to be checked
:return: True if the virtual address is valid, False if the virtual address is invalid or error
:rtype: bool
"""
return core.BNIsValidOffset(self.handle, addr)
[docs]
def is_offset_readable(self, addr: int) -> bool:
"""
``is_offset_readable`` checks if a virtual address ``addr`` is valid for reading.
:param int addr: a virtual address to be checked
:return: True if the virtual address is valid for reading, False if the virtual address is invalid or error
:rtype: bool
"""
return core.BNIsOffsetReadable(self.handle, addr)
[docs]
def is_offset_writable(self, addr: int) -> bool:
"""
``is_offset_writable`` checks if a virtual address ``addr`` is valid for writing.
:param int addr: a virtual address to be checked
:return: True if the virtual address is valid for writing, False if the virtual address is invalid or error
:rtype: bool
"""
return core.BNIsOffsetWritable(self.handle, addr)
[docs]
def is_offset_executable(self, addr: int) -> bool:
"""
``is_offset_executable`` checks if a virtual address ``addr`` is valid for executing.
:param int addr: a virtual address to be checked
:return: True if the virtual address is valid for executing, False if the virtual address is invalid or error
:rtype: bool
"""
return core.BNIsOffsetExecutable(self.handle, addr)
[docs]
def is_offset_code_semantics(self, addr: int) -> bool:
"""
``is_offset_code_semantics`` checks if a virtual address ``addr`` is semantically valid for code.
:param int addr: a virtual address to be checked
:return: True if the virtual address is valid for code semantics, False if the virtual address is invalid or error
:rtype: bool
"""
return core.BNIsOffsetCodeSemantics(self.handle, addr)
[docs]
def is_offset_extern_semantics(self, addr: int) -> bool:
"""
``is_offset_extern_semantics`` checks if a virtual address ``addr`` is semantically valid for external references.
:param int addr: a virtual address to be checked
:return: true if the virtual address is valid for external references, false if the virtual address is invalid or error
:rtype: bool
"""
return core.BNIsOffsetExternSemantics(self.handle, addr)
[docs]
def is_offset_writable_semantics(self, addr: int) -> bool:
"""
``is_offset_writable_semantics`` checks if a virtual address ``addr`` is semantically writable. Some sections
may have writable permissions for linking purposes but can be treated as read-only for the purposes of
analysis.
:param int addr: a virtual address to be checked
:return: True if the virtual address is valid for writing, False if the virtual address is invalid or error
:rtype: bool
"""
return core.BNIsOffsetWritableSemantics(self.handle, addr)
[docs]
def save(self, dest: Union['fileaccessor.FileAccessor', str]) -> bool:
"""
``save`` saves the original binary file to the provided destination ``dest`` along with any modifications.
:param str dest: destination path and filename of file to be written
:return: True on success, False on failure
:rtype: bool
"""
if isinstance(dest, fileaccessor.FileAccessor):
return core.BNSaveToFile(self.handle, dest._cb)
return core.BNSaveToFilename(self.handle, str(dest))
[docs]
def register_notification(self, notify: BinaryDataNotification) -> None:
"""
`register_notification` enables the receipt of callbacks for various analysis events. A full
list of callbacks is available in the :py:class:`BinaryDataNotification` class. If the
`notification_barrier` is enabled, then it is triggered upon the initial call to
`register_notification`. Subsequent calls for an already registered ``notify`` instance
also trigger a `notification_barrier` callback.
:param BinaryDataNotification notify: notify is a subclassed instance of :py:class:`BinaryDataNotification`.
:rtype: None
"""
if notify in self._notifications:
self._notifications[notify]._register()
return
cb = BinaryDataNotificationCallbacks(self, notify)
cb._register()
self._notifications[notify] = cb
[docs]
def unregister_notification(self, notify: BinaryDataNotification) -> None:
"""
`unregister_notification` unregisters the :py:class:`BinaryDataNotification` object passed to
`register_notification`
:param BinaryDataNotification notify: notify is a subclassed instance of :py:class:`BinaryDataNotification`.
:rtype: None
"""
if notify in self._notifications:
self._notifications[notify]._unregister()
del self._notifications[notify]
[docs]
def add_function(self, addr: int, plat: Optional['_platform.Platform'] = None, auto_discovered: bool = False, func_type: Optional['_function.Function'] = None) -> Optional['_function.Function']:
"""
``add_function`` add a new function of the given ``plat`` at the virtual address ``addr``
.. warning:: This function is used to create auto functions, often used when writing loaders, etc. Most users will want to use :py:func:`create_user_function` in their scripts.
:param int addr: virtual address of the function to be added
:param Platform plat: Platform for the function to be added
:param auto_discovered: True if function was automatically discovered, False if created by user
:param func_type: optional function type
:rtype: None
:Example:
>>> bv.add_function(1)
>>> bv.functions
[<func: x86_64@0x1>]
"""
if self.platform is None and plat is None:
raise Exception("Default platform not set in BinaryView")
if plat is None:
plat = self.platform
if not isinstance(plat, _platform.Platform):
raise ValueError("Provided platform is not of type `Platform`")
if isinstance(func_type, _types.Type):
func_type = func_type.handle
elif func_type is not None:
raise ValueError("Provided type is not of type `binaryninja.Type`")
result = core.BNAddFunctionForAnalysis(self.handle, plat.handle, addr, auto_discovered, func_type)
if result:
return _function.Function(self, result)
return None
[docs]
def add_entry_point(self, addr: int, plat: Optional['_platform.Platform'] = None) -> None:
"""
``add_entry_point`` adds a virtual address to start analysis from for a given plat.
:param int addr: virtual address to start analysis from
:param Platform plat: Platform for the entry point analysis
:rtype: None
:Example:
>>> bv.add_entry_point(0xdeadbeef)
>>>
"""
if self.platform is None and plat is None:
raise Exception("Default platform not set in BinaryView")
if plat is None:
plat = self.platform
if not isinstance(plat, _platform.Platform):
raise ValueError("Provided platform is not of type `Platform`")
core.BNAddEntryPointForAnalysis(self.handle, plat.handle, addr)
[docs]
def add_to_entry_functions(self, func: '_function.Function') -> None:
"""
``add_to_entry_functions`` adds a function to the `entry_functions` list.
:param Function func: a Function object
:rtype: None
:Example:
>>> bv.entry_functions
[<func: x86@0x4014c8>, <func: x86@0x401618>]
>>> bv.add_to_entry_functions(bv.get_function_at(0x4014da))
>>> bv.entry_functions
[<func: x86@0x4014c8>, <func: x86@0x401618>, <func: x86@0x4014da>]
"""
core.BNAddToEntryFunctions(self.handle, func.handle)
[docs]
def remove_function(self, func: '_function.Function', update_refs = False) -> None:
"""
``remove_function`` removes the function ``func`` from the list of functions
.. warning:: This method should only be used when the function that is removed is expected to re-appear after any other analysis executes that could re-add it. Most users will want to use :py:func:`remove_user_function` in their scripts.
:param Function func: a Function object.
:param bool update_refs: automatically update other functions that were referenced
:rtype: None
:Example:
>>> bv.functions
[<func: x86_64@0x1>]
>>> bv.remove_function(next(bv.functions))
>>> bv.functions
[]
"""
core.BNRemoveAnalysisFunction(self.handle, func.handle, update_refs)
[docs]
def create_user_function(self, addr: int, plat: Optional['_platform.Platform'] = None) \
-> Optional['_function.Function']:
"""
``create_user_function`` add a new *user* function of the given ``plat`` at the virtual address ``addr``
:param int addr: virtual address of the *user* function to be added
:param Platform plat: Platform for the function to be added
:rtype: None
:Example:
>>> bv.create_user_function(1)
>>> bv.functions
[<func: x86_64@0x1>]
"""
if plat is None:
if self.platform is None:
raise Exception("Attempting to call create_user_function with no specified platform")
plat = self.platform
func = core.BNCreateUserFunction(self.handle, plat.handle, addr)
if func is None:
return None
return _function.Function(self, func)
[docs]
def remove_user_function(self, func: '_function.Function') -> None:
"""
``remove_user_function`` removes the function ``func`` from the list of functions as a user action.
.. note:: This API will prevent the function from being re-created if any analysis later triggers that would re-add it, unlike :py:func:`remove_function`.
:param Function func: a Function object.
:rtype: None
:Example:
>>> bv.functions
[<func: x86_64@0x1>]
>>> bv.remove_user_function(next(bv.functions))
>>> bv.functions
[]
"""
core.BNRemoveUserFunction(self.handle, func.handle)
[docs]
def add_analysis_option(self, name: str) -> None:
"""
``add_analysis_option`` adds an analysis option. Analysis options elaborate the analysis phase. The user must
start analysis by calling either :py:func:`update_analysis` or :py:func:`update_analysis_and_wait`.
:param str name: name of the analysis option. Available options are: "linearsweep", and "signaturematcher".
:rtype: None
:Example:
>>> bv.add_analysis_option("linearsweep")
>>> bv.update_analysis_and_wait()
"""
core.BNAddAnalysisOption(self.handle, name)
[docs]
def has_initial_analysis(self) -> bool:
"""
``has_initial_analysis`` check for the presence of an initial analysis in this BinaryView.
:return: True if the BinaryView has a valid initial analysis, False otherwise
:rtype: bool
"""
return core.BNHasInitialAnalysis(self.handle)
[docs]
def set_analysis_hold(self, enable: bool) -> None:
"""
``set_analysis_hold`` control the analysis hold for this BinaryView. Enabling analysis hold defers all future
analysis updates, therefore causing :py:func:`update_analysis` or :py:func:`update_analysis_and_wait` to take no action.
:rtype: None
"""
core.BNSetAnalysisHold(self.handle, enable)
[docs]
def get_function_analysis_update_disabled(self) -> bool:
"""
Returns True when functions are prevented from being marked as updates required, False otherwise.
:return:
"""
return core.BNGetFunctionAnalysisUpdateDisabled(self.handle)
[docs]
def set_function_analysis_update_disabled(self, disabled: bool) -> None:
"""
``set_function_analysis_update_disabled`` prevents any function from being marked as updates required, so that
they would NOT be re-analyzed when the analysis is updated. The main difference between this API and
``set_analysis_hold`` is that ``set_analysis_hold`` only temporarily holds the analysis, and the functions
are still arranged to be updated when the hold is turned off. However, with
``set_function_analysis_update_disabled``, functions would not be put into the analysis queue at all.
Use with caution -- in most cases, this is NOT what you want, and you should use ``set_analysis_hold`` instead.
:param disabled:
:return:
"""
core.BNSetFunctionAnalysisUpdateDisabled(self.handle, disabled)
[docs]
def update_analysis(self) -> None:
"""
``update_analysis`` asynchronously starts the analysis process and returns immediately.
**Usage**:
Call ``update_analysis`` after making changes that could affect the analysis results, such as adding or modifying
functions. This ensures that the analysis is updated to reflect the latest changes. The analysis runs in the background,
allowing other operations to continue.
:rtype: None
"""
core.BNUpdateAnalysis(self.handle)
[docs]
def update_analysis_and_wait(self) -> None:
"""
``update_analysis_and_wait`` starts the analysis process and blocks until it is complete. This method should be
used when it is necessary to ensure that analysis results are fully updated before proceeding with further operations.
If an update is already in progress, this method chains a new update request to ensure that the update processes
all pending changes before the call was made.
**Usage**:
Call ``update_analysis_and_wait`` after making changes that could affect the analysis results, such as adding or modifying
functions, to ensure that the analysis reflects the latest changes. Unlike ``update_analysis``, this method waits for the
analysis to finish before returning.
**Thread Restrictions**:
- **Worker Threads**: This function cannot be called from a worker thread. If called from a worker thread, an error will be
logged, and the function will return immediately.
- **UI Threads**: This function cannot be called from a UI thread. If called from a UI thread, an error will be logged, and
the function will return immediately.
:rtype: None
"""
core.BNUpdateAnalysisAndWait(self.handle)
[docs]
def abort_analysis(self) -> None:
"""
``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.
:rtype: None
"""
core.BNAbortAnalysis(self.handle)
[docs]
def define_data_var(
self, addr: int, var_type: StringOrType, name: Optional[Union[str, '_types.CoreSymbol']] = None
) -> None:
"""
``define_data_var`` defines a non-user data variable ``var_type`` at the virtual address ``addr``.
:param int addr: virtual address to define the given data variable
:param StringOrType var_type: type to be defined at the given virtual address
:param Optional[Union[str, '_types.CoreSymbol']] name: Optionally additionally define a symbol at this location
:rtype: 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>
"""
if isinstance(var_type, str):
(var_type, _) = self.parse_type_string(var_type)
tc = var_type._to_core_struct()
core.BNDefineDataVariable(self.handle, addr, tc)
if name is not None:
if isinstance(name, str):
name = _types.Symbol(SymbolType.DataSymbol, addr, name)
self.define_auto_symbol(name)
[docs]
def define_user_data_var(
self, addr: int, var_type: StringOrType, name: Optional[Union[str, '_types.CoreSymbol']] = None
) -> Optional['DataVariable']:
"""
``define_user_data_var`` defines a user data variable ``var_type`` at the virtual address ``addr``.
:param int addr: virtual address to define the given data variable
:param binaryninja.Type var_type: type to be defined at the given virtual address
:param Optional[Union[str, _types.CoreSymbol]] name: Optionally, additionally define a symbol at this same address
:rtype: 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>
"""
if isinstance(var_type, str):
(var_type, _) = self.parse_type_string(var_type)
tc = var_type._to_core_struct()
core.BNDefineUserDataVariable(self.handle, addr, tc)
if name is not None:
if isinstance(name, str):
name = _types.Symbol(SymbolType.DataSymbol, addr, name)
self.define_user_symbol(name)
return self.get_data_var_at(addr)
[docs]
def undefine_data_var(self, addr: int, blacklist: bool = True) -> None:
"""
``undefine_data_var`` removes the non-user data variable at the virtual address ``addr``.
:param int addr: virtual address to define the data variable to be removed
:param bool blacklist: whether to add the address to the data variable black list so that the auto analysis
would not recreat the variable on re-analysis
:rtype: None
:Example:
>>> bv.undefine_data_var(bv.entry_point)
>>>
"""
core.BNUndefineDataVariable(self.handle, addr, blacklist)
[docs]
def undefine_user_data_var(self, addr: int) -> None:
"""
``undefine_user_data_var`` removes the user data variable at the virtual address ``addr``.
:param int addr: virtual address to define the data variable to be removed
:rtype: None
:Example:
>>> bv.undefine_user_data_var(bv.entry_point)
>>>
"""
core.BNUndefineUserDataVariable(self.handle, addr)
[docs]
def get_data_var_at(self, addr: int) -> Optional['DataVariable']:
"""
``get_data_var_at`` returns the data type at a given virtual address.
:param int addr: virtual address to get the data type from
:return: returns the DataVariable at the given virtual address, None on error
:rtype: DataVariable
:Example:
>>> t = bv.parse_type_string("int foo")
>>> bv.define_data_var(bv.entry_point, t[0])
>>> bv.get_data_var_at(bv.entry_point)
<var 0x100001174: int32_t>
"""
var = core.BNDataVariable()
if not core.BNGetDataVariableAtAddress(self.handle, addr, var):
return None
result = DataVariable.from_core_struct(var, self)
core.BNFreeDataVariable(var)
return result
[docs]
def get_functions_containing(self, addr: int,
plat: Optional['_platform.Platform'] = None) -> List['_function.Function']:
"""
``get_functions_containing`` returns a list of :py:class:`~binaryninja.function.Function` objects which contain the given address.
:param int addr: virtual address to query.
:rtype: list of :py:class:`~binaryninja.function.Function` objects
"""
count = ctypes.c_ulonglong(0)
funcs = core.BNGetAnalysisFunctionsContainingAddress(self.handle, addr, count)
assert funcs is not None, "core.BNGetAnalysisFunctionsContainingAddress returned None"
result = []
try:
for i in range(0, count.value):
result.append(_function.Function(self, core.BNNewFunctionReference(funcs[i])))
if plat is not None:
result = [func for func in result if func.platform == plat]
return result
finally:
core.BNFreeFunctionList(funcs, count.value)
[docs]
def get_functions_by_name(
self, name: str, plat: Optional['_platform.Platform'] = None, ordered_filter: Optional[List[SymbolType]] = None
) -> List['_function.Function']:
"""``get_functions_by_name`` returns a list of :py:class:`~binaryninja.function.Function` objects
function with a :py:class:`~binaryninja.types.Symbol` of ``name``.
:param str name: name of the functions
:param Platform plat: (optional) platform
:param list(SymbolType) ordered_filter: (optional) an ordered filter based on SymbolType
:return: returns a list of :py:class:`~binaryninja.function.Function` objects or an empty list
:rtype: list(Function)
:Example:
>>> bv.get_functions_by_name("main")
[<func: x86_64@0x1587>]
>>>
"""
if ordered_filter is None:
ordered_filter = [
SymbolType.FunctionSymbol, SymbolType.ImportedFunctionSymbol, SymbolType.LibraryFunctionSymbol
]
fns = []
addresses = [sym.address for sym in self.get_symbols_by_name(name, ordered_filter=ordered_filter)]
if len(addresses) == 0 and name.startswith("sub_"):
try:
addresses = [int(name[4:], 16)]
except:
addresses = []
for address in addresses:
for fn in self.get_functions_at(address):
if fn.start == address:
if plat is not None and fn.platform != plat:
continue
fns.append(fn)
return fns
[docs]
def get_function_at(self, addr: int, plat: Optional['_platform.Platform'] = None) -> Optional['_function.Function']:
"""
``get_function_at`` gets a Function object for the function that starts at virtual address ``addr``:
:param int addr: starting virtual address of the desired function
:param Platform plat: platform of the desired function
:return: returns a Function object or None for the function at the virtual address provided
:rtype: Function
:Example:
>>> bv.get_function_at(bv.entry_point)
<func: x86_64@0x100001174>
>>>
"""
if plat is None:
funcs = self.get_functions_at(addr)
if not funcs:
return None
result = [func for func in funcs if (func.platform == self.platform)]
if not result:
result = funcs
return result[0]
else:
func = core.BNGetAnalysisFunction(self.handle, plat.handle, addr)
if func is None:
return None
return _function.Function(self, func)
[docs]
def get_functions_at(self, addr: int) -> List['_function.Function']:
"""
``get_functions_at`` get a list of :py:class:`~binaryninja.function.Function` objects (one for each valid platform) that start at the
given virtual address. Binary Ninja does not limit the number of platforms in a given file thus there may be
multiple functions defined from different architectures at the same location. This API allows you to query all
of valid platforms.
You may also be interested in :py:func:`get_functions_containing` which is useful for requesting all function
that contain a given address
:param int addr: virtual address of the desired Function object list.
:return: a list of :py:class:`~binaryninja.function.Function` objects defined at the provided virtual address
:rtype: list(Function)
"""
count = ctypes.c_ulonglong(0)
funcs = core.BNGetAnalysisFunctionsForAddress(self.handle, addr, count)
assert funcs is not None, "core.BNGetAnalysisFunctionsForAddress returned None"
result = []
try:
for i in range(0, count.value):
result.append(_function.Function(self, core.BNNewFunctionReference(funcs[i])))
return result
finally:
core.BNFreeFunctionList(funcs, count.value)
[docs]
def get_recent_function_at(self, addr: int) -> Optional['_function.Function']:
func = core.BNGetRecentAnalysisFunctionForAddress(self.handle, addr)
if func is None:
return None
return _function.Function(self, func)
[docs]
def get_basic_blocks_at(self, addr: int) -> List['basicblock.BasicBlock']:
"""
``get_basic_blocks_at`` get a list of :py:class:`~binaryninja.basicblock.BasicBlock` objects which exist at the provided virtual address.
:param int addr: virtual address of BasicBlock desired
:return: a list of :py:class:`~binaryninja.basicblock.BasicBlock` objects
:rtype: list(BasicBlock)
"""
count = ctypes.c_ulonglong(0)
blocks = core.BNGetBasicBlocksForAddress(self.handle, addr, count)
assert blocks is not None, "core.BNGetBasicBlocksForAddress returned None"
result = []
try:
for i in range(0, count.value):
block_handle = core.BNNewBasicBlockReference(blocks[i])
assert block_handle is not None, "core.BNNewBasicBlockReference is None"
result.append(basicblock.BasicBlock(block_handle, self))
return result
finally:
core.BNFreeBasicBlockList(blocks, count.value)
[docs]
def get_basic_blocks_starting_at(self, addr: int) -> List['basicblock.BasicBlock']:
"""
``get_basic_blocks_starting_at`` get a list of :py:class:`~binaryninja.basicblock.BasicBlock` objects which start at the provided virtual address.
:param int addr: virtual address of BasicBlock desired
:return: a list of :py:class:`~binaryninja.basicblock.BasicBlock` objects
:rtype: list(BasicBlock)
"""
count = ctypes.c_ulonglong(0)
blocks = core.BNGetBasicBlocksStartingAtAddress(self.handle, addr, count)
assert blocks is not None, "core.BNGetBasicBlocksStartingAtAddress returned None"
result = []
try:
for i in range(0, count.value):
block_handle = core.BNNewBasicBlockReference(blocks[i])
assert block_handle is not None, "core.BNNewBasicBlockReference returned None"
result.append(basicblock.BasicBlock(block_handle, self))
return result
finally:
core.BNFreeBasicBlockList(blocks, count.value)
[docs]
def get_recent_basic_block_at(self, addr: int) -> Optional['basicblock.BasicBlock']:
block = core.BNGetRecentBasicBlockForAddress(self.handle, addr)
if block is None:
return None
return basicblock.BasicBlock(block, self)
[docs]
def get_code_refs(self, addr: int, length: Optional[int] = None) -> Generator['ReferenceSource', None, None]:
"""
``get_code_refs`` returns a generator of :py:class:`~binaryninja.binaryview.ReferenceSource` objects (xrefs or cross-references) that point to the provided virtual address.
This function returns both autoanalysis ("auto") and user-specified ("user") xrefs.
To add a user-specified reference, see :py:func:`~binaryninja.function.Function.add_user_code_ref`.
The related :py:func:`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 :py:func:`get_code_refs_from` looks for references that are outgoing from the queried address to other locations.
:param int addr: virtual address to query for references
:param int length: optional length of query
:return: A generator of References for the given virtual address
:rtype: Generator[ReferenceSource, None, None]
:Example:
>>> bv.get_code_refs(here)
[<ref: x86@0x4165ff>]
>>>
"""
count = ctypes.c_ulonglong(0)
if length is None:
refs = core.BNGetCodeReferences(self.handle, addr, count)
assert refs is not None, "core.BNGetCodeReferences returned None"
else:
refs = core.BNGetCodeReferencesInRange(self.handle, addr, length, count)
assert refs is not None, "core.BNGetCodeReferencesInRange returned None"
try:
for i in range(0, count.value):
yield ReferenceSource._from_core_struct(self, refs[i])
finally:
core.BNFreeCodeReferences(refs, count.value)
[docs]
def get_code_refs_from(
self, addr: int, func: Optional['_function.Function'] = None,
arch: Optional['architecture.Architecture'] = None, length: Optional[int] = None
) -> List[int]:
"""
``get_code_refs_from`` returns a list of virtual addresses referenced by code in the function ``func``,
of the architecture ``arch``, and at the address ``addr``. If no function is specified, references from
all functions and containing the address will be returned. If no architecture is specified, the
architecture of the function will be used.
This function returns both autoanalysis ("auto") and user-specified ("user") xrefs.
To add a user-specified reference, see :py:func:`~binaryninja.function.Function.add_user_code_ref`.
:param int addr: virtual address to query for references
:param int length: optional length of query
:param Architecture arch: optional architecture of query
:return: list of integers
:rtype: list(integer)
"""
result = []
funcs = self.get_functions_containing(addr) if func is None else [func]
if not funcs:
return []
for src_func in funcs:
src_arch = src_func.arch if arch is None else arch
assert src_arch is not None
ref_src = core.BNReferenceSource(src_func.handle, src_arch.handle, addr)
count = ctypes.c_ulonglong(0)
if length is None:
refs = core.BNGetCodeReferencesFrom(self.handle, ref_src, count)
assert refs is not None, "core.BNGetCodeReferencesFrom returned None"
else:
refs = core.BNGetCodeReferencesFromInRange(self.handle, ref_src, length, count)
assert refs is not None, "core.BNGetCodeReferencesFromInRange returned None"
for i in range(0, count.value):
result.append(refs[i])
core.BNFreeAddressList(refs)
return result
[docs]
def get_data_refs(self, addr: int, length: Optional[int] = None) -> Generator[int, None, None]:
"""
``get_data_refs`` returns a list of virtual addresses of _data_ (not code) which references ``addr``, optionally specifying
a length. When ``length`` is set ``get_data_refs`` returns the data which references in the range ``addr``-``addr``+``length``.
This function returns both autoanalysis ("auto") and user-specified ("user") xrefs. To add a user-specified
reference, see :py:func:`add_user_data_ref`.
.. warning:: If you're looking at this API, please double check that you don't mean to use :py:func:`get_code_refs` instead. \
`get_code_refs` returns references from code to the specified address while this API returns references from data \
(pointers in global variables for example). Also, note there exists :py:func:`get_data_refs_from`.
:param int addr: virtual address to query for references
:param int length: optional length of query
:return: list of integers
:rtype: list(integer)
:Example:
>>> bv.get_data_refs(here)
[4203812]
>>>
"""
count = ctypes.c_ulonglong(0)
if length is None:
refs = core.BNGetDataReferences(self.handle, addr, count)
assert refs is not None, "core.BNGetDataReferences returned None"
else:
refs = core.BNGetDataReferencesInRange(self.handle, addr, length, count)
assert refs is not None, "core.BNGetDataReferencesInRange returned None"
try:
for i in range(0, count.value):
yield refs[i]
finally:
core.BNFreeDataReferences(refs)
[docs]
def get_data_refs_from(self, addr: int, length: Optional[int] = None) -> Generator[int, None, None]:
"""
``get_data_refs_from`` returns a list of virtual addresses referenced by the address ``addr``. Optionally specifying
a length. When ``length`` is set ``get_data_refs_from`` returns the data referenced in the range ``addr``-``addr``+``length``.
This function returns both autoanalysis ("auto") and user-specified ("user") xrefs. To add a user-specified
reference, see :py:func:`add_user_data_ref`. Also, note there exists :py:func:`get_data_refs`.
:param int addr: virtual address to query for references
:param int length: optional length of query
:return: list of integers
:rtype: list(integer)
:Example:
>>> bv.get_data_refs_from(here)
[4200327]
>>>
"""
count = ctypes.c_ulonglong(0)
if length is None:
refs = core.BNGetDataReferencesFrom(self.handle, addr, count)
assert refs is not None, "core.BNGetDataReferencesFrom returned None"
else:
refs = core.BNGetDataReferencesFromInRange(self.handle, addr, length, count)
assert refs is not None, "core.BNGetDataReferencesFromInRange returned None"
try:
for i in range(0, count.value):
yield refs[i]
finally:
core.BNFreeDataReferences(refs)
[docs]
def get_code_refs_for_type(self, name: str) -> Generator[ReferenceSource, None, None]:
"""
``get_code_refs_for_type`` returns a Generator[ReferenceSource] objects (xrefs or cross-references) that reference the provided QualifiedName.
:param QualifiedName name: name of type to query for references
:return: List of References for the given type
:rtype: list(ReferenceSource)
:Example:
>>> bv.get_code_refs_for_type('A')
[<ref: x86@0x4165ff>]
>>>
"""
count = ctypes.c_ulonglong(0)
_name = _types.QualifiedName(name)._to_core_struct()
refs = core.BNGetCodeReferencesForType(self.handle, _name, count)
assert refs is not None, "core.BNGetCodeReferencesForType returned None"
try:
for i in range(0, count.value):
yield ReferenceSource._from_core_struct(self, refs[i])
finally:
core.BNFreeCodeReferences(refs, count.value)
[docs]
def get_code_refs_for_type_field(self, name: str,
offset: int) -> Generator['_types.TypeFieldReference', None, None]:
"""
``get_code_refs_for_type`` returns a Generator[TypeFieldReference] objects (xrefs or cross-references) that reference the provided type field.
:param QualifiedName name: name of type to query for references
:param int offset: offset of the field, relative to the type
:return: Generator of References for the given type
:rtype: Generator[TypeFieldReference]
:Example:
>>> bv.get_code_refs_for_type_field('A', 0x8)
[<ref: x86@0x4165ff>]
>>>
"""
count = ctypes.c_ulonglong(0)
_name = _types.QualifiedName(name)._to_core_struct()
refs = core.BNGetCodeReferencesForTypeField(self.handle, _name, offset, count)
assert refs is not None, "core.BNGetCodeReferencesForTypeField returned None"
try:
for i in range(0, count.value):
if refs[i].func:
func = _function.Function(self, core.BNNewFunctionReference(refs[i].func))
else:
func = None
if refs[i].arch:
arch = architecture.CoreArchitecture._from_cache(refs[i].arch)
else:
arch = None
addr = refs[i].addr
size = refs[i].size
typeObj = None
if refs[i].incomingType.type:
typeObj = _types.Type.create(
core.BNNewTypeReference(refs[i].incomingType.type), confidence=refs[i].incomingType.confidence
)
yield _types.TypeFieldReference(func, arch, addr, size, typeObj)
finally:
core.BNFreeTypeFieldReferences(refs, count.value)
[docs]
def get_data_refs_for_type(self, name: str) -> Generator[int, None, None]:
"""
``get_data_refs_for_type`` returns a list of virtual addresses of data which references the type ``name``.
Note, the returned addresses are the actual start of the queried type. For example, suppose there is a DataVariable
at 0x1000 that has type A, and type A contains type B at offset 0x10. Then `get_data_refs_for_type('B')` will
return 0x1010 for it.
:param QualifiedName name: name of type to query for references
:return: list of integers
:rtype: list(integer)
:Example:
>>> bv.get_data_refs_for_type('A')
[4203812]
>>>
"""
count = ctypes.c_ulonglong(0)
_name = _types.QualifiedName(name)._to_core_struct()
refs = core.BNGetDataReferencesForType(self.handle, _name, count)
assert refs is not None, "core.BNGetDataReferencesForType returned None"
try:
for i in range(0, count.value):
yield refs[i]
finally:
core.BNFreeDataReferences(refs)
[docs]
def get_data_refs_for_type_field(self, name: '_types.QualifiedNameType', offset: int) -> List[int]:
"""
``get_data_refs_for_type_field`` returns a list of virtual addresses of data which references the type ``name``.
Note, the returned addresses are the actual start of the queried type field. For example, suppose there is a
DataVariable at 0x1000 that has type A, and type A contains type B at offset 0x10.
Then `get_data_refs_for_type_field('B', 0x8)` will return 0x1018 for it.
:param QualifiedName name: name of type to query for references
:param int offset: offset of the field, relative to the type
:return: list of integers
:rtype: list(integer)
:Example:
>>> bv.get_data_refs_for_type_field('A', 0x8)
[4203812]
>>>
"""
count = ctypes.c_ulonglong(0)
_name = _types.QualifiedName(name)._to_core_struct()
refs = core.BNGetDataReferencesForTypeField(self.handle, _name, offset, count)
assert refs is not None, "core.BNGetDataReferencesForTypeField returned None"
result = []
try:
for i in range(0, count.value):
result.append(refs[i])
return result
finally:
core.BNFreeDataReferences(refs)
[docs]
def get_data_refs_from_for_type_field(self, name: '_types.QualifiedNameType', offset: int) -> List[int]:
"""
``get_data_refs_from_for_type_field`` returns a list of virtual addresses of data which are referenced by the type ``name``.
Only data referenced by structures with the ``__data_var_refs`` attribute are included.
:param QualifiedName name: name of type to query for references
:param int offset: offset of the field, relative to the type
:return: list of integers
:rtype: list(integer)
:Example:
>>> bv.get_data_refs_from_for_type_field('A', 0x8)
[4203812]
>>>
"""
count = ctypes.c_ulonglong(0)
_name = _types.QualifiedName(name)._to_core_struct()
refs = core.BNGetDataReferencesFromForTypeField(self.handle, _name, offset, count)
assert refs is not None, "core.BNGetDataReferencesFromForTypeField returned None"
result = []
try:
for i in range(0, count.value):
result.append(refs[i])
return result
finally:
core.BNFreeDataReferences(refs)
[docs]
def get_type_refs_for_type(self, name: '_types.QualifiedNameType') -> List['_types.TypeReferenceSource']:
"""
``get_type_refs_for_type`` returns a list of TypeReferenceSource objects (xrefs or cross-references) that reference the provided QualifiedName.
:param QualifiedName name: name of type to query for references
:return: List of references for the given type
:rtype: list(TypeReferenceSource)
:Example:
>>> bv.get_type_refs_for_type('A')
['<type D, offset 0x8, direct>', '<type C, offset 0x10, indirect>']
>>>
"""
count = ctypes.c_ulonglong(0)
_name = _types.QualifiedName(name)._to_core_struct()
refs = core.BNGetTypeReferencesForType(self.handle, _name, count)
assert refs is not None, "core.BNGetTypeReferencesForType returned None"
result = []
try:
for i in range(0, count.value):
type_field = _types.TypeReferenceSource(
_types.QualifiedName._from_core_struct(refs[i].name), refs[i].offset, refs[i].type
)
result.append(type_field)
return result
finally:
core.BNFreeTypeReferences(refs, count.value)
[docs]
def get_type_refs_for_type_field(self, name: '_types.QualifiedNameType',
offset: int) -> List['_types.TypeReferenceSource']:
"""
``get_type_refs_for_type`` returns a list of TypeReferenceSource objects (xrefs or cross-references) that reference the provided type field.
:param QualifiedName name: name of type to query for references
:param int offset: offset of the field, relative to the type
:return: List of references for the given type
:rtype: list(TypeReferenceSource)
:Example:
>>> bv.get_type_refs_for_type_field('A', 0x8)
['<type D, offset 0x8, direct>', '<type C, offset 0x10, indirect>']
>>>
"""
count = ctypes.c_ulonglong(0)
_name = _types.QualifiedName(name)._to_core_struct()
refs = core.BNGetTypeReferencesForTypeField(self.handle, _name, offset, count)
assert refs is not None, "core.BNGetTypeReferencesForTypeField returned None"
result = []
try:
for i in range(0, count.value):
type_field = _types.TypeReferenceSource(
_types.QualifiedName._from_core_struct(refs[i].name), refs[i].offset, refs[i].type
)
result.append(type_field)
return result
finally:
core.BNFreeTypeReferences(refs, count.value)
[docs]
def get_code_refs_for_type_from(
self, addr: int, func: Optional['_function.Function'] = None,
arch: Optional['architecture.Architecture'] = None, length: Optional[int] = None
) -> List['_types.TypeReferenceSource']:
"""
``get_code_refs_for_type_from`` returns a list of types referenced by code in the function ``func``,
of the architecture ``arch``, and at the address ``addr``. If no function is specified, references from
all functions and containing the address will be returned. If no architecture is specified, the
architecture of the function will be used.
:param int addr: virtual address to query for references
:param int length: optional length of query
:return: list of references
:rtype: list(TypeReferenceSource)
"""
result = []
funcs = self.get_functions_containing(addr) if func is None else [func]
if not funcs:
return []
for src_func in funcs:
src_arch = src_func.arch if arch is None else arch
assert src_arch is not None
ref_src = core.BNReferenceSource(src_func.handle, src_arch.handle, addr)
count = ctypes.c_ulonglong(0)
if length is None:
refs = core.BNGetCodeReferencesForTypeFrom(self.handle, ref_src, count)
assert refs is not None, "core.BNGetCodeReferencesForTypeFrom returned None"
else:
refs = core.BNGetCodeReferencesForTypeFromInRange(self.handle, ref_src, length, count)
assert refs is not None, "core.BNGetCodeReferencesForTypeFromInRange returned None"
try:
for i in range(0, count.value):
type_field = _types.TypeReferenceSource(
_types.QualifiedName._from_core_struct(refs[i].name), refs[i].offset, refs[i].type
)
result.append(type_field)
finally:
core.BNFreeTypeReferences(refs, count.value)
return result
[docs]
def get_code_refs_for_type_fields_from(
self, addr: int, func: Optional['_function.Function'] = None,
arch: Optional['architecture.Architecture'] = None, length: Optional[int] = None
) -> List['_types.TypeReferenceSource']:
"""
``get_code_refs_for_type_fields_from`` returns a list of type fields referenced by code in the function ``func``,
of the architecture ``arch``, and at the address ``addr``. If no function is specified, references from
all functions and containing the address will be returned. If no architecture is specified, the
architecture of the function will be used.
:param int addr: virtual address to query for references
:param int length: optional length of query
:return: list of references
:rtype: list(TypeReferenceSource)
"""
result = []
funcs = self.get_functions_containing(addr) if func is None else [func]
if not funcs:
return []
for src_func in funcs:
src_arch = src_func.arch if arch is None else arch
assert src_arch is not None
ref_src = core.BNReferenceSource(src_func.handle, src_arch.handle, addr)
count = ctypes.c_ulonglong(0)
if length is None:
refs = core.BNGetCodeReferencesForTypeFieldsFrom(self.handle, ref_src, count)
assert refs is not None, "core.BNGetCodeReferencesForTypeFieldsFrom returned None"
else:
refs = core.BNGetCodeReferencesForTypeFieldsFromInRange(self.handle, ref_src, length, count)
assert refs is not None, "core.BNGetCodeReferencesForTypeFieldsFromInRange returned None"
try:
for i in range(0, count.value):
type_field = _types.TypeReferenceSource(
_types.QualifiedName._from_core_struct(refs[i].name), refs[i].offset, refs[i].type
)
result.append(type_field)
finally:
core.BNFreeTypeReferences(refs, count.value)
return result
[docs]
def add_user_data_ref(self, from_addr: int, to_addr: int) -> None:
"""
``add_user_data_ref`` adds a user-specified data cross-reference (xref) from the address ``from_addr`` to the address ``to_addr``.
If the reference already exists, no action is performed. To remove the reference, use :py:func:`remove_user_data_ref`.
:param int from_addr: the reference's source virtual address.
:param int to_addr: the reference's destination virtual address.
:rtype: None
"""
core.BNAddUserDataReference(self.handle, from_addr, to_addr)
[docs]
def remove_user_data_ref(self, from_addr: int, to_addr: int) -> None:
"""
``remove_user_data_ref`` removes a user-specified data cross-reference (xref) from the address ``from_addr`` to the address ``to_addr``.
This function will only remove user-specified references, not ones generated during autoanalysis.
If the reference does not exist, no action is performed.
:param int from_addr: the reference's source virtual address.
:param int to_addr: the reference's destination virtual address.
:rtype: None
"""
core.BNRemoveUserDataReference(self.handle, from_addr, to_addr)
[docs]
def get_all_fields_referenced(self, name: '_types.QualifiedNameType') -> List[int]:
"""
``get_all_fields_referenced`` returns a list of offsets in the QualifiedName
specified by name, which are referenced by code.
:param QualifiedName name: name of type to query for references
:return: List of offsets
:rtype: list(integer)
:Example:
>>> bv.get_all_fields_referenced('A')
[0, 8, 16, 24, 32, 40]
>>>
"""
count = ctypes.c_ulonglong(0)
_name = _types.QualifiedName(name)._to_core_struct()
refs = core.BNGetAllFieldsReferenced(self.handle, _name, count)
assert refs is not None, "core.BNGetAllFieldsReferenced returned None"
result = []
try:
for i in range(0, count.value):
result.append(refs[i])
return result
finally:
core.BNFreeDataReferences(refs)
[docs]
def get_all_sizes_referenced(self, name: '_types.QualifiedNameType') -> Mapping[int, List[int]]:
"""
``get_all_sizes_referenced`` returns a map from field offset to a list of sizes of
the accesses to it.
:param QualifiedName name: name of type to query for references
:return: A map from field offset to the size of the code accesses to it
:rtype: map
:Example:
>>> bv.get_all_sizes_referenced('B')
{0: [1, 8], 8: [8], 16: [1, 8]}
>>>
"""
count = ctypes.c_ulonglong(0)
_name = _types.QualifiedName(name)._to_core_struct()
refs = core.BNGetAllSizesReferenced(self.handle, _name, count)
assert refs is not None, "core.BNGetAllSizesReferenced returned None"
result: Mapping[int, List[int]] = {}
try:
for i in range(0, count.value):
result[refs[i].offset] = []
for j in range(0, refs[i].count):
result[refs[i].offset].append(refs[i].sizes[j])
return result
finally:
core.BNFreeTypeFieldReferenceSizeInfo(refs, count.value)
[docs]
def get_all_types_referenced(self, name: '_types.QualifiedNameType') -> Mapping[int, List['_types.Type']]:
"""
``get_all_types_referenced`` returns a map from field offset to a list of incoming types written to the specified type.
:param QualifiedName name: name of type to query for references
:return: A map from field offset to a list of incoming types written to it
:rtype: 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>]}
>>>
"""
count = ctypes.c_ulonglong(0)
_name = _types.QualifiedName(name)._to_core_struct()
refs = core.BNGetAllTypesReferenced(self.handle, _name, count)
assert refs is not None, "core.BNGetAllTypesReferenced returned None"
result: Mapping[int, List['_types.Type']] = {}
try:
for i in range(0, count.value):
result[refs[i].offset] = []
for j in range(0, refs[i].count):
typeObj = _types.Type.create(
core.BNNewTypeReference(refs[i].types[j].type), self.platform, refs[i].types[j].confidence
)
result[refs[i].offset].append(typeObj)
return result
finally:
core.BNFreeTypeFieldReferenceTypeInfo(refs, count.value)
[docs]
def get_sizes_referenced(self, name: '_types.QualifiedNameType', offset: int) -> List[int]:
"""
``get_sizes_referenced`` returns a list of access sizes to the specified type.
:param QualifiedName name: name of type to query for references
:param int offset: offset of the field
:return: a list of sizes of the accesses to it.
:rtype: list
:Example:
>>> bv.get_sizes_referenced('B', 16)
[1, 8]
>>>
"""
count = ctypes.c_ulonglong(0)
_name = _types.QualifiedName(name)._to_core_struct()
refs = core.BNGetSizesReferenced(self.handle, _name, offset, count)
assert refs is not None, "core.BNGetSizesReferenced returned None"
result = []
try:
for i in range(0, count.value):
result.append(refs[i])
return result
finally:
core.BNFreeTypeFieldReferenceSizes(refs, count.value)
[docs]
def get_types_referenced(self, name: '_types.QualifiedName', offset: int) -> List['_types.Type']:
"""
``get_types_referenced`` returns a list of types related to the type field access.
:param QualifiedName name: name of type to query for references
:param int offset: offset of the field
:return: a list of types related to the type field access.
:rtype: list
:Example:
>>> bv.get_types_referenced('B', 0x10)
[<type: bool>, <type: char, 0% confidence>]
>>>
"""
count = ctypes.c_ulonglong(0)
_name = _types.QualifiedName(name)._to_core_struct()
refs = core.BNGetTypesReferenced(self.handle, _name, offset, count)
assert refs is not None, "core.BNGetTypesReferenced returned None"
try:
result = []
for i in range(0, count.value):
typeObj = _types.Type.create(core.BNNewTypeReference(refs[i].type), confidence=refs[i].confidence)
result.append(typeObj)
return result
finally:
core.BNFreeTypeFieldReferenceTypes(refs, count.value)
[docs]
def get_outgoing_direct_type_references(self, name: '_types.QualifiedNameType') -> List['_types.QualifiedName']:
qname = _types.QualifiedName(name)
_qname = qname._to_core_struct()
count = ctypes.c_ulonglong(0)
_result = core.BNGetOutgoingDirectTypeReferences(self.handle, _qname, count)
assert _result is not None, "core.BNGetOutgoingDirectTypeReferences returned None"
try:
result = []
for i in range(0, count.value):
result_name = _types.QualifiedName._from_core_struct(_result[i])
result.append(result_name)
return result
finally:
core.BNFreeTypeNameList(_result, count.value)
[docs]
def get_outgoing_recursive_type_references(self, names: Union['_types.QualifiedNameType', List['_types.QualifiedNameType']]) -> List['_types.QualifiedName']:
qnames = []
if isinstance(names, list):
for name in names:
qnames.append(_types.QualifiedName(name))
else:
qnames.append(_types.QualifiedName(names))
_qnames = (core.BNQualifiedName * len(qnames))()
for i, qname in enumerate(qnames):
_qnames[i] = qname._to_core_struct()
count = ctypes.c_ulonglong(0)
_result = core.BNGetOutgoingRecursiveTypeReferences(self.handle, _qnames, len(qnames), count)
assert _result is not None, "core.BNGetOutgoingRecursiveTypeReferences returned None"
try:
result = []
for i in range(0, count.value):
result_name = _types.QualifiedName._from_core_struct(_result[i])
result.append(result_name)
return result
finally:
core.BNFreeTypeNameList(_result, count.value)
[docs]
def get_incoming_direct_type_references(self, name: '_types.QualifiedNameType') -> List['_types.QualifiedName']:
qname = _types.QualifiedName(name)
_qname = qname._to_core_struct()
count = ctypes.c_ulonglong(0)
_result = core.BNGetIncomingDirectTypeReferences(self.handle, _qname, count)
assert _result is not None, "core.BNGetIncomingDirectTypeReferences returned None"
try:
result = []
for i in range(0, count.value):
result_name = _types.QualifiedName._from_core_struct(_result[i])
result.append(result_name)
return result
finally:
core.BNFreeTypeNameList(_result, count.value)
[docs]
def get_incoming_recursive_type_references(self, names: Union['_types.QualifiedNameType', List['_types.QualifiedNameType']]) -> List['_types.QualifiedName']:
qnames = []
if isinstance(names, list):
for name in names:
qnames.append(_types.QualifiedName(name))
else:
qnames.append(_types.QualifiedName(names))
_qnames = (core.BNQualifiedName * len(qnames))()
for i, qname in enumerate(qnames):
_qnames[i] = qname._to_core_struct()
count = ctypes.c_ulonglong(0)
_result = core.BNGetIncomingRecursiveTypeReferences(self.handle, _qnames, len(qnames), count)
assert _result is not None, "core.BNGetIncomingRecursiveTypeReferences returned None"
try:
result = []
for i in range(0, count.value):
result_name = _types.QualifiedName._from_core_struct(_result[i])
result.append(result_name)
return result
finally:
core.BNFreeTypeNameList(_result, count.value)
[docs]
def create_structure_from_offset_access(self, name: '_types.QualifiedName') -> '_types.StructureType':
newMemberAdded = ctypes.c_bool(False)
_name = _types.QualifiedName(name)._to_core_struct()
struct = core.BNCreateStructureFromOffsetAccess(self.handle, _name, newMemberAdded)
if struct is None:
raise Exception("BNCreateStructureFromOffsetAccess failed to create struct from offsets")
return _types.StructureType.from_core_struct(struct)
[docs]
def create_structure_member_from_access(self, name: '_types.QualifiedName', offset: int) -> '_types.Type':
_name = _types.QualifiedName(name)._to_core_struct()
result = core.BNCreateStructureMemberFromAccess(self.handle, _name, offset)
if not result.type:
raise Exception("BNCreateStructureMemberFromAccess failed to create struct member offsets")
return _types.Type.create(result.type, confidence=result.confidence)
[docs]
def add_expression_parser_magic_value(self, name: str, value: int) -> None:
"""
Add a magic value to the expression parser.
If the magic value already exists, its value gets updated.
The magic value can be used in the expression by a `$` followed by its name, e.g., `$foobar`.
It is optional to include the `$` when calling this function, i.e., calling with `foobar` and `$foobar`
has the same effect.
:param str name: name for the magic value to add or update
:param int value: value for the magic value
:return:
"""
core.BNAddExpressionParserMagicValue(self.handle, name, value)
[docs]
def remove_expression_parser_magic_value(self, name: str) -> None:
"""
Remove a magic value from the expression parser.
If the magic value gets referenced after removal, an error will occur during the parsing.
:param str name: name for the magic value to remove
:return:
"""
core.BNRemoveExpressionParserMagicValue(self.handle, name)
[docs]
def add_expression_parser_magic_values(self, names: List[str], values: List[int]) -> None:
"""
Add a list of magic value to the expression parser.
The list `names` and `values` must have the same size. The ith name in the `names` will correspond to
the ith value in the `values`.
If a magic value already exists, its value gets updated.
The magic value can be used in the expression by a `$` followed by its name, e.g., `$foobar`.
It is optional to include the `$` when calling this function, i.e., calling with `foobar` and `$foobar`
has the same effect.
:param list(str) names: names for the magic values to add or update
:param list(int) values: value for the magic values
:return:
"""
if len(names) == 0 or len(values) == 0 or (not len(names) == len(values)):
return
names_buf = (ctypes.c_char_p * len(names))()
for i in range(0, len(names)):
names_buf[i] = names[i].encode('charmap')
values_buf = (ctypes.c_ulonglong * len(values))()
for i in range(0, len(values)):
values_buf[i] = values[i]
core.BNAddExpressionParserMagicValues(self.handle, names_buf, values_buf, len(names))
[docs]
def remove_expression_parser_magic_values(self, names: List[str]) -> None:
"""
Remove a list of magic value from the expression parser
If any of the magic values gets referenced after removal, an error will occur during the parsing.
:param list(str) names: names for the magic value to remove
:return:
"""
if len(names) == 0:
return
names_buf = (ctypes.c_char_p * len(names))()
for i in range(0, len(names)):
names_buf[i] = names[i].encode('charmap')
core.BNRemoveExpressionParserMagicValues(self.handle, names_buf, len(names))
[docs]
def get_expression_parser_magic_value(self, name: str) -> Optional[int]:
"""
Get the value of an expression parser magic value
If the queried magic value exists, the function returns true and the magic value is returned in `value`.
If the queried magic value does not exist, the function returns None.
:param name: name for the magic value to query
:return:
"""
result = ctypes.c_ulonglong()
if not core.BNGetExpressionParserMagicValue(self.handle, name, result):
return None
return result.value
[docs]
def get_callers(self, addr: int) -> Generator[ReferenceSource, None, None]:
"""
``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.
:param int addr: virtual address of callee to query for callers
:return: List of References that call the given virtual address
:rtype: list(ReferenceSource)
:Example:
>>> bv.get_callers(here)
[<ref: x86@0x4165ff>]
>>>
"""
count = ctypes.c_ulonglong(0)
refs = core.BNGetCallers(self.handle, addr, count)
assert refs is not None, "core.BNGetCallers returned None"
try:
for i in range(0, count.value):
yield ReferenceSource._from_core_struct(self, refs[i])
finally:
core.BNFreeCodeReferences(refs, count.value)
[docs]
def get_callees(self, addr: int, func: Optional['_function.Function'] = None,
arch: Optional['architecture.Architecture'] = None) -> List[int]:
"""
``get_callees`` returns a list of virtual addresses called by the call site in the function ``func``,
of the architecture ``arch``, and at the address ``addr``. If no function is specified, call sites from
all functions and containing the address will be considered. If no architecture is specified, the
architecture of the function will be used.
:param int addr: virtual address of the call site to query for callees
:param Function func: (optional) the function that the call site belongs to
:param Architecture func: (optional) the architecture of the call site
:return: list of integers
:rtype: list(integer)
"""
result = []
funcs = self.get_functions_containing(addr) if func is None else [func]
if not funcs:
return []
for src_func in funcs:
src_arch = src_func.arch if arch is None else arch
assert src_arch is not None
ref_src = core.BNReferenceSource(src_func.handle, src_arch.handle, addr)
count = ctypes.c_ulonglong(0)
refs = core.BNGetCallees(self.handle, ref_src, count)
assert refs is not None, "core.BNGetCallees returned None"
try:
for i in range(0, count.value):
result.append(refs[i])
finally:
core.BNFreeAddressList(refs)
return result
[docs]
def get_symbol_at(self, addr: int, namespace: '_types.NameSpaceType' = None) -> Optional['_types.CoreSymbol']:
"""
``get_symbol_at`` returns the Symbol at the provided virtual address.
:param addr: virtual address to query for symbol
:param namespace: (optional) the namespace of the symbols to retrieve
:return: CoreSymbol for the given virtual address
:rtype: CoreSymbol
:Example:
>>> bv.get_symbol_at(bv.entry_point)
<FunctionSymbol: "_start" @ 0x100001174>
>>>
"""
_namespace = _types.NameSpace.get_core_struct(namespace)
sym = core.BNGetSymbolByAddress(self.handle, addr, _namespace)
if sym is None:
return None
return _types.CoreSymbol(sym)
[docs]
def get_symbols_by_raw_name(self, name: str, namespace: '_types.NameSpaceType' = None) -> List['_types.CoreSymbol']:
_namespace = _types.NameSpace.get_core_struct(namespace)
count = ctypes.c_ulonglong(0)
syms = core.BNGetSymbolsByRawName(self.handle, name, count, _namespace)
assert syms is not None, "core.BNGetSymbolsByRawName returned None"
result = []
try:
for i in range(0, count.value):
handle = core.BNNewSymbolReference(syms[i])
assert handle is not None, "core.BNNewSymbolReference returned None"
result.append(_types.CoreSymbol(handle))
return result
finally:
core.BNFreeSymbolList(syms, count.value)
[docs]
def get_symbol_by_raw_name(self, name: str,
namespace: '_types.NameSpaceType' = None) -> Optional['_types.CoreSymbol']:
"""
``get_symbol_by_raw_name`` retrieves a Symbol object for the given raw (mangled) name.
:param name: raw (mangled) name of Symbol to be retrieved
:param namespace: (optional) the namespace to search for the given symbol
:return: CoreSymbol object corresponding to the provided raw name
:rtype: CoreSymbol
:Example:
>>> bv.get_symbol_by_raw_name('?testf@Foobar@@SA?AW4foo@1@W421@@Z')
<FunctionSymbol: "public: static enum Foobar::foo __cdecl Foobar::testf(enum Foobar::foo)" @ 0x10001100>
>>>
"""
_namespace = _types.NameSpace.get_core_struct(namespace)
sym = core.BNGetSymbolByRawName(self.handle, name, _namespace)
if sym is None:
return None
return _types.CoreSymbol(sym)
[docs]
def get_symbols_by_name(
self, name: str, namespace: '_types.NameSpaceType' = None, ordered_filter: Optional[List[SymbolType]] = None
) -> List['_types.CoreSymbol']:
"""
``get_symbols_by_name`` retrieves a list of Symbol objects for the given symbol name and ordered filter
:param name: name of Symbol object to be retrieved
:param namespace: (optional) the namespace to search for the given symbol
:param namespace: (optional) the namespace to search for the given symbol
:param ordered_filter: (optional) an ordered filter based on SymbolType
:return: Symbol object corresponding to the provided name
:rtype: Symbol
:Example:
>>> bv.get_symbols_by_name('?testf@Foobar@@SA?AW4foo@1@W421@@Z')
[<FunctionSymbol: "public: static enum Foobar::foo __cdecl Foobar::testf(enum Foobar::foo)" @ 0x10001100>]
>>>
"""
if ordered_filter is None:
ordered_filter = [
SymbolType.FunctionSymbol, SymbolType.ImportedFunctionSymbol, SymbolType.LibraryFunctionSymbol, SymbolType.SymbolicFunctionSymbol,
SymbolType.DataSymbol, SymbolType.ImportedDataSymbol, SymbolType.ImportAddressSymbol,
SymbolType.ExternalSymbol, SymbolType.LocalLabelSymbol
]
_namespace = _types.NameSpace.get_core_struct(namespace)
count = ctypes.c_ulonglong(0)
syms = core.BNGetSymbolsByName(self.handle, name, count, _namespace)
assert syms is not None, "core.BNGetSymbolsByName returned None"
result = []
try:
for i in range(0, count.value):
handle = core.BNNewSymbolReference(syms[i])
assert handle is not None, "core.BNNewSymbolReference returned None"
result.append(_types.CoreSymbol(handle))
result = sorted(
filter(lambda sym: sym.type in ordered_filter, result), key=lambda sym: ordered_filter.index(sym.type)
)
return result
finally:
core.BNFreeSymbolList(syms, count.value)
[docs]
def get_symbols(
self, start: Optional[int] = None, length: Optional[int] = None, namespace: '_types.NameSpaceType' = None
) -> List['_types.CoreSymbol']:
"""
``get_symbols`` retrieves the list of all Symbol objects in the optionally provided range.
:param start: optional start virtual address
:param length: optional length
:return: list of all Symbol objects, or those Symbol objects in the range of ``start``-``start+length``
:rtype: list(Symbol)
:Example:
>>> bv.get_symbols(0x1000200c, 1)
[<ImportAddressSymbol: "KERNEL32!IsProcessorFeaturePresent" @ 0x1000200c>]
>>>
"""
count = ctypes.c_ulonglong(0)
_namespace = _types.NameSpace.get_core_struct(namespace)
if start is None:
syms = core.BNGetSymbols(self.handle, count, _namespace)
assert syms is not None, "core.BNGetSymbols returned None"
else:
if length is None:
length = 1
syms = core.BNGetSymbolsInRange(self.handle, start, length, count, namespace)
assert syms is not None, "core.BNGetSymbolsInRange returned None"
result = []
try:
for i in range(0, count.value):
sym_handle = core.BNNewSymbolReference(syms[i])
assert sym_handle is not None, "core.BNNewSymbolReference returned None"
result.append(_types.CoreSymbol(sym_handle))
return result
finally:
core.BNFreeSymbolList(syms, count.value)
[docs]
def get_symbols_of_type(
self, sym_type: SymbolType, start: Optional[int] = None, length: Optional[int] = None,
namespace: '_types.NameSpaceType' = None
) -> List['_types.CoreSymbol']:
"""
``get_symbols_of_type`` retrieves a list of all :py:class:`~binaryninja.types.Symbol` objects of the provided symbol type in the optionally
provided range.
:param sym_type: A Symbol type: :py:class:`~binaryninja.enums.SymbolType`
:param start: optional start virtual address
:param length: optional length
:return: list of all :py:class:`~binaryninja.types.Symbol` objects of type ``sym_type``, or those :py:class:`~binaryninja.types.Symbol` objects in the range of ``start``-``start+length``
:rtype: list(CoreSymbol)
:Example:
>>> bv.get_symbols_of_type(SymbolType.ImportAddressSymbol, 0x10002028, 1)
[<ImportAddressSymbol: "KERNEL32!GetCurrentThreadId" @ 0x10002028>]
>>>
"""
if isinstance(sym_type, str):
sym_type = SymbolType[sym_type]
_namespace = _types.NameSpace.get_core_struct(namespace)
count = ctypes.c_ulonglong(0)
if start is None:
syms = core.BNGetSymbolsOfType(self.handle, sym_type, count, _namespace)
assert syms is not None, "core.BNGetSymbolsOfType returned None"
else:
if length is None:
raise Exception("Length must be provided if start is present")
syms = core.BNGetSymbolsOfTypeInRange(self.handle, sym_type, start, length, count, _namespace)
assert syms is not None, "core.BNGetSymbolsOfTypeInRange returned None"
result = []
try:
for i in range(0, count.value):
sym_handle = core.BNNewSymbolReference(syms[i])
assert sym_handle is not None, "core.BNNewSymbolReference returned None"
result.append(_types.CoreSymbol(sym_handle))
return result
finally:
core.BNFreeSymbolList(syms, count.value)
[docs]
def define_auto_symbol(self, sym: '_types.CoreSymbol') -> None:
"""
``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.
:param sym: the symbol to define
:rtype: None
"""
core.BNDefineAutoSymbol(self.handle, sym.handle)
[docs]
def define_auto_symbol_and_var_or_function(
self, sym: '_types.CoreSymbol', type: '_types.Type', plat: Optional['_platform.Platform'] = None
) -> Optional['_types.CoreSymbol']:
"""
``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.
:param sym: Symbol to define
:param type: Type for the function/variable being defined (can be None)
:param plat: Platform (optional)
:rtype: Optional[CoreSymbol]
"""
if plat is None:
if self.platform is None:
raise Exception("Attempting to call define_auto_symbol_and_var_or_function without Platform specified")
plat = self.platform
elif not isinstance(plat, _platform.Platform):
raise ValueError("Provided platform is not of type `Platform`")
if isinstance(type, _types.Type):
type = type.handle
elif type is not None:
raise ValueError("Provided type is not of type `binaryninja.Type`")
_sym = core.BNDefineAutoSymbolAndVariableOrFunction(self.handle, plat.handle, sym.handle, type)
if _sym is None:
return None
return _types.CoreSymbol(_sym)
[docs]
def undefine_auto_symbol(self, sym: '_types.CoreSymbol') -> None:
"""
``undefine_auto_symbol`` removes a symbol from the internal list of automatically discovered Symbol objects.
:param Symbol sym: the symbol to undefine
:rtype: None
"""
core.BNUndefineAutoSymbol(self.handle, sym.handle)
[docs]
def define_user_symbol(self, sym: '_types.CoreSymbol') -> None:
"""
``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.
:param Symbol sym: the symbol to define
:rtype: None
"""
core.BNDefineUserSymbol(self.handle, sym.handle)
[docs]
def undefine_user_symbol(self, sym: '_types.CoreSymbol') -> None:
"""
``undefine_user_symbol`` removes a symbol from the internal list of user added Symbol objects.
:param sym: the symbol to undefine
:rtype: None
"""
core.BNUndefineUserSymbol(self.handle, sym.handle)
[docs]
def define_imported_function(
self, import_addr_sym: '_types.CoreSymbol', func: '_function.Function', type: Optional['_types.Type'] = None
) -> None:
"""
``define_imported_function`` defines an imported Function ``func`` with a ImportedFunctionSymbol type.
:param import_addr_sym: A Symbol object with type ImportedFunctionSymbol
:param func: A Function object to define as an imported function
:param type: Optional type for the function
:rtype: None
"""
core.BNDefineImportedFunction(
self.handle, import_addr_sym.handle, func.handle, <