libdebug.debugger package

Submodules

libdebug.debugger.debugger module

class libdebug.debugger.debugger.Debugger

Bases: object

The Debugger class is the main class of libdebug. It contains all the methods needed to run and interact with the process.

post_init_(internal_debugger: InternalDebugger) → None

Do not use this constructor directly. Use the debugger function instead.

run() → None

Starts the process and waits for it to stop.

attach(pid: int) → None

Attaches to an existing process.

detach() → None

Detaches from the process.

kill() → None

Kills the process.

terminate() → None

Terminates the background thread.

The debugger object cannot be used after this method is called. This method should only be called to free up resources when the debugger object is no longer needed.

cont() → None

Continues the process.

interrupt() → None

Interrupts the process.

wait() → None

Waits for the process to stop.

maps() → list[MemoryMap]

Returns the memory maps of the process.

print_maps() → None

Prints the memory maps of the process.

breakpoint(position: int | str, hardware: bool = False, condition: str | None = None, length: int = 1, callback: None | Callable[[ThreadContext, Breakpoint], None] = None, file: str = 'default') → Breakpoint

Sets a breakpoint at the specified location.

Parameters:

• position (int | bytes) – The location of the breakpoint.

• hardware (bool, optional) – Whether the breakpoint should be hardware-assisted or purely software.

• False. (Defaults to)

• condition (str, optional) – The trigger condition for the breakpoint. Defaults to None.

• length (int, optional) – The length of the breakpoint. Only for watchpoints. Defaults to 1.

• callback (Callable[[ThreadContext, Breakpoint], None], optional) – A callback to be called when the

• None. (breakpoint is hit. Defaults to)

• file (str, optional) – The user-defined backing file to resolve the address in. Defaults to “default”

• address ((libdebug will first try to solve the address as an absolute)

• w.r.t. (then as a relative address)

• file). (the "binary" map)

watchpoint(position: int | str, condition: str = 'w', length: int = 1, callback: None | Callable[[ThreadContext, Breakpoint], None] = None, file: str = 'default') → Breakpoint

Sets a watchpoint at the specified location. Internally, watchpoints are implemented as breakpoints.

Parameters:

• position (int | bytes) – The location of the breakpoint.

• condition (str, optional) – The trigger condition for the watchpoint (either “r”, “rw” or “x”).

• "w". (Defaults to)

• length (int, optional) – The size of the word in being watched (1, 2, 4 or 8). Defaults to 1.

• callback (Callable[[ThreadContext, Breakpoint], None], optional) – A callback to be called when the

• None. (watchpoint is hit. Defaults to)

• file (str, optional) – The user-defined backing file to resolve the address in. Defaults to “default”

• address ((libdebug will first try to solve the address as an absolute)

• w.r.t. (then as a relative address)

• file). (the "binary" map)

hook_signal(signal_to_hook: int | str, callback: None | Callable[[ThreadContext, int], None] = None, hook_hijack: bool = True) → SignalHook

Hooks a signal in the target process.

Parameters:

• signal_to_hook (int | str) – The signal to hook.

• callback (Callable[[ThreadContext, int], None], optional) – A callback to be called when the signal is received. Defaults to None.

• hook_hijack (bool, optional) – Whether to execute the hook/hijack of the new signal after an hijack or not. Defaults to False.

unhook_signal(hook: SignalHook) → None

Unhooks a signal in the target process.

Parameters:

hook (SignalHook) – The signal hook to unhook.

hijack_signal(original_signal: int | str, new_signal: int | str, hook_hijack: bool = True) → None

Hijacks a signal in the target process.

Parameters:

• original_signal (int | str) – The signal to hijack.

• new_signal (int | str) – The signal to replace the original signal with.

• hook_hijack (bool, optional) – Whether to execute the hook/hijack of the new signal after the hijack or not. Defaults to True.

