debuggercontroller module

binaryninja.debugger.debuggercontroller.DebugBreakpoint(...)

DebugBreakpoint represents a breakpoint in the target.

binaryninja.debugger.debuggercontroller.DebugFrame(...)

DebugFrame represents a frame in the stack trace.

binaryninja.debugger.debuggercontroller.DebugModule(...)

DebugModule represents a module in the target.

binaryninja.debugger.debuggercontroller.DebugProcess(...)

DebugProcess represents a process in the target.

binaryninja.debugger.debuggercontroller.DebugRegister(...)

DebugRegister represents a register in the target.

binaryninja.debugger.debuggercontroller.DebugRegisters(handle)

DebugRegisters represents all registers of the target.

binaryninja.debugger.debuggercontroller.DebugThread(...)

DebugThread represents a thread in the target.

binaryninja.debugger.debuggercontroller.DebuggerController(bv)

The DebuggerController object is the core of the debugger.

binaryninja.debugger.debuggercontroller.DebuggerEvent(...)

DebuggerEvent is the event object that a debugger event callback receives

binaryninja.debugger.debuggercontroller.DebuggerEventData(...)

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

binaryninja.debugger.debuggercontroller.DebuggerEventWrapper()

binaryninja.debugger.debuggercontroller.ErrorEventData(...)

ErrorEventData is the data associated with a ErrorEvent

binaryninja.debugger.debuggercontroller.ModuleNameAndOffset(...)

ModuleNameAndOffset represents an address that is relative to the start of module.

binaryninja.debugger.debuggercontroller.StdOutMessageEventData(message)

StdOutMessageEventData is the data associated with a StdOutMessageEvent

binaryninja.debugger.debuggercontroller.TargetExitedEventData(...)

TargetExitedEventData is the data associated with a TargetExitedEvent

binaryninja.debugger.debuggercontroller.TargetStoppedEventData(...)

TargetStoppedEventData is the data associated with a TargetStoppedEvent

class DebugBreakpoint(module, offset, address, enabled)[source]

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: not used

class DebugFrame(index, pc, sp, fp, func_name, func_start, module)[source]

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

