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.DebugRegister(...)

DebugRegister represents a register in 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 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 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: binaryninja.binaryview.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 (binaryninja.binaryview.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

Returns

attach(pid: int) bool[source]

Attach to a running process by its PID

Parameters

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

Returns

Return type

bool

connect() None[source]

Connect to a remote target.

Returns

Return type

None

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

Returns

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.

Returns

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 asddress it.

Parameters

command (str) –

Returns

Return type

str

frames_of_thread(tid: int) List[binaryninja.debugger.debuggercontroller.DebugFrame][source]

Get the stack frames of the thread specified by tid

Parameters

tid (int) –

Returns

list of stack frames

Return type

List[binaryninja.debugger.debuggercontroller.DebugFrame]

get_reg_value(reg: str) int[source]

Get the value of one register by its name

Parameters

reg (str) – the name of the register

Returns

Return type

int

go() binaryninja.debugger.debugger_enums.DebugStopReason[source]

Resume the target.

The call is blocking and only returns when the target stops. :return: the reason for the stop

Return type

binaryninja.debugger.debugger_enums.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

Returns

Return type

bool

launch() bool[source]

Launch the target

Returns

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:

Return type

None

pause() None[source]

Pause a running target

Returns

Return type

None

quit() None[source]

Terminate the target

Returns

Return type

None

read_memory(address: int, size: int) binaryninja.databuffer.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

binaryninja.databuffer.DataBuffer

register_event_callback(callback: Callable[[binaryninja.debugger.debuggercontroller.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[[binaryninja.debugger.debuggercontroller.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) –

Returns

restart() None[source]

Restart the target

Returns

Return type

None

run_to(address) binaryninja.debugger.debugger_enums.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

binaryninja.debugger.debugger_enums.DebugStopReason

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

Returns

Return type

bool

step_into(il: binaryninja.enums.FunctionGraphType = FunctionGraphType.NormalFunctionGraph) binaryninja.debugger.debugger_enums.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 (binaryninja.enums.FunctionGraphType) – optional IL level to perform the operation at.

Returns

the reason for the stop

Return type

binaryninja.debugger.debugger_enums.DebugStopReason

step_over(il: binaryninja.enums.FunctionGraphType = FunctionGraphType.NormalFunctionGraph) binaryninja.debugger.debugger_enums.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 (binaryninja.enums.FunctionGraphType) – optional IL level to perform the operation at.

Returns

the reason for the stop

Return type

binaryninja.debugger.debugger_enums.DebugStopReason

step_return() binaryninja.debugger.debugger_enums.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

binaryninja.debugger.debugger_enums.DebugStopReason

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) –

Returns

Return type

None

property active_thread: binaryninja.debugger.debuggercontroller.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[binaryninja.debugger.debuggercontroller.DebugBreakpoint]

The list of breakpoints

Returns

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: binaryninja.debugger.debugger_enums.DebugAdapterConnectionStatus

Get the connection status of the debugger

Returns

property data: binaryninja.binaryview.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.

Returns

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.

Returns

property last_ip: int

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

Returns

property live_view: binaryninja.binaryview.BinaryView

Get the live BinaryView of the debugger

property modules: List[binaryninja.debugger.debuggercontroller.DebugModule]

The modules of the target

Returns

a list of DebugModule

property regs: List[binaryninja.debugger.debuggercontroller.DebugRegister]

All registers of the target

Returns

a list of DebugRegister

property remote_arch: binaryninja.architecture.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: binaryninja.debugger.debugger_enums.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() :return:

property stop_reason_str: str

String description of the target stop reason

Returns

property target_status: binaryninja.debugger.debugger_enums.DebugAdapterTargetStatus

Get the status of the target

Returns

property threads: List[binaryninja.debugger.debuggercontroller.DebugThread]

The threads of the target.

Returns

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: binaryninja.debugger.debugger_enums.DebuggerEventType, data: binaryninja.debugger.debuggercontroller.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: binaryninja.debugger.debuggercontroller.TargetStoppedEventData, error_data: binaryninja.debugger.debuggercontroller.ErrorEventData, absolute_address: int, relative_address: binaryninja.debugger.debuggercontroller.ModuleNameAndOffset, exit_data: binaryninja.debugger.debuggercontroller.TargetExitedEventData, message_data: binaryninja.debugger.debuggercontroller.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: binaryninja.debugger.debuggercontroller.DebuggerController, callback: Callable[[binaryninja.debugger.debuggercontroller.DebuggerEvent], None]) int[source]
Parameters
Return type

int

classmethod remove(controller: binaryninja.debugger.debuggercontroller.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: binaryninja.debugger.debugger_enums.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