hook_syscall(syscall: int | str, on_enter: Callable[[ThreadContext, int], None] | None = None, on_exit: Callable[[ThreadContext, int], None] | None = None, hook_hijack: bool = True) → SyscallHook

Hooks a syscall in the target process.

Parameters:

• syscall (int | str) – The syscall name or number to hook.

• on_enter (Callable[[ThreadContext, int], None], optional) – The callback to execute when the syscall is entered. Defaults to None.

• on_exit (Callable[[ThreadContext, int], None], optional) – The callback to execute when the syscall is exited. Defaults to None.

• hook_hijack (bool, optional) – Whether the syscall after the hijack should be hooked. Defaults to True.

Returns:

The syscall hook object.

Return type:

SyscallHook

unhook_syscall(hook: SyscallHook) → None

Unhooks a syscall in the target process.

Parameters:

hook (SyscallHook) – The syscall hook to unhook.

hijack_syscall(original_syscall: int | str, new_syscall: int | str, hook_hijack: bool = True, **kwargs: int) → SyscallHook

Hijacks a syscall in the target process.

Parameters:

• original_syscall (int | str) – The syscall name or number to hijack.

• new_syscall (int | str) – The syscall name or number to replace the original syscall with.

• hook_hijack (bool, optional) – Whether the syscall after the hijack should be hooked. Defaults to True.

• **kwargs – (int, optional): The arguments to pass to the new syscall.

Returns:

The syscall hook object.

Return type:

SyscallHook

migrate_to_gdb(open_in_new_process: bool = True) → None

Migrates the current debugging session to GDB.

r() → None

Alias for the run method.

Starts the process and waits for it to stop.

c() → None

Alias for the cont method.

Continues the process.

int() → None

Alias for the interrupt method.

Interrupts the process.

w() → None

Alias for the wait method.

Waits for the process to stop.

bp(position: int | str, hardware: bool = False, condition: str | None = None, length: int = 1, callback: None | Callable[[ThreadContext, Breakpoint], None] = None, file: str = 'default') → Breakpoint

Alias for the breakpoint method.

Parameters:

• position (int | bytes) – The location of the breakpoint.

• hardware (bool, optional) – Whether the breakpoint should be hardware-assisted or purely software.

• False. (Defaults to)

• condition (str, optional) – The trigger condition for the breakpoint. Defaults to None.

• length (int, optional) – The length of the breakpoint. Only for watchpoints. Defaults to 1.

• callback (Callable[[ThreadContext, Breakpoint], None], optional) – A callback to be called when the

• None. (breakpoint is hit. Defaults to)

• file (str, optional) – The user-defined backing file to resolve the address in. Defaults to “default”

• address ((libdebug will first try to solve the address as an absolute)

• w.r.t. (then as a relative address)

• file). (the "binary" map)

wp(position: int | str, condition: str = 'w', length: int = 1, callback: None | Callable[[ThreadContext, Breakpoint], None] = None, file: str = 'default') → Breakpoint

Alias for the watchpoint method.

Sets a watchpoint at the specified location. Internally, watchpoints are implemented as breakpoints.

Parameters:

• position (int | bytes) – The location of the breakpoint.

• condition (str, optional) – The trigger condition for the watchpoint (either “r”, “rw” or “x”).

• "w". (Defaults to)

• length (int, optional) – The size of the word in being watched (1, 2, 4 or 8). Defaults to 1.

• callback (Callable[[ThreadContext, Breakpoint], None], optional) – A callback to be called when the

• None. (watchpoint is hit. Defaults to)

• file (str, optional) – The user-defined backing file to resolve the address in. Defaults to “default”

• address ((libdebug will first try to solve the address as an absolute)

• w.r.t. (then as a relative address)

• file). (the "binary" map)

property threads: list[ThreadContext]

Get the list of threads in the process.

property memory: MemoryView

Get the memory view of the process.

property mem: MemoryView

Alias for the memory property.

Get the memory view of the process.

property breakpoints: dict[int, Breakpoint]

Get the breakpoints set on the process.