class DebugModule(name, short_name, address, size, loaded)[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

static is_same_base_module(module1: str, module2: str) bool[source]
Parameters
  • module1 (str) –

  • module2 (str) –

Return type

bool

class DebugProcess(pid, name)[source]

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

class DebugRegister(name, value, width, index, hint)[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

class DebugRegisters(handle)[source]

Bases: object

DebugRegisters represents all registers of the target.

class DebugThread(tid, rip)[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.

class DebuggerController(bv: BinaryView)[source]

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 = BinaryViewType.get_view_of_file("test/binaries/helloworld")
>>> dbg = DebuggerController(bv)
>>> dbg.launch()
True

When the launch() returns True, it means the debugger has launched the target successfully. The target breaks at the entry point of the binary. Now we can perform other control operations on it, e.g., resume the target by calling go().

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

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

All target control funciotns, e.g., go(), step_into(), etc, are blocking. They will not return until the target breaks. In the future, we will switch to an asyunchrounous communication model where these functions return before the operation is performed.

For each insteance of DebuggerController, there are two BinaryViews associated with it. The first one is the original BinaryView that gets rebased to the proper offset according to the target’s actual base. The second is a “live” BinaryView that represents the entire memory space of the target process. They can be accessed by data and live_view, respectively.

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

attach(pid: int) bool[source]

Attach to a running process by its PID

Parameters

pid (int) – the PID of the process to attach to

Return type

bool

connect() None[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

None

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

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

disconnect_from_debug_server() None[source]

` Disconnect from a debug server.

Return type

None

execute_backend_command(command: str) str[source]

Execute a backend command and get the output

For LLDB adapter (on Linux and macOS), 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 (on Windows), any Windbg commands can be executed. However, nothing will be returned. This is because the backend processes the command asynchronously. By the time it returns, the commands are not executed yet. However, the output are still printed to the Debugger console in the global area.

Note, the user should never run any command that resumes the target (either running or stepping). It will cause the UI to de-synchronize and even hang. This is a known limitation, and we will try to address it.

Parameters

command (str) –

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) Union[Metadata, int, bool, str, bytes, float, List[MetadataValueType], Tuple[MetadataValueType], dict][source]
Parameters

name (str) –

Return type

Union[Metadata, int, bool, str, bytes, float, List[MetadataValueType], Tuple[MetadataValueType], dict]

get_reg_value(reg: str) int[source]

Get the value of one register by its name

Parameters

reg (str) – the name of the register

Return type

int

go() bool[source]

Resume the target.

The call is asynchronous and returns before the target stops.

Returns

the reason for the stop

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

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

launch() bool[source]

Launch the target

Return type

bool

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

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

register_event_callback(callback: Callable[[DebuggerEvent], None]) 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]) –

Returns

an integer handle to the registered event callback

Return type

int

remove_event_callback(index: int)[source]

Remove the debuggeer event callback from the DebuggerController

Parameters

index (int) –

restart() None[source]

Restart the target

Return type

None

resume_thread(tid: int) bool[source]

Resumes a thread by thread id.

Parameters

tid (int) – thread id

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 breeakpoints 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.

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 breeakpoints 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.

Return type

DebugStopReason

set_adapter_property(name: str, value: Union[Metadata, int, bool, str, bytes, float, List[MetadataValueType], Tuple[MetadataValueType], dict]) bool[source]
Parameters
Return type

bool

set_reg_value(reg: str, value: int) bool[source]

Set value of register

Parameters
  • reg (str) – the name of the register

  • value (int) – new value of the register

Return type

bool

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

the reason for the stop

Return type

bool

step_into_and_wait(il: FunctionGraphType = FunctionGraphType.NormalFunctionGraph) DebugStopReason[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 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

the reason for the stop

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

the reason for the stop

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

suspend_thread(tid: int) bool[source]

Suspends a thread by thread id.

Parameters

tid (int) – thread id

Return type

bool

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

Write memory of the target.

One can also get the live_view 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) None[source]

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

Parameters

data (str) –

Return type

None

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 fo the current DebugAdapter. (read/write)

Getter

returns the name of the current DebugAdapter

Setter

sets the DebugAdapter to use

property breakpoints: List[DebugBreakpoint]

The list of breakpoints

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 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 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 last_ip: int

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

property live_view: BinaryView

Get the live BinaryView of the debugger

property modules: List[DebugModule]

The modules of the target

Returns

a list of DebugModule

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: List[DebugThread]

The threads of the target.

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 workding directory to the folder that the executable is in.

Getter

returns the working directory

Setter

sets the working directory

class DebuggerEvent(type: DebuggerEventType, data: DebuggerEventData)[source]

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

Parameters
class DebuggerEventData(target_stopped_data: TargetStoppedEventData, error_data: ErrorEventData, absolute_address: int, relative_address: ModuleNameAndOffset, exit_data: TargetExitedEventData, message_data: StdOutMessageEventData)[source]

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

Parameters
class DebuggerEventWrapper[source]

Bases: object

classmethod register(controller: DebuggerController, callback: Callable[[DebuggerEvent], None]) int[source]
Parameters
Return type

int

classmethod remove(controller: DebuggerController, index: int) None[source]
Parameters
Return type

None

class ErrorEventData(error: str, data)[source]

Bases: object

ErrorEventData is the data associated with a ErrorEvent

  • error: the error message

  • data: extra data. Not used.

Parameters

error (str) –

class ModuleNameAndOffset(module, offset)[source]

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

class StdOutMessageEventData(message: str)[source]

Bases: object

StdOutMessageEventData is the data associated with a StdOutMessageEvent

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

Parameters

message (str) –

class TargetExitedEventData(exit_code: int)[source]

Bases: object

TargetExitedEventData is the data associated with a TargetExitedEvent

  • exit_code: the exit code of the target

Parameters

exit_code (int) –

class TargetStoppedEventData(reason: DebugStopReason, last_active_thread: int, exit_code: int, data)[source]

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.

Parameters