debugger.debuggercontroller module¶

Bases: object

DebugBreakpoint represents a breakpoint in the target. It has the following fields:

• module: the name of the module for which the breakpoint is in

• offset: the offset of the breakpoint to the start of the module

• address: the absolute address of the breakpoint

• enabled: whether the breakpoint is enabled (read-only)

• condition: the condition expression for the breakpoint (empty if no condition)

• type: the type of breakpoint (Software, HardwareExecute, HardwareRead, HardwareWrite, HardwareAccess)

• size: the size in bytes for hardware breakpoints/watchpoints (1, 2, 4, or 8)

__init__(module: str, offset: int, address: int, enabled: bool, condition: str = '', type: DebugBreakpointType = DebugBreakpointType.BNSoftwareBreakpoint, size: int = 1) → None¶

Parameters:

• module (str) –

• offset (int) –

• address (int) –

• enabled (bool) –

• condition (str) –

• type (DebugBreakpointType) –

• size (int) –

Return type:

None

address: int¶

condition: str = ''¶

enabled: bool¶

module: str¶

offset: int¶

size: int = 1¶

type: DebugBreakpointType = 0¶

Bases: object

DebugBreakpoints represents all breakpoints of the target.

__init__(breakpoints: List[DebugBreakpoint])[source]¶

Parameters:

breakpoints (List[DebugBreakpoint]) –

Bases: object

DebugFrame represents a frame in the stack trace. It has the following fields:

• index: the index of the frame

• pc: the program counter of the frame

• sp: the stack pointer of the frame

• fp: the frame pointer of the frame

• func_name: the function name which the pc is in

• func_start: the start of the function

• module: the module of the pc

__init__(index, pc, sp, fp, func_name, func_start, module)[source]¶

Bases: object

DebugModule represents a module in the target. It has the following fields:

• name: the path of the module

• short_name: the name of the module

• address: the base load address of the module

• size: the size of the module

• loaded: not used

__init__(name, short_name, address, size, loaded)[source]¶

static is_same_base_module(module1: str | bytes, module2: str | bytes) → bool[source]¶

Parameters:

• module1 (str | bytes) –

• module2 (str | bytes) –

Return type:

bool

Bases: object

DebugModules represents all modules of the target.

__init__(modules: List[DebugModule])[source]¶

Parameters:

modules (List[DebugModule]) –

Bases: object

DebugProcess represents a process in the target. It has the following fields:

• pid: the ID of the process

• name: the name of the process

• command_line: the command line of the process

__init__(pid, name, command_line='')[source]¶

Bases: object

DebugRegister represents a register in the target. It has the following fields:

• name: the name of the register

• value: the value of the register

• width: the width of the register, in bits. E.g., rax register is 64-bits wide

• index: the index of the register. This is reported by the DebugAdapter and should remain unchanged

• hint: a string that shows the content of the memory pointed to by the register. It is empty if the register value do not point to a valid (mapped) memory region

__init__(name, value, width, index, hint)[source]¶

Bases: object

DebugRegisters represents all registers of the target.

__init__(handle)[source]¶

Bases: object

DebugThread represents a thread in the target. It has the following fields:

• tid: the ID of the thread. On different systems, this may be either the system thread ID, or a sequential index starting from zero.

• rip: the current address (instruction pointer) of the thread

In the future, we should provide both the internal thread ID and the system thread ID.

__init__(tid, rip)[source]¶

Bases: object

DebugThreads represents all threads of the target.

__init__(threads: List[DebugThread])[source]¶

Parameters:

threads (List[DebugThread]) –

Bases: object

The DebuggerController object is the core of the debugger. Most debugger operations can be performed on it. It takes in a BinaryView and creates a debugger for it. If a debugger is already existing for the very same BinaryView object, the debugger is returned.

Most operations of the debugger are performed on this class. For example, we can launch the debugger as follows:

>>> bv = load("test/binaries/helloworld")
>>> dbg = DebuggerController(bv)
>>> dbg.launch_and_wait()
<DebugStopReason.Breakpoint: 6>

When the launch_and_wait() returns DebugStopReason.Breakpoint, it means the debugger has launched the target successfully, and the target stopped at the entry point of the binary. Now we can perform other control operations on it, e.g., resume the target by calling step_into_and_wait().

>>> dbg.step_into_and_wait()
<DebugStopReason.SingleStep: 4>

For all the API functions that resume the target, e.g., launch go, step into, etc, there are two variants of them. One of them resumes the target and waits for it to stop again synchronously, step_into_and_wait will do a step into, and it only returns AFTER the target stops again. This is more frequently used, and is suitable for automating a sequence of actions. However, after calling such a synchronous API, if for any reason the target does not stop as expected, Binary Ninja might be confused or hang.

The second set of API works asynchronously. For example, step into will only do a step into, but does NOT wait for the target to stop again. Usually the asynchronous API is used with register_event_callback to listen for the relevant events (e.g., target resumed, stopped, etc). The asynchronous API is harder to use and is only recommended when the synchronous version does not suit your need. The Binary Ninja debugger UI uses the asynchronous API.

To retrieve all the registers, run regs:

>>> dbg.regs
{'x0': <DebugRegister: x0, 0x1>, ...}

More often we only need get the value of one regisgter:

>>> dbg.regs['x1']
<DebugRegister: x1, 0x16fdffa70, &"/Users/xxxx//debugger/test/binaries/Darwin-arm64-signed/helloworld">

The result contains the register value as well as a string that can be dereferenced at its value.