property syscall_hooks: dict[int, SyscallHook]

Get the syscall hooks dictionary.

Returns:

the syscall hooks dictionary.

Return type:

dict[int, SyscallHook]

property signal_hooks: dict[int, SignalHook]

Get the signal hooks dictionary.

Returns:

the signal hooks dictionary.

Return type:

dict[int, SignalHook]

property pprint_syscalls: bool

Get the state of the pprint_syscalls flag.

Returns:

True if the debugger should pretty print syscalls, False otherwise.

Return type:

bool

pprint_syscalls_context(value: bool) → ...

A context manager to temporarily change the state of the pprint_syscalls flag.

Parameters:

value (bool) – the value to set.

Yields:

None

property syscalls_to_pprint: list[str] | None

Get the syscalls to pretty print.

Returns:

The syscalls to pretty print.

Return type:

list[str]

property syscalls_to_not_pprint: list[str] | None

Get the syscalls to not pretty print.

Returns:

The syscalls to not pretty print.

Return type:

list[str]

property signals_to_block: list[str]

Get the signals to not forward to the process.

Returns:

The signals to block.

Return type:

list[str]

libdebug.debugger.internal_debugger module

class libdebug.debugger.internal_debugger.InternalDebugger

Bases: object

A class that holds the global debugging state.

auto_interrupt_on_command: bool

A flag that indicates if the debugger should automatically interrupt the debugged process when a command is issued.

memory: MemoryView

The memory view of the debugged process.

debugging_interface: DebuggingInterface

The debugging interface used to communicate with the debugged process.

aslr_enabled: bool

A flag that indicates if ASLR is enabled or not.

autoreach_entrypoint: bool

A flag that indicates if the debugger should automatically reach the entry point of the debugged process.

argv: list[str]

The command line arguments of the debugged process.

env: dict[str, str] | None

The environment variables of the debugged process.

escape_antidebug: bool

A flag that indicates if the debugger should escape anti-debugging techniques.

breakpoints: dict[int, Breakpoint]

A dictionary of all the breakpoints set on the process. Key: the address of the breakpoint.

syscall_hooks: dict[int, SyscallHook]

A dictionary of all the syscall hooks set on the process. Key: the syscall number.

signal_hooks: dict[int, SignalHook]

A dictionary of all the signal hooks set on the process. Key: the signal number.

syscalls_to_pprint: list[int] | None

The syscalls to pretty print.

syscalls_to_not_pprint: list[int] | None

The syscalls to not pretty print.

signals_to_block: list[int]

The signals to not forward to the process.

pprint_syscalls: bool

A flag that indicates if the debugger should pretty print syscalls.

pipe_manager: PipeManager

The pipe manager used to communicate with the debugged process.

process_id: int

The PID of the debugged process.

threads: list[ThreadContext]

A list of all the threads of the debugged process.

instanced: bool = False

Whether the process was started and has not been killed yet.

resume_context: ResumeContext

Context that indicates if the debugger should resume the debugged process.

clear() → None

Reinitializes the context, so it is ready for a new run.

start_up() → None

Starts up the context.

start_processing_thread() → None

Starts the thread that will poll the traced process for state change.

run() → None

Starts the process and waits for it to stop.

attach(pid: int) → None

Attaches to an existing process.

detach() → None

Detaches from the process.

kill() → None

Kills the process.

terminate() → None

Terminates the background thread.

The debugger object cannot be used after this method is called. This method should only be called to free up resources when the debugger object is no longer needed.

cont() → None

Continues the process.

Parameters:

auto_wait (bool, optional) – Whether to automatically wait for the process to stop after continuing. Defaults to True.

interrupt() → None

Interrupts the process.

wait() → None

Waits for the process to stop.

maps() → list[MemoryMap]

Returns the memory maps of the process.

print_maps() → None

Prints the memory maps of the process.

breakpoint(position: int | str, hardware: bool = False, condition: str | None = None, length: int = 1, callback: None | Callable[[ThreadContext, Breakpoint], None] = None, file: str = 'default') → Breakpoint

