# coding=utf-8

# Copyright (c) 2015-2026 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, Sequence, Mapping, Any, \

Iterator, Iterable, KeysView, ItemsView, ValuesView, Dict, overload

from dataclasses import dataclass, field

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, DerivedStringLocationType, MetadataStoreFlag

)

from .exceptions import RelocationWriteException, ExternalLinkException

from . import associateddatastore # required for _BinaryViewAssociatedDataStore

from .log import log_warn, log_error_for_exception, 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 undo

from . import stringrecognizer

PathType = Union[str, os.PathLike]

InstructionsType = Generator[Tuple[List['_function.InstructionTextToken'], int], None, None]

ProgressFuncType = Callable[[int, int], bool]

DataMatchCallbackType = Callable[[int, 'databuffer.DataBuffer'], bool]

TextMatchCallbackType = Callable[[int, str, 'lineardisassembly.LinearDisassemblyLine'], bool]

LineMatchCallbackType = Callable[[int, 'lineardisassembly.LinearDisassemblyLine'], bool]

StringOrType = Union[str, '_types.Type', '_types.TypeBuilder']

@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 llils(self) -> List[lowlevelil.LowLevelILInstruction]:

"""Returns the low level il instructions at the current location if any exists"""

if self.function is None or self.arch is None:

return []

return self.function.get_low_level_ils_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 mlils(self) -> Iterator[mediumlevelil.MediumLevelILInstruction]:

"""Returns the medium level il instructions at the current location if any exists"""

if self.function is None or self.arch is None:

return

for llil in self.llils:

for mlil in llil.mlils:

yield mlil

@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

@property

def hlils(self) -> Iterator[highlevelil.HighLevelILInstruction]:

"""Returns the high level il instructions at the current location if any exists"""

if self.function is None or self.arch is None:

return

for llil in self.llils:

for hlil in llil.hlils:

yield hlil

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

Rebased = 1 << 52

DerivedStringFound = 1 << 53

DerivedStringRemoved = 1 << 54

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

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

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().__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: Optional[NotificationType] = None):

self.notifications = notifications

def notification_barrier(self, view: 'BinaryView') -> int:

return 0

def data_written(self, view: 'BinaryView', offset: int, length: int) -> None:

pass

def data_inserted(self, view: 'BinaryView', offset: int, length: int) -> None:

pass

def data_removed(self, view: 'BinaryView', offset: int, length: int) -> None:

pass

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

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

def function_updated(self, view: 'BinaryView', func: '_function.Function') -> None:

pass

def function_update_requested(self, view: 'BinaryView', func: '_function.Function') -> None:

pass

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

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

def data_var_updated(self, view: 'BinaryView', var: 'DataVariable') -> None:

pass

def data_metadata_updated(self, view: 'BinaryView', offset: int) -> None:

pass

def tag_type_updated(self, view: 'BinaryView', tag_type) -> None:

pass

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

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

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

def symbol_added(self, view: 'BinaryView', sym: '_types.CoreSymbol') -> None:

pass

def symbol_updated(self, view: 'BinaryView', sym: '_types.CoreSymbol') -> None:

pass

def symbol_removed(self, view: 'BinaryView', sym: '_types.CoreSymbol') -> None:

pass

def string_found(self, view: 'BinaryView', string_type: StringType, offset: int, length: int) -> None:

pass

def string_removed(self, view: 'BinaryView', string_type: StringType, offset: int, length: int) -> None:

pass

def derived_string_found(self, view: 'BinaryView', string: 'DerivedString') -> None:

pass

def derived_string_removed(self, view: 'BinaryView', string: 'DerivedString') -> None:

pass

def type_defined(self, view: 'BinaryView', name: '_types.QualifiedName', type: '_types.Type') -> None:

pass

def type_undefined(self, view: 'BinaryView', name: '_types.QualifiedName', type: '_types.Type') -> None:

pass

def type_ref_changed(self, view: 'BinaryView', name: '_types.QualifiedName', type: '_types.Type') -> None:

pass

def type_field_ref_changed(self, view: 'BinaryView', name: '_types.QualifiedName', offset: int) -> None:

pass

def segment_added(self, view: 'BinaryView', segment: 'Segment') -> None:

pass

def segment_updated(self, view: 'BinaryView', segment: 'Segment') -> None:

pass

def segment_removed(self, view: 'BinaryView', segment: 'Segment') -> None:

pass

def section_added(self, view: 'BinaryView', section: 'Section') -> None:

pass

def section_updated(self, view: 'BinaryView', section: 'Section') -> None:

pass

def section_removed(self, view: 'BinaryView', section: 'Section') -> None:

pass

def component_added(self, view: 'BinaryView', _component: component.Component) -> None:

pass

def component_removed(self, view: 'BinaryView', formerParent: component.Component,

_component: component.Component) -> None:

pass

def component_name_updated(self, view: 'BinaryView', previous_name: str, _component: component.Component) -> None:

pass

def component_moved(self, view: 'BinaryView', formerParent: component.Component, newParent: component.Component,

_component: component.Component) -> None:

pass

def component_function_added(self, view: 'BinaryView', _component: component.Component, func: '_function.Function'):

pass

def component_function_removed(self, view: 'BinaryView', _component: component.Component,

func: '_function.Function'):

pass

def component_data_var_added(self, view: 'BinaryView', _component: component.Component, var: 'DataVariable'):

pass

def component_data_var_removed(self, view: 'BinaryView', _component: component.Component, var: 'DataVariable'):

pass

def type_archive_attached(self, view: 'BinaryView', id: str, path: str):

pass

def type_archive_detached(self, view: 'BinaryView', id: str, path: str):

pass

def type_archive_connected(self, view: 'BinaryView', archive: 'typearchive.TypeArchive'):

pass

def type_archive_disconnected(self, view: 'BinaryView', archive: 'typearchive.TypeArchive'):

pass

def undo_entry_added(self, view: 'BinaryView', entry: 'undo.UndoEntry'):

pass

def undo_entry_taken(self, view: 'BinaryView', entry: 'undo.UndoEntry'):

pass

def redo_entry_taken(self, view: 'BinaryView', entry: 'undo.UndoEntry'):

pass

def rebased(self, old_view: 'BinaryView', new_view: 'BinaryView'):

pass

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], errors='replace')

@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

@dataclass

class StringDetectionParameters:

"""Parameters controlling raw string detection, as used by the core strings analysis."""

min_string_length: int = 4

utf8_enabled: bool = True

utf16_enabled: bool = True

utf32_enabled: bool = True

unicode_block_names: List[str] = field(default_factory=list)

@classmethod

def from_settings(

cls, settings_obj: Optional['settings.Settings'] = None, view: Optional['BinaryView'] = None

) -> 'StringDetectionParameters':

"""

``from_settings`` builds parameters from the standard string-analysis settings:

``analysis.limits.minStringLength`` and ``analysis.unicode.{blocks,utf8,utf16,utf32}``.

"""

if settings_obj is None:

settings_obj = settings.Settings()

return cls(

min_string_length=settings_obj.get_integer("analysis.limits.minStringLength", view),

utf8_enabled=settings_obj.get_bool("analysis.unicode.utf8", view),

utf16_enabled=settings_obj.get_bool("analysis.unicode.utf16", view),

utf32_enabled=settings_obj.get_bool("analysis.unicode.utf32", view),

unicode_block_names=settings_obj.get_string_list("analysis.unicode.blocks", view)

)

@dataclass(frozen=True)

class DetectedString:

"""A string detected by :py:class:`StringDetector`. ``start`` is relative to the ``base_address``

passed to the detector, and ``length`` is in bytes."""

type: StringType

start: int

length: int

class StringDetector:

"""A reusable string detector using the same detection logic as the core strings analysis. Unlike

:py:meth:`BinaryView.get_strings`, the data scanned does not need to be part of a BinaryView.

The detector is immutable once constructed, so a single instance may be shared across threads.

:param parameters: Detection parameters; defaults to the current global settings

"""

def __init__(self, parameters: Optional[StringDetectionParameters] = None):

if parameters is None:

parameters = StringDetectionParameters.from_settings()

params = core.BNStringDetectionParameters()

params.minStringLength = parameters.min_string_length

params.utf8Enabled = parameters.utf8_enabled

params.utf16Enabled = parameters.utf16_enabled

params.utf32Enabled = parameters.utf32_enabled

block_names = (ctypes.c_char_p * len(parameters.unicode_block_names))()

for i, name in enumerate(parameters.unicode_block_names):

block_names[i] = core.cstr(name)

params.unicodeBlockNames = ctypes.cast(block_names, ctypes.POINTER(ctypes.c_char_p))

params.unicodeBlockNameCount = len(parameters.unicode_block_names)

self.handle = core.BNCreateStringDetector(params)

assert self.handle is not None, "core.BNCreateStringDetector returned None"

def __del__(self):

if core is not None:

core.BNFreeStringDetector(self.handle)

def detect_strings(

self, data: bytes, block_len: Optional[int] = None, base_address: int = 0,

last_found: Optional[DetectedString] = None

) -> List[DetectedString]:

"""

``detect_strings`` detects strings in a raw data buffer.

Strings must start within the first ``block_len`` bytes of ``data`` but may extend to the end

of ``data``, allowing a large buffer to be scanned in chunks with a ``BN_MAX_STRING_LENGTH``

overlap tail. When scanning consecutive chunks, pass the last string detected so far as

``last_found`` so a string spanning a chunk boundary is not reported twice.

:param data: Buffer to scan

:param block_len: Number of bytes within which strings may start; defaults to ``len(data)``

:param base_address: Address reported for offset 0 of ``data``

:param last_found: Cross-chunk overlap state, the last string detected in a prior chunk

:return: The strings detected, with addresses relative to ``base_address``

"""

if block_len is None:

block_len = len(data)

last_ref = None

if last_found is not None:

last_ref = core.BNStringReference()

last_ref.type = last_found.type

last_ref.start = last_found.start

last_ref.length = last_found.length

buf = (ctypes.c_ubyte * len(data)).from_buffer_copy(data)

count = ctypes.c_ulonglong()

strings = core.BNStringDetectorDetectStrings(

self.handle, buf, len(data), block_len, base_address, last_ref, count

)

assert strings is not None, "core.BNStringDetectorDetectStrings returned None"

result = []

try:

for i in range(count.value):

result.append(DetectedString(StringType(strings[i].type), strings[i].start, strings[i].length))

finally:

core.BNFreeStringReferenceList(strings)

return result

def detect_strings_in_block(

data: bytes, base_address: int = 0, parameters: Optional[StringDetectionParameters] = None

) -> List[DetectedString]:

"""

``detect_strings_in_block`` detects strings in a raw data buffer using the same detection logic

as the core strings analysis. It is a one-shot convenience over :py:class:`StringDetector`; build

a :py:class:`StringDetector` directly to reuse it across buffers or to scan in chunks.

:param data: Buffer to scan

:param base_address: Address reported for offset 0 of ``data``

:param parameters: Detection parameters; defaults to the current global settings

:return: The strings detected

"""

return StringDetector(parameters).detect_strings(data, base_address=base_address)

class StringRef:

"""Deduplicated reference to a string owned by the Binary Ninja core. Use `str` or `bytes` to convert

this to a standard Python string or sequence of bytes."""

def __init__(self, handle):

self.handle = core.handle_of_type(handle, core.BNStringRef)

def __del__(self):

if core is not None:

core.BNFreeStringRef(self.handle)

def __bytes__(self):

# Do not call the wrapper BNGetStringRefContents here, it will crash as the generator

# does not understand that this API gives a direct reference to the string

value_ptr = core._BNGetStringRefContents(self.handle)

value_len = core.BNGetStringRefSize(self.handle)

buf = ctypes.create_string_buffer(value_len)

ctypes.memmove(buf, value_ptr, value_len)

return bytes(buf.raw)

def __str__(self):

return core.pyNativeStr(bytes(self))

def __len__(self):

return core.BNGetStringRefSize(self.handle)

def __repr__(self):

return repr(str(self))

def __eq__(self, other):

if not isinstance(other, self.__class__):

return NotImplemented

return bytes(self) == bytes(other)

def __ne__(self, other):

if not isinstance(other, self.__class__):

return NotImplemented

return not (self == other)

def __lt__(self, other) -> bool:

if not isinstance(other, self.__class__):

return NotImplemented

return bytes(self) < bytes(self)

def __gt__(self, other) -> bool:

if not isinstance(other, self.__class__):

return NotImplemented

return bytes(self) > bytes(other)

def __le__(self, other) -> bool:

if not isinstance(other, self.__class__):

return NotImplemented

return bytes(self) <= bytes(other)

def __ge__(self, other) -> bool:

if not isinstance(other, self.__class__):

return NotImplemented

return bytes(self) >= bytes(other)

def __hash__(self):

return hash(bytes(self))

@dataclass(frozen=True)

class DerivedStringLocation:

"""Location associated with a derived string. Locations are optional."""

location_type: 'DerivedStringLocationType'

address: int

length: int

@dataclass(frozen=True)

class DerivedString:

"""

Contains a string derived from code or data. The string does not need to be directly present in

the binary in its raw form. Derived strings can have optional locations to data or code. When

creating new derived strings, a custom type should be registered with

:py:func:`~binaryninja.stringrecognizer.CustomStringType.register` on :py:class:`~binaryninja.stringrecognizer.CustomStringType`.

"""

value: 'StringRef'

location: Optional[DerivedStringLocation]

custom_type: Optional[stringrecognizer.CustomStringType]

def __init__(

self, value: Union['StringRef', str, bytes, bytearray, 'databuffer.DataBuffer'],

location: Optional[DerivedStringLocation], custom_type: Optional[stringrecognizer.CustomStringType]

):

if isinstance(value, str):

value = value.encode("utf-8")

value = StringRef(core.BNCreateStringRefOfLength(value, len(value)))

elif isinstance(value, bytes):

value = StringRef(core.BNCreateStringRefOfLength(value, len(value)))

elif isinstance(value, bytearray):

value = bytes(value)

value = StringRef(core.BNCreateStringRefOfLength(value, len(value)))

elif isinstance(value, databuffer.DataBuffer):

value = bytes(value)

value = StringRef(core.BNCreateStringRefOfLength(value, len(value)))

elif not isinstance(value, StringRef):

value = str(value).encode("utf-8")

value = StringRef(core.BNCreateStringRefOfLength(value, len(value)))

object.__setattr__(self, "value", value)

object.__setattr__(self, "location", location)

object.__setattr__(self, "custom_type", custom_type)

def _to_core_struct(self, owned: bool) -> 'core.BNDerivedString':

result = core.BNDerivedString()

if owned:

result.value = core.BNDuplicateStringRef(self.value.handle)

else:

result.value = self.value.handle

result.locationValid = self.location is not None

if result.locationValid:

result.location.locationType = self.location.location_type

result.location.addr = self.location.address

result.location.len = self.location.length

if self.custom_type is None:

result.customType = None

else:

result.customType = self.custom_type.handle

return result

@staticmethod

def _from_core_struct(obj: 'core.BNDerivedString', owned: bool) -> 'DerivedString':

if owned:

value = StringRef(obj.value)

else:

value = StringRef(core.BNDuplicateStringRef(obj.value))

if obj.locationValid:

location = DerivedStringLocation(DerivedStringLocationType(obj.location.locationType), obj.location.addr, obj.location.len)

else:

location = None

if obj.customType:

custom_type = stringrecognizer.CustomStringType(obj.customType)

else:

custom_type = None

return DerivedString(value, location, custom_type)

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

log_error_for_exception("Unhandled Python exception in AnalysisCompletionEvent._notify")

def _empty_callback(self):

pass

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

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 = {}

@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 Exception:

log_error_for_exception("Unhandled Python exception in BinaryViewEvent._notify")

@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}>"

@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}>"

@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.DiscoveryState:

return "Discovery"

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

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 (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.derivedStringFound = self._cb.derivedStringFound.__class__(self._derived_string_found)

self._cb.derivedStringRemoved = self._cb.derivedStringRemoved.__class__(self._derived_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)