ip returns the current intrudction pointer, and stack_pointer` returns the stack pointer:

>>> dbg.stack_pointer
6171916256
>>> dbg.ip
4294983364

To read/write memory value, use read_memory/write_memory. Or you can directly read/write the binary view object returned by dbg.data.

>>> dbg.read_memory(dbg.ip, 0x10)
<binaryninja.databuffer.DataBuffer object at 0x32ffa2f90>
>>> dbg.data.read(dbg.ip, 0x10)
b'ý{©ýѿø ƒ¸'

>>> dbg.write_memory(dbg.stack_pointer, b'a' * 0x10)
True
>>> dbg.data.write(dbg.stack_pointer, b'a' * 0x10)
16

modules returns the list of modules, threads returns the list of threads.

Breakpoints can be added via add_breakpoint:

>>> dbg.add_breakpoint(0x100003ed0)

And it will be hit after we resume the target with go_and_wait:

>>> dbg.go_and_wait()
<DebugStopReason.Breakpoint: 6>

We can resume it again:

>>> dbg.go_and_wait()
<DebugStopReason.ProcessExited: 2>

Since there are no other breakpoints in the target, the process executes and then exits.

For more examples of using the debugger Python API, feel free to get some inspirations from our [unit tests](https://github.com/Vector35/debugger/blob/dev/test/debugger_test.py)

__init__(bv: BinaryView)[source]¶

Parameters:

bv (BinaryView) –

add_breakpoint(address)[source]¶

Add a breakpoint

The input can be either an absolute address, or a ModuleNameAndOffset, which specifies a relative address to the start of a module. The latter is useful for ASLR.

Parameters:

address – the address of breakpoint to add

add_hardware_breakpoint(address, bp_type: DebugBreakpointType, size: int = 1) → bool[source]¶

Add a hardware breakpoint

The input can be either an absolute address, or a ModuleNameAndOffset, which specifies a relative address to the start of a module. The latter is useful for ASLR.

Parameters:

• address – the address of breakpoint to add

• bp_type (DebugBreakpointType) – the type of hardware breakpoint (DebugBreakpointType.BNHardwareExecuteBreakpoint, BNHardwareReadBreakpoint, BNHardwareWriteBreakpoint, or BNHardwareAccessBreakpoint)

• size (int) – the size in bytes for the watchpoint (1, 2, 4, or 8)

Returns:

True if successful, False otherwise

Return type:

bool

add_ttd_bookmark(position, note='', view_address=0)[source]¶

Add a TTD bookmark. If a bookmark with the same position already exists, it is updated.

Parameters:

• position – TTDPosition object or string in format “sequence:step”

• note – optional note for the bookmark

• view_address – optional view address to navigate to when the bookmark is activated

Returns:

True if the bookmark was added/updated successfully

Return type:

bool

attach() → bool[source]¶

Attach to a running process

The PID of the target process must be set via DebuggerState.pid_attach

Return type:

bool

attach_and_wait() → DebugStopReason[source]¶

Attach to a running process and wait until all debugger events are processed

The PID of the target process must be set via DebuggerState.pid_attach

Return type:

DebugStopReason

clear_ttd_bookmarks()[source]¶

Remove all TTD bookmarks.

clear_ttd_position_history()[source]¶

Clear the TTD position navigation history.

connect() → bool[source]¶

Connect to a remote target (process)

The host and port of the remote target must first be specified by setting remote_host and remote_port

Return type:

bool

connect_and_wait() → DebugStopReason[source]¶

Connect to a remote target (process) and wait for all debugger events to be processed

The host and port of the remote target must first be specified by setting remote_host and remote_port

Return type:

DebugStopReason

connect_to_debug_server() → bool[source]¶

Connect to a debug server.

The host and port of the debug server must first be specified by setting remote_host and remote_port

Return type:

bool

delete_breakpoint(address)[source]¶

Delete a breakpoint

The input can be either an absolute address, or a ModuleNameAndOffset, which specifies a relative address to the start of a module. The latter is useful for ASLR.

Parameters:

address – the address of breakpoint to delete

delete_hardware_breakpoint(address, bp_type: DebugBreakpointType, size: int = 1) → bool[source]¶

Delete a hardware breakpoint

The input can be either an absolute address, or a ModuleNameAndOffset, which specifies a relative address to the start of a module. The latter is useful for ASLR.

Parameters:

• address – the address of breakpoint to delete

• bp_type (DebugBreakpointType) – the type of hardware breakpoint (DebugBreakpointType.BNHardwareExecuteBreakpoint, BNHardwareReadBreakpoint, BNHardwareWriteBreakpoint, or BNHardwareAccessBreakpoint)

• size (int) – the size in bytes for the watchpoint (1, 2, 4, or 8)

Returns:

True if successful, False otherwise

Return type:

bool

destroy()[source]¶

Delete the DebuggerController object. Intended for internal use. Ordinary users do not need to call it.

detach() → None[source]¶

Detach the target, and let it execute on its own.

Return type:

None

disable_breakpoint(address)[source]¶

Disable a breakpoint

The input can be either an absolute address, or a ModuleNameAndOffset, which specifies a relative address to the start of a module. The latter is useful for ASLR.

Parameters:

address – the address of breakpoint to disable

disconnect_from_debug_server() → None[source]¶

` Disconnect from a debug server.

Return type:

None

enable_breakpoint(address)[source]¶

Enable a breakpoint

The input can be either an absolute address, or a ModuleNameAndOffset, which specifies a relative address to the start of a module. The latter is useful for ASLR.

Parameters:

address – the address of breakpoint to enable

execute_backend_command(command: str | bytes) → str[source]¶

Execute a backend command and get the output

For LLDB adapter, any LLDB commands can be executed. The returned string is what gets printed if one executes the command in the LLDB prompt.

For DbgEnd adapter, any WinDbg commands can be executed. The returned string is what gets printed if one executes the command in WinDbg.

Parameters:

command (str | bytes) –

Return type:

str

frames_of_thread(tid: int) → List[DebugFrame][source]¶

Get the stack frames of the thread specified by tid

Parameters:

tid (int) – thread id

Returns:

list of stack frames

Return type:

List[DebugFrame]

get_adapter_property(name: str | bytes) → binaryninja.metadata.MetadataValueType[source]¶

Parameters:

name (str | bytes) –

Return type:

binaryninja.metadata.MetadataValueType

get_addr_info(addr: int)[source]¶

Parameters:

addr (int) –

get_all_ttd_events() → List[TTDEvent][source]¶

Get all TTD events from the trace.

This method is only available when debugging with TTD (Time Travel Debugging). Use the is_ttd property to check if TTD is available before calling this method.

Returns:

list of all TTDEvent objects in the trace

Return type:

List[TTDEvent]

get_breakpoint_condition(address) → str[source]¶

Get the condition for a breakpoint

Parameters:

address – the address of the breakpoint (int or ModuleNameAndOffset)

Returns:

the condition expression, or empty string if no condition

Return type:

str

get_executed_instruction_count() → int[source]¶