Sets a breakpoint at the specified location.

Parameters:

• position (int | bytes) – The location of the breakpoint.

• hardware (bool, optional) – Whether the breakpoint should be hardware-assisted or purely software.

• False. (Defaults to)

• condition (str, optional) – The trigger condition for the breakpoint. Defaults to None.

• length (int, optional) – The length of the breakpoint. Only for watchpoints. Defaults to 1.

• callback (Callable[[ThreadContext, Breakpoint], None], optional) – A callback to be called when the

• None. (breakpoint is hit. Defaults to)

• file (str, optional) – The user-defined backing file to resolve the address in. Defaults to “default”

• address ((libdebug will first try to solve the address as an absolute)

• w.r.t. (then as a relative address)

• file). (the "binary" map)

hook_signal(signal_to_hook: int | str, callback: None | Callable[[ThreadContext, int], None] = None, hook_hijack: bool = True) → SignalHook

Hooks a signal in the target process.

Parameters:

• signal_to_hook (int | str) – The signal to hook.

• callback (Callable[[ThreadContext, int], None], optional) – A callback to be called when the signal is

• None. (received. Defaults to)

• hook_hijack (bool, optional) – Whether to execute the hook/hijack of the new signal after an hijack or not.

• False. (Defaults to)

unhook_signal(hook: SignalHook) → None

Unhooks a signal in the target process.

Parameters:

hook (SignalHook) – The signal hook to unhook.

hijack_signal(original_signal: int | str, new_signal: int | str, hook_hijack: bool = True) → None

Hijacks a signal in the target process.

Parameters:

• original_signal (int | str) – The signal to hijack.

• new_signal (int | str) – The signal to replace the original signal with.

• hook_hijack (bool, optional) – Whether to execute the hook/hijack of the new signal after the hijack or not.

• True. (Defaults to)

hook_syscall(syscall: int | str, on_enter: Callable[[ThreadContext, int], None] | None = None, on_exit: Callable[[ThreadContext, int], None] | None = None, hook_hijack: bool = True) → SyscallHook

Hooks a syscall in the target process.

Parameters:

• syscall (int | str) – The syscall name or number to hook.

• on_enter (Callable[[ThreadContext, int], None], optional) – The callback to execute when the syscall is entered. Defaults to None.

• on_exit (Callable[[ThreadContext, int], None], optional) – The callback to execute when the syscall is exited. Defaults to None.

• hook_hijack (bool, optional) – Whether the syscall after the hijack should be hooked. Defaults to True.

Returns:

The syscall hook object.

Return type:

SyscallHook

unhook_syscall(hook: SyscallHook) → None

Unhooks a syscall in the target process.

Parameters:

hook (SyscallHook) – The syscall hook to unhook.

hijack_syscall(original_syscall: int | str, new_syscall: int | str, hook_hijack: bool = True, **kwargs: int) → SyscallHook

Hijacks a syscall in the target process.

Parameters:

• original_syscall (int | str) – The syscall name or number to hijack.

• new_syscall (int | str) – The syscall name or number to replace the original syscall with.

• hook_hijack (bool, optional) – Whether the syscall after the hijack should be hooked. Defaults to True.

• **kwargs – (int, optional): The arguments to pass to the new syscall.

Returns:

The syscall hook object.

Return type:

SyscallHook

migrate_to_gdb(open_in_new_process: bool = True) → None

Migrates the current debugging session to GDB.

step(thread: ThreadContext) → None

Executes a single instruction of the process.

Parameters:

thread (ThreadContext) – The thread to step. Defaults to None.

step_until(thread: ThreadContext, position: int | str, max_steps: int = -1, file: str = 'default') → None

Executes instructions of the process until the specified location is reached.

Parameters:

• thread (ThreadContext) – The thread to step. Defaults to None.

• position (int | bytes) – The location to reach.

• max_steps (int, optional) – The maximum number of steps to execute. Defaults to -1.

• file (str, optional) – The user-defined backing file to resolve the address in. Defaults to “default”

• address ((libdebug will first try to solve the address as an absolute)

• w.r.t. (then as a relative address)

• file). (the "binary" map)

finish(thread: ThreadContext, heuristic: str = 'backtrace') → None

Continues execution until the current function returns or the process stops.

The command requires a heuristic to determine the end of the function. The available heuristics are: - backtrace: The debugger will place a breakpoint on the saved return address found on the stack and continue execution on all threads. - step-mode: The debugger will step on the specified thread until the current function returns. This will be slower.

Parameters:

• thread (ThreadContext) – The thread to finish.

• heuristic (str, optional) – The heuristic to use. Defaults to “backtrace”.

enable_pretty_print() → SyscallHook

Hooks a syscall in the target process to pretty prints its arguments and return value.

disable_pretty_print() → None

Unhooks all syscalls that are pretty printed.

insert_new_thread(thread: ThreadContext) → None

Insert a new thread in the context.

Parameters:

thread (ThreadContext) – the thread to insert.

set_thread_as_dead(thread_id: int, exit_code: int | None, exit_signal: int | None) → None

Set a thread as dead and update its exit code and exit signal.

Parameters:

• thread_id (int) – the ID of the thread to set as dead.

• exit_code (int, optional) – the exit code of the thread.

• exit_signal (int, optional) – the exit signal of the thread.

get_thread_by_id(thread_id: int) → ThreadContext

Get a thread by its ID.

Parameters:

thread_id (int) – the ID of the thread to get.

Returns:

the thread with the specified ID.

Return type:

ThreadContext

resolve_address(address: int, backing_file: str) → int

Normalizes and validates the specified address.

Parameters:

• address (int) – The address to normalize and validate.

• backing_file (str) – The backing file to resolve the address in.

Returns:

The normalized and validated address.

Return type:

int

Raises:

ValueError – If the substring backing_file is present in multiple backing files.

resolve_symbol(symbol: str, backing_file: str) → int

Resolves the address of the specified symbol.

Parameters:

• symbol (str) – The symbol to resolve.

• backing_file (str) – The backing file to resolve the symbol in.

Returns:

The address of the symbol.

Return type:

int

property running: bool

Get the state of the process.

Returns:

True if the process is running, False otherwise.

Return type:

bool

set_running() → None

Set the state of the process to running.

set_stopped() → None

Set the state of the process to stopped.

libdebug.debugger.internal_debugger_holder module

class libdebug.debugger.internal_debugger_holder.InternalDebuggerHolder(internal_debuggers: ~weakref.WeakKeyDictionary = <factory>)

Bases: object

A holder for internal debuggers.

internal_debuggers: WeakKeyDictionary

global_internal_debugger = None

internal_debugger_lock = <unlocked _thread.lock object>

libdebug.debugger.internal_debugger_instance_manager module

libdebug.debugger.internal_debugger_instance_manager.get_global_internal_debugger() → InternalDebugger

Can be used to retrieve a temporarily-global internal debugger.

libdebug.debugger.internal_debugger_instance_manager.provide_internal_debugger(reference: object) → InternalDebugger

Provide a internal debugger.

Parameters:

reference (object) – the object that needs the internal debugger.

Returns:

the internal debugger.

Return type:

InternalDebugger

libdebug.debugger.internal_debugger_instance_manager.link_to_internal_debugger(reference: object, internal_debugger: InternalDebugger) → None

Link a reference to a InternalDebugger.

Parameters:

• reference (object) – the object that needs the internal debugger.

• internal_debugger (InternalDebugger) – the internal debugger.

libdebug.debugger.internal_debugger_instance_manager.extend_internal_debugger(referrer: object) → ...

Extend the internal debugger.

Parameters:

referrer (object) – the referrer object.

Yields:

InternalDebugger – the internal debugger.

Module contents