Get the count of executed instructions from the last code coverage analysis.

This method requires that run_code_coverage_analysis() has been called first.

Returns:

number of unique executed instructions

Return type:

int

get_instruction_execution_count(address: int) → int[source]¶

Get the execution count for a specific instruction address.

This method requires that run_code_coverage_analysis() has been called first.

Parameters:

address (int) – address of the instruction to check

Returns:

number of times the instruction was executed (0 if not executed or analysis not run)

Return type:

int

get_reg_value(reg: str | bytes) → int[source]¶

Get the value of one register by its name

Parameters:

reg (str | bytes) – the name of the register

Return type:

int

get_remote_base() → int | None[source]¶

Get the detected remote base address of the target module.

This returns the base address that the debugger detected for the input binary in the remote process. Returns None if not connected or detection failed.

Returns:

The remote base address, or None if unavailable

Return type:

int | None

get_ttd_calls_for_symbols(symbols: str, start_return_address: int = 0, end_return_address: int = 0) → List[TTDCallEvent][source]¶

Get TTD call events for specific symbols/functions.

This method is only available when debugging with TTD (Time Travel Debugging). Use the is_ttd property to check if TTD is available before calling this method.

Parameters:

• symbols (str) – symbol or function name to query (e.g., “MessageBoxA”, “CreateFileA”)

• start_return_address (int) – optional start return address filter (0 = no filter)

• end_return_address (int) – optional end return address filter (0 = no filter)

Returns:

list of TTDCallEvent objects

Raises:

May raise an exception if TTD is not available

Return type:

List[TTDCallEvent]

get_ttd_events(event_type: int) → List[TTDEvent][source]¶

Get TTD events for specific event types using bitfield filtering.

This method is only available when debugging with TTD (Time Travel Debugging). Use the is_ttd property to check if TTD is available before calling this method.

Parameters:

event_type (int) – type of events to query (TTDEventType bitfield flags that can be combined with |)

Returns:

list of TTDEvent objects

Return type:

List[TTDEvent]

get_ttd_memory_access_for_address(address: int, end_address: int, access_type=DebuggerTTDMemoryAccessType.DebuggerTTDMemoryRead) → List[TTDMemoryEvent][source]¶

Get TTD memory access events for a specific address range.

This method is only available when debugging with TTD (Time Travel Debugging). Use the is_ttd property to check if TTD is available before calling this method.

Parameters:

• address (int) – starting memory address to query

• end_address (int) – ending memory address to query

• access_type – type of memory access to query - can be: - DebuggerTTDMemoryAccessType enum values - String specification like “r”, “w”, “e”, “rw”, “rwe”, etc. - Integer values (for backward compatibility)

Returns:

list of TTDMemoryEvent objects

Raises:

May raise an exception if TTD is not available

Return type:

List[TTDMemoryEvent]

get_ttd_memory_access_for_position_range(start_address: int, end_address: int, access_type, start_time: TTDPosition | None = None, end_time: TTDPosition | None = None) → List[TTDPositionRangeIndexedMemoryEvent][source]¶

Get TTD memory access events for a specific address range and time range.

This method is only available when debugging with TTD (Time Travel Debugging). Use the is_ttd property to check if TTD is available before calling this method.

Parameters:

• start_address (int) – starting memory address to query

• end_address (int) – ending memory address to query

• access_type – type of memory access to query - can be: - DebuggerTTDMemoryAccessType enum values - String specification like “r”, “w”, “e”, “rw”, “rwe”, etc. - Integer values (for backward compatibility)

• start_time (TTDPosition | None) – starting TTD position (default: start of trace)

• end_time (TTDPosition | None) – ending TTD position (default: end of trace)

Returns:

list of TTDPositionRangeIndexedMemoryEvent objects

Raises:

May raise an exception if TTD is not available

Return type:

List[TTDPositionRangeIndexedMemoryEvent]

get_ttd_next_memory_access(address: int, size: int, access_type=DebuggerTTDMemoryAccessType.DebuggerTTDMemoryRead)[source]¶

Get the next memory access to a specific address from the current TTD position.

This is more efficient than pulling all accesses and searching, as it uses the TTD NextMemoryAccess API directly.

Parameters:

• address (int) – memory address to monitor

• size (int) – size of the memory region in bytes

• access_type – type of memory access to query (read/write/execute)

Returns:

TTDMemoryEvent if found, None if no subsequent access exists

get_ttd_prev_memory_access(address: int, size: int, access_type=DebuggerTTDMemoryAccessType.DebuggerTTDMemoryRead)[source]¶

Get the previous memory access to a specific address from the current TTD position.

This is more efficient than pulling all accesses and searching, as it uses the TTD PrevMemoryAccess API directly.

Parameters:

• address (int) – memory address to monitor

• size (int) – size of the memory region in bytes

• access_type – type of memory access to query (read/write/execute)

Returns:

TTDMemoryEvent if found, None if no prior access exists

go() → bool[source]¶

Resume the target.

The call is asynchronous and returns before the target stops.

Returns:

whether the operation is successfully requested

Return type:

bool

go_and_wait() → DebugStopReason[source]¶

Resume the target.

The call is blocking and only returns when the target stops.

Returns:

the reason for the stop

Return type:

DebugStopReason

go_reverse() → bool[source]¶

Resume the target in reverse.

The call is asynchronous and returns before the target stops.

Returns:

whether the operation is successfully requested

Return type:

bool

go_reverse_and_wait() → DebugStopReason[source]¶

Resume the target in reverse.

The call is blocking and only returns when the target stops.

Returns:

the reason for the stop

Return type:

DebugStopReason

has_breakpoint(address) → bool[source]¶

Checks whether a breakpoint exists at the specified address

The input can be either an absolute address, or a ModuleNameAndOffset, which specifies a relative address to the start of a module. The latter is useful for ASLR.

Parameters:

address – the address of breakpoint to query

Return type:

bool

is_instruction_executed(address: int) → bool[source]¶

Check if an instruction at a specific address was executed during code coverage analysis.

This method requires that run_code_coverage_analysis() has been called first.

Parameters:

address (int) – address of the instruction to check

Returns:

True if the instruction was executed, False otherwise

Return type:

bool

launch() → bool[source]¶

Launch the target

Return type:

bool

launch_and_wait() → DebugStopReason[source]¶

Launch the target and wait for all debugger events to be processed

Return type:

DebugStopReason

launch_or_connect() → None[source]¶

Launch or connect to the target. Intended for internal use. Ordinary users do not need to call it.

Return type:

None

load_code_coverage_from_file(file_path: str) → bool[source]¶

Load code coverage results from a file.

Parameters:

file_path (str) – path to the file containing code coverage results

Returns:

True if load succeeded, False otherwise

Return type:

bool

navigate_to_timestamp(timestamp_str)[source]¶

Convenience method to navigate to a timestamp string.

Args:

timestamp_str: String in format “sequence:step” (hex or decimal)

Returns:

bool: True if navigation succeeded, False otherwise

pause() → None[source]¶

Pause a running target

Return type:

None

pause_and_wait() → None[source]¶

Pause a running target.

The call is blocking and only returns when the target stops.

Return type:

None

quit() → None[source]¶

Terminate the target

Return type:

None

quit_and_wait() → None[source]¶

Terminate the target, and wait for all callback to be called

Return type:

None

read_memory(address: int, size: int) → DataBuffer[source]¶

Read memory from the target.

One can also get the data BinaryView of the DebuggerController, and use ordinary read methods to read its content.

Parameters:

• address (int) – address to read from

• size (int) – number of bytes to read

Returns:

always returns a DataBuffer. When the operation fails, the size of the DataBuffer is 0x0

Return type:

DataBuffer

rebase_to_address(address: int) → bool[source]¶

Rebase the input binary view to the specified base address.

This allows manual rebasing to a user-specified address, which is useful when the auto-detected remote base is incorrect.

Note: In UI mode, this returns True immediately and the rebase completes asynchronously.

Parameters:

address (int) – The new base address for the binary view

Returns:

True if the rebase was initiated successfully, False otherwise

Return type:

bool

rebase_to_remote_base() → bool[source]¶

Rebase the input binary view to match the remote base address.

This is useful when auto-rebase is disabled (via the debugger.autoRebase setting) and you want to manually trigger a rebase after the target has been launched.

Note: In UI mode, this returns True immediately and the rebase completes asynchronously.

Returns:

True if the rebase was initiated successfully, False otherwise

Return type:

bool

register_event_callback(callback: Callable[[DebuggerEvent], None], name: str | bytes = '') → int[source]¶

Register a debugger event callback to receive notification when various events happen.

The callback receives DebuggerEvent object that contains the type of the event and associated data.

Parameters:

• callback (Callable[[DebuggerEvent], None]) – the callback to register

• name (str | bytes) – name of the callback

Returns:

an integer handle to the registered event callback

Return type:

int

remove_event_callback(index: int)[source]¶

Remove the debugger event callback from the DebuggerController

Parameters:

index (int) –

remove_ttd_bookmark(position)[source]¶

Remove a TTD bookmark by position.

Parameters:

position – TTDPosition object or string in format “sequence:step”

Returns:

True if the bookmark was found and removed

Return type:

bool

restart() → None[source]¶

Restart the target

Return type:

None

restart_and_wait() → None[source]¶

Restart a running target.

The call is blocking and only returns when the target stops again after the restart.

Return type:

None

resume_thread(tid: int) → bool[source]¶

Resumes a thread by thread id.

Parameters:

tid (int) – thread id

Return type:

bool

run_code_coverage_analysis(start_address: int, end_address: int, start_time: TTDPosition | None = None, end_time: TTDPosition | None = None) → bool[source]¶

Run code coverage analysis on a specific address range and time range.

This method is only available when debugging with TTD (Time Travel Debugging). Use the is_ttd property to check if TTD is available before calling this method.

The code coverage analysis identifies which instructions within the specified address range were executed during the specified time range. Results can be queried using the is_instruction_executed() method.

Parameters:

• start_address (int) – starting address of the range to analyze

• end_address (int) – ending address of the range to analyze

• start_time (TTDPosition | None) – starting TTD position (default: start of trace)

• end_time (TTDPosition | None) – ending TTD position (default: end of trace)

Returns:

True if analysis succeeded, False otherwise

Raises:

May raise an exception if TTD is not available

Return type:

bool

run_to(address) → bool[source]¶

Resume the target, and wait for it to break at the given address(es).

The address parameter can be either an integer, or a list of integers.

Internally, the debugger places breakpoints on these addresses, resume the target, and wait for the target to break. Then the debugger removes the added breakpoints.

The call is asynchronous and returns before the target stops.

Returns:

whether the operation is successfully requested

Return type:

bool

run_to_and_wait(address) → DebugStopReason[source]¶

Resume the target, and wait for it to break at the given address(es).

The address parameter can be either an integer, or a list of integers.

Internally, the debugger places breakpoints on these addresses, resume the target, and wait for the target to break. Then the debugger removes the added breakpoints.

The call is blocking and only returns when the target stops.

Returns:

the reason for the stop

Return type:

DebugStopReason

run_to_reverse(address) → bool[source]¶

Resume the target in reverse, and wait for it to break at the given address(es).

The address parameter can be either an integer, or a list of integers.

Internally, the debugger places breakpoints on these addresses, resumes the target in reverse, and waits for the target to break. Then the debugger removes the added breakpoints.

The call is asynchronous and returns before the target stops.

Returns:

whether the operation is successfully requested

Return type:

bool

run_to_reverse_and_wait(address) → DebugStopReason[source]¶

Resume the target in reverse, and wait for it to break at the given address(es).

The address parameter can be either an integer, or a list of integers.

Internally, the debugger places breakpoints on these addresses, resumes the target in reverse, and waits for the target to break. Then the debugger removes the added breakpoints.

The call is blocking and only returns when the target stops.

Returns:

the reason for the stop

Return type:

DebugStopReason

save_code_coverage_to_file(file_path: str) → bool[source]¶

Save code coverage results to a file.

This method requires that run_code_coverage_analysis() has been called first.

Parameters:

file_path (str) – path to the file where results should be saved

Returns:

True if save succeeded, False otherwise

Return type:

bool

set_adapter_property(name: str | bytes, value: Metadata | int | bool | str | bytes | float | List[MetadataValueType] | Tuple[MetadataValueType] | dict) → bool[source]¶

Parameters:

• name (str | bytes) –

• value (Metadata | int | bool | str | bytes | float | List[MetadataValueType] | Tuple[MetadataValueType] | dict) –

Return type:

bool

set_breakpoint_condition(address, condition: str) → bool[source]¶

Set a condition for a breakpoint

The condition is an expression that will be evaluated using Binary Ninja’s expression parser when the breakpoint is hit. If the condition evaluates to non-zero (true), the debugger stops. If it evaluates to zero (false), the debugger silently continues execution.

Example conditions:

• "rax == 0x1234" - break when RAX equals 0x1234

• "rsp + 0x20" - break when the expression is non-zero

Pass an empty string to clear the condition.

Parameters:

• address – the address of the breakpoint (int or ModuleNameAndOffset)

• condition (str) – the condition expression, or empty string to clear

Returns:

True if successful, False otherwise

Return type:

bool

set_reg_value(reg: str | bytes, value: int) → bool[source]¶

Set value of register

Parameters:

• reg (str | bytes) – the name of the register

• value (int) – new value of the register

Return type:

bool

set_ttd_position(position)[source]¶

Navigate to a specific position in the TTD trace.

Args:

position: TTDPosition object or string in format “sequence:step”

Returns:

bool: True if navigation succeeded, False otherwise

step_into(il: FunctionGraphType = FunctionGraphType.NormalFunctionGraph) → bool[source]¶

Perform a step into on the target.

When the next instruction is not a call, execute the next instruction. When the next instruction is a call, follow the call the get into the first instruction of the call.

The operation can be performed on an IL level specified by the il parameter, which then either executes the next IL instruction, or follow into the IL function. Note, the underlying operation is still performed at the disassembly level because that is the only thing a debugger understands. The high-level operations are simulated on top of the disassembly and analysis.

Some limitations are known with stepping into on IL.

The call is asynchronous and returns before the target stops.

Parameters:

il (FunctionGraphType) – optional IL level to perform the operation at

Returns:

whether the operation is successfully requested

Return type:

bool

step_into_and_wait(il: FunctionGraphType = FunctionGraphType.NormalFunctionGraph) → DebugStopReason[source]¶

Perform a step into on the target in reverse.

When the next instruction is not a call, execute the next instruction. When the next instruction is a call, follow the call the get into the first instruction of the call.

The operation can be performed on an IL level specified by the il parameter, which then either executes the next IL instruction, or follow into the IL function. Note, the underlying operation is still performed at the disassembly level because that is the only thing a debugger understands. The high-level operations are simulated on top of the disassembly and analysis.

Some limitations are known with stepping into on IL.

The call is blocking and only returns when the target stops.

Parameters:

il (FunctionGraphType) – optional IL level to perform the operation at

Returns:

the reason for the stop

Return type:

DebugStopReason

step_into_reverse(il: FunctionGraphType = FunctionGraphType.NormalFunctionGraph) → bool[source]¶

Perform a step into on the target in reverse.

When the previous instruction is not a call, step backwards. When the previous instruction is a call, follow the call into the last instruction of the function.

The operation can be performed on an IL level specified by the il parameter, which then either executes the next IL instruction, or follow into the IL function. Note, the underlying operation is still performed at the disassembly level because that is the only thing a debugger understands. The high-level operations are simulated on top of the disassembly and analysis.

Some limitations are known with stepping into on IL.

The call is asynchronous and returns before the target stops.

Parameters:

il (FunctionGraphType) – optional IL level to perform the operation at

Returns:

whether the operation is successfully requested

Return type:

bool

step_into_reverse_and_wait(il: FunctionGraphType = FunctionGraphType.NormalFunctionGraph) → DebugStopReason[source]¶

Perform a reverse step into on the target.

When the previous instruction is not a call, reverse the program to the previous state. When the previous instruction is a call, follow the call to get into the last instruction of the call.

The operation can be performed on an IL level specified by the il parameter, which then either reverses the current IL instruction, or follow into the previous IL function. Note, the underlying operation is still performed at the disassembly level because that is the only thing a debugger understands. The high-level operations are simulated on top of the disassembly and analysis.

Some limitations are known with stepping into on IL.

The call is blocking and only returns when the target stops.

Parameters:

il (FunctionGraphType) – optional IL level to perform the operation at

Returns:

the reason for the stop

Return type:

DebugStopReason

step_over(il: FunctionGraphType = FunctionGraphType.NormalFunctionGraph) → bool[source]¶

Perform a step over on the target.

When the next instruction is not a call, execute the next instruction. When the next instruction is a call, complete the execution of the function and break at next instruction.

The operation can be performed on an IL level specified by the il parameter, which then either executes the next IL instruction, or completes the IL function. Note, the underlying operation is still performed at the disassembly level because that is the only thing a debugger understands. The high-level operations are simulated on top of the disassembly and analysis.

Some limitations are known with stepping over on IL.

The call is asynchronous and returns before the target stops.

Parameters:

il (FunctionGraphType) – optional IL level to perform the operation at

Returns:

whether the operation is successfully requested

Return type:

bool

step_over_and_wait(il: FunctionGraphType = FunctionGraphType.NormalFunctionGraph) → DebugStopReason[source]¶

Perform a step over on the target.

When the next instruction is not a call, execute the next instruction. When the next instruction is a call, complete the execution of the function and break at next instruction.

The operation can be performed on an IL level specified by the il parameter, which then either executes the next IL instruction, or completes the IL function. Note, the underlying operation is still performed at the disassembly level because that is the only thing a debugger understands. The high-level operations are simulated on top of the disassembly and analysis.

Some limitations are known with stepping over on IL.

The call is blocking and only returns when the target stops.

Parameters:

il (FunctionGraphType) – optional IL level to perform the operation at

Returns:

the reason for the stop

Return type:

DebugStopReason

step_over_reverse(il: FunctionGraphType = FunctionGraphType.NormalFunctionGraph) → bool[source]¶

Perform a step over on the target in reverse.

When the previous instruction is not a call, step backwards. When the previous instruction is a call, step back over the call.

The operation can be performed on an IL level specified by the il parameter, which then either executes the next IL instruction, or completes the IL function. Note, the underlying operation is still performed at the disassembly level because that is the only thing a debugger understands. The high-level operations are simulated on top of the disassembly and analysis.

Some limitations are known with stepping over on IL.

The call is asynchronous and returns before the target stops.

Parameters:

il (FunctionGraphType) – optional IL level to perform the operation at

Returns:

whether the operation is successfully requested

Return type:

bool

step_over_reverse_and_wait(il: FunctionGraphType = FunctionGraphType.NormalFunctionGraph) → DebugStopReason[source]¶

Perform a step over on the target in reverse.

When the next instruction is not a call, execute the next instruction. When the next instruction is a call, complete the execution of the function and break at next instruction.

The operation can be performed on an IL level specified by the il parameter, which then either executes the next IL instruction, or completes the IL function. Note, the underlying operation is still performed at the disassembly level because that is the only thing a debugger understands. The high-level operations are simulated on top of the disassembly and analysis.

Some limitations are known with stepping over on IL.

The call is blocking and only returns when the target stops.

Parameters:

il (FunctionGraphType) – optional IL level to perform the operation at

Returns:

the reason for the stop

Return type:

DebugStopReason

step_return() → bool[source]¶

Perform a step return on the target.

Step return completes the execution of the current function and returns to its caller. This operation relies heavily on stack frame analysis, which is done by the DebugAdapters.

If a DebugAdapter does not support (i.e., overload) this function, a fallback handling is provided by the DebuggerController. It checks the MLIL function and put breakpoints on all returning instructions and then resume the target. By the time it breaks, the target is about to return from the current function.

This fallback behavior is slightly different from that offered by the LLDB and DbgEng adapter, which returns from the current function and break afterwards.

The call is asynchronous and returns before the target stops.

Returns:

whether the operation is successfully requested

Return type:

bool

step_return_and_wait() → DebugStopReason[source]¶

Perform a step return on the target.

Step return completes the execution of the current function and returns to its caller. This operation relies heavily on stack frame analysis, which is done by the DebugAdapters.

If a DebugAdapter does not support (i.e., overload) this function, a fallback handling is provided by the DebuggerController. It checks the MLIL function and put breakpoints on all returning instructions and then resume the target. By the time it breaks, the target is about to return from the current function.

This fallback behavior is slightly different from that offered by the LLDB and DbgEng adapter, which returns from the current function and break afterwards.

The call is blocking and only returns when the target stops.

Returns:

the reason for the stop

Return type:

DebugStopReason

step_return_reverse() → bool[source]¶

Perform a step return on the target in reverse.

Step return reverses the execution of the current function and returns to its caller. This operation relies heavily on stack frame analysis, which is done by the DebugAdapters.

If a DebugAdapter does not support (i.e., overload) this function, a fallback handling is provided by the DebuggerController. It checks the MLIL function and put breakpoints on all returning instructions and then resume the target. By the time it breaks, the target is about to return from the current function.

This fallback behavior is slightly different from that offered by the LLDB and DbgEng adapter, which returns from the current function and break afterwards.

The call is asynchronous and returns before the target stops.

Returns:

whether the operation is successfully requested

Return type:

bool

suspend_thread(tid: int) → bool[source]¶

Suspends a thread by thread id.

Parameters:

tid (int) – thread id

Return type:

bool

ttd_navigate_back()[source]¶

Navigate to the previous TTD timestamp in the position history.

Returns:

bool: True if navigation succeeded, False if there is no previous position

ttd_navigate_forward()[source]¶

Navigate to the next TTD timestamp in the position history.

Returns:

bool: True if navigation succeeded, False if there is no next position

update_ttd_bookmark(position, note='', view_address=0)[source]¶

Update an existing TTD bookmark’s note and view address.

Parameters:

• position – TTDPosition object or string in format “sequence:step”

• note – new note for the bookmark

• view_address – new view address for the bookmark

Returns:

True if the bookmark was found and updated

Return type:

bool

write_memory(address: int, buffer) → bool[source]¶

Write memory of the target.

One can also get the data BinaryView of the DebuggerController, and use ordinary write methods to write its content.

Parameters:

• address (int) – address to write to

• buffer – buffer of data to write. It can be either bytes or a DataBuffer

Returns:

True on success, False on failure.

Return type:

bool

write_stdin(data: str | bytes) → None[source]¶

Write to the stdin of the target. Only works on Linux and macOS.

Parameters:

data (str | bytes) –

Return type:

None

property active_pid: int¶

The PID of the process currently being debugged. (read-only)

This returns the PID of the currently attached or running process.

Returns:

the PID of the active process, or 0 if no process is active or the PID is unavailable

property active_thread: DebugThread¶

The active thread of the target. (read/write)

Getter:

returns the active thread of the target

Setter:

sets the active thread of the target

property adapter_type: str¶

The name for the current DebugAdapter. (read/write)

Getter:

returns the name of the current DebugAdapter

Setter:

sets the DebugAdapter to use

property breakpoints: DebugBreakpoints¶

The list of breakpoints

Returns:

a DebugBreakpoints wrapper containing all breakpoints

property can_ttd_navigate_back¶

Check if there is a previous TTD position to navigate to.

Returns:

bool: True if back navigation is possible

property can_ttd_navigate_forward¶

Check if there is a next TTD position to navigate to.

Returns:

bool: True if forward navigation is possible

property cmd_line: str¶

The command line arguments of the target. (read/write)

This can be set before launching the target to specify the command line arguments. The arguments are supplied as a single string. The string is NOT shell expanded, which means the user must properly escape it if needed.

Getter:

returns the command line arguments

Setter:

sets the command line arguments

property connected: bool¶

Whether the debugger has successfully connected to the target (read-only)

property connection_status: DebugAdapterConnectionStatus¶

Get the connection status of the debugger

property current_ttd_position¶

Get the current position in the TTD trace.

Returns:

TTDPosition: Current position, or None if not in TTD mode

property data: BinaryView¶

Get the (rebased) BinaryView of the debugger

property executable_path: str¶

The path of the executable. (read/write)

This can be set before launching the target. Be default, it is the path of the FileMetadata (bv.file.filename)

Getter:

returns the executable path

Setter:

sets the executable path

property exit_code: int¶

The exit code of the target (read-only)

This is only meaningful after the target has executed and exited.

property input_file: str¶

The input file used to create the database

This should be set before launching the target. Be default, it is the path of the FileMetadata (bv.file.filename)

Getter:

returns the input file path

Setter:

sets the input file path

property ip: int¶

The IP (instruction pointer) of the target

For x86_64, it returns the value of rip register.

For x86, it returns the value of eip register.

For armv7/aarch64, or any other architecture that is not native to BN, it returns the value of pc register.

property is_first_launch¶

property is_ttd¶

property last_ip: int¶

The IP (instruction pointer) when the target breaks last time.

property live_view: BinaryView¶

Get the live BinaryView of the debugger

Deprecated since version 4.1.5542: Debugger no longer uses the live view, Use data instead

property modules: DebugModules¶

The modules of the target

Returns:

a DebugModules wrapper containing all modules

property pid_attach: int¶

The PID to attach to. (read/write)

pid_attach is only useful for connecting to a running process using PID.

Getter:

returns the PID to attach to

Setter:

sets the PID to attach to

property processes: List[DebugProcess]¶

The processes of the target.

property regs: DebugRegisters¶

All registers of the target

Returns:

a list of DebugRegister

property remote_arch: Architecture¶

Get the architecture of the running target (read-only). This could be different from the architecture of the original binary.

property remote_host: str¶

The remote host to connect to. (read/write)

remote_host and remote_port are only useful for remote debugging.

Getter:

returns the remote host

Setter:

sets the remote host

property remote_port: int¶

The remote port to connect to. (read/write)

remote_host and remote_port are only useful for remote debugging.

Getter:

returns the remote port

Setter:

sets the remote port

property request_terminal_emulator: bool¶

Whether to run the target in a separate terminal. (read/write)

The default value is false.

This can be set before launching the target to configure whether the target should be executed in a separate terminal. On Linux and macOS, when set, the target runs in its own terminal and the DebuggerController cannot receive notification of stdout output, or write to its stdin. All input/output must be performed in the target’s console. On Windows, this option has no effect and the target always runs in its own terminal.

Getter:

returns whether to run the target in a separate terminal

Setter:

sets whether to run the target in a separate terminal

property running: bool¶

Whether the target is running (read-only)

property stack_pointer: int¶

The stack pointer of the target (read-only)

property stop_reason: DebugStopReason¶

The reason for the target to stop

This is the same value to the return value of the function that resumed the target, e.g., go()

property stop_reason_str: str¶

String description of the target stop reason

property target_status: DebugAdapterTargetStatus¶

Get the status of the target

property threads: DebugThreads¶

The threads of the target.

property ttd_bookmarks¶

Get all TTD bookmarks.

Returns:

list of TTDBookmark objects

Return type:

list[TTDBookmark]

property working_directory: str¶

The path of the target. (read/write)

This can be set before launching the target to configure a working directory. Be default, it is the path of the binaryninja executable. In the future, we will change the default working directory to the folder that the executable is in.

Getter:

returns the working directory

Setter:

sets the working directory

Bases: object

DebuggerEvent is the event object that a debugger event callback receives

• type: a DebuggerEventType that specifies the event type

• data: a DebuggerEventData that specifies the event data

__init__(type: DebuggerEventType, data: DebuggerEventData)[source]¶

Parameters:

• type (DebuggerEventType) –

• data (DebuggerEventData) –

Bases: object

DebuggerEventData is the collection of all possible data associated with the debugger events

• target_stopped_data: the data associated with a TargetStoppedEvent

• error_data: the data associated with an ErrorEvent

• absolute_address: an integer address, which is used when an absolute breakpoint is added/removed

• relative_address: a ModuleNameAndOffset, which is used when a relative breakpoint is added/removed

• exit_data: the data associated with a TargetExitedEvent

• message_data: message data, used by both StdOutMessageEvent and BackendMessageEvent

__init__(target_stopped_data: TargetStoppedEventData, error_data: ErrorEventData, absolute_address: int, relative_address: ModuleNameAndOffset, exit_data: TargetExitedEventData, message_data: StdOutMessageEventData)[source]¶

Parameters:

• target_stopped_data (TargetStoppedEventData) –

• error_data (ErrorEventData) –

• absolute_address (int) –

• relative_address (ModuleNameAndOffset) –

• exit_data (TargetExitedEventData) –

• message_data (StdOutMessageEventData) –

Bases: object

classmethod register(controller: DebuggerController, callback: Callable[[DebuggerEvent], None], name: str | bytes) → int[source]¶

Parameters:

• controller (DebuggerController) –

• callback (Callable[[DebuggerEvent], None]) –

• name (str | bytes) –

Return type:

int

classmethod remove(controller: DebuggerController, index: int) → None[source]¶

Parameters:

• controller (DebuggerController) –

• index (int) –

Return type:

None

Bases: object

ErrorEventData is the data associated with a ErrorEvent

• error: the error message

• data: extra data. Not used.

__init__(error: str, data)[source]¶

Parameters:

error (str) –

Bases: object

ModuleNameAndOffset represents an address that is relative to the start of module. It is useful when ASLR is on.

• module: the name of the module for which the address is in

• offset: the offset of the address to the start of the module

__init__(module, offset)[source]¶

Bases: object

StdOutMessageEventData is the data associated with a StdOutMessageEvent

• message: the message that the target writes to the stdout

__init__(message: str)[source]¶

Parameters:

message (str) –

Bases: object

TTDBookmark represents a saved position in a TTD trace with an optional note and view address.

• position: the TTD position (TTDPosition object)

• view_address: the address the user was viewing when the bookmark was created

• note: an optional note describing the bookmark

__init__(position: TTDPosition, note: str = '', view_address: int = 0)[source]¶

Parameters:

• position (TTDPosition) –

• note (str) –

• view_address (int) –

Bases: object

TTDCallEvent represents a function call event in a TTD trace. It has the following fields:

• event_type: type of the event (always “Call” for TTD.Calls objects)

• thread_id: OS thread ID that made the call

• unique_thread_id: unique thread ID across the trace

• function: symbolic name of the function

• function_address: function’s address in memory

• return_address: instruction to return to after the call

• return_value: return value of the function (if not void)

• has_return_value: whether the function has a return value

• parameters: list of parameters passed to the function

• time_start: TTD position when call started

• time_end: TTD position when call ended

__init__(event_type: str, thread_id: int, unique_thread_id: int, function: str, function_address: int, return_address: int, return_value: int, has_return_value: bool, parameters: List[str], time_start: TTDPosition, time_end: TTDPosition)[source]¶

Parameters:

• event_type (str) –

• thread_id (int) –

• unique_thread_id (int) –

• function (str) –

• function_address (int) –

• return_address (int) –

• return_value (int) –

• has_return_value (bool) –

• parameters (List[str]) –

• time_start (TTDPosition) –

• time_end (TTDPosition) –

Bases: object

TTDEvent represents important events that happened during a TTD trace.

Attributes:

type (int): type of event (TTDEventType enum value) position (TTDPosition): position where event occurred module (TTDModule or None): module information for ModuleLoaded/ModuleUnloaded events thread (TTDThread or None): thread information for ThreadCreated/ThreadTerminated events exception (TTDException or None): exception information for Exception events

__init__(type: int, position: TTDPosition, module=None, thread=None, exception=None)[source]¶

Parameters:

• type (int) –

• position (TTDPosition) –

Bases: object

TTD Event Type enumeration for different types of events in TTD traces. These are bitfield flags that can be combined.

ALL = 31¶

Exception = 16¶

ModuleLoaded = 4¶

ModuleUnloaded = 8¶

NONE = 0¶

ThreadCreated = 1¶

ThreadTerminated = 2¶

Bases: object

TTDException represents information about exceptions that occurred during a TTD trace.

Attributes:

type (int): type of exception (TTDExceptionType.Software or TTDExceptionType.Hardware) program_counter (int): instruction where exception was thrown code (int): exception code flags (int): exception flags record_address (int): where in memory the exception record is found position (TTDPosition): position where exception occurred

__init__(type: int, program_counter: int, code: int, flags: int, record_address: int, position: TTDPosition)[source]¶

Parameters:

• type (int) –

• program_counter (int) –

• code (int) –

• flags (int) –

• record_address (int) –

• position (TTDPosition) –

Bases: object

TTD Exception Type enumeration for different types of exceptions.

Hardware = 1¶

Software = 0¶

Bases: object

TTDMemoryEvent represents a memory access event in a TTD trace. It has the following fields:

• event_type: type of the event (e.g., “Memory”)

• thread_id: OS thread ID that performed the memory access

• unique_thread_id: unique thread ID across the trace

• time_start: TTD position when the memory access started

• time_end: TTD position when the memory access ended

• address: memory address that was accessed

• size: size of the memory access

• memory_address: actual memory address (may differ from address field)

• instruction_address: address of the instruction that performed the access

• value: value that was read/written/executed

• access_type: type of access (read/write/execute)

__init__(event_type: str, thread_id: int, unique_thread_id: int, time_start: TTDPosition, time_end: TTDPosition, address: int, size: int, memory_address: int, instruction_address: int, value: int, access_type: int)[source]¶

Parameters:

• event_type (str) –

• thread_id (int) –

• unique_thread_id (int) –

• time_start (TTDPosition) –

• time_end (TTDPosition) –

• address (int) –

• size (int) –

• memory_address (int) –

• instruction_address (int) –

• value (int) –

• access_type (int) –

Bases: object

TTDModule represents information about modules that were loaded/unloaded during a TTD trace.

Attributes:

name (str): name and path of the module address (int): address where the module was loaded size (int): size of the module in bytes checksum (int): checksum of the module timestamp (int): timestamp of the module

__init__(name: str, address: int, size: int, checksum: int, timestamp: int)[source]¶

Parameters:

• name (str) –

• address (int) –

• size (int) –

• checksum (int) –

• timestamp (int) –

Bases: object

TTDPosition represents a position in a time travel debugging trace.

It has the following fields:

• sequence: the sequence number (as hex string or int)

• step: the step number within the sequence (as hex string or int)

__init__(sequence, step)[source]¶

classmethod from_string(timestamp_str)[source]¶

Create a TTDPosition from a string in format “sequence:step” Both sequence and step can be in hex or decimal format.

Bases: object

TTDPositionRangeIndexedMemoryEvent represents a memory access event in a TTD trace with position information. This is used for memory queries filtered by both address range and time range.

• position: TTD position when the memory access occurred

• thread_id: OS thread ID that performed the memory access

• unique_thread_id: unique thread ID across the trace

• address: memory address that was accessed

• instruction_address: address of the instruction that performed the access

• size: size of the memory access in bytes

• access_type: type of access (read/write/execute)

• value: value that was read/written/executed (truncated to size)

• data: the next 8 bytes of data at the memory address (as a bytes object)

__init__(position: TTDPosition, thread_id: int, unique_thread_id: int, address: int, instruction_address: int, size: int, access_type: int, value: int, data: bytes)[source]¶

Parameters:

• position (TTDPosition) –

• thread_id (int) –

• unique_thread_id (int) –

• address (int) –

• instruction_address (int) –

• size (int) –

• access_type (int) –

• value (int) –

• data (bytes) –

Bases: object

TTDThread represents information about threads and their lifetime during a TTD trace.

Attributes:

unique_id (int): unique ID for the thread across the trace id (int): TID of the thread lifetime_start (TTDPosition): lifetime start position lifetime_end (TTDPosition): lifetime end position active_time_start (TTDPosition): active time start position active_time_end (TTDPosition): active time end position

__init__(unique_id: int, id: int, lifetime_start: TTDPosition, lifetime_end: TTDPosition, active_time_start: TTDPosition, active_time_end: TTDPosition)[source]¶

Parameters:

• unique_id (int) –

• id (int) –

• lifetime_start (TTDPosition) –

• lifetime_end (TTDPosition) –

• active_time_start (TTDPosition) –

• active_time_end (TTDPosition) –

Bases: object

TargetExitedEventData is the data associated with a TargetExitedEvent

• exit_code: the exit code of the target

__init__(exit_code: int)[source]¶

Parameters:

exit_code (int) –

Bases: object

TargetStoppedEventData is the data associated with a TargetStoppedEvent

• reason: the reason of the stop

• last_active_thread: not used

• exit_code: not used

• data: extra data. Not used.

__init__(reason: DebugStopReason, last_active_thread: int, exit_code: int, data)[source]¶

Parameters:

• reason (DebugStopReason) –

• last_active_thread (int) –

• exit_code (int) –