libdebug.ptrace package

Subpackages

• libdebug.ptrace.jumpstart package
  • Module contents

Submodules

libdebug.ptrace.ptrace_constants module

class libdebug.ptrace.ptrace_constants.StopEvents(value)

Bases: IntEnum

An enumeration of the stop events that ptrace can return.

CLONE_EVENT = 773

EXEC_EVENT = 1029

EXIT_EVENT = 1541

FORK_EVENT = 261

VFORK_EVENT = 517

VFORK_DONE_EVENT = 1285

SECCOMP_EVENT = 1797

class libdebug.ptrace.ptrace_constants.Commands(value)

Bases: IntEnum

An enumeration of the available ptrace commands.

PTRACE_TRACEME = 0

PTRACE_PEEKTEXT = 1

PTRACE_PEEKDATA = 2

PTRACE_PEEKUSER = 3

PTRACE_POKETEXT = 4

PTRACE_POKEDATA = 5

PTRACE_POKEUSER = 6

PTRACE_CONT = 7

PTRACE_KILL = 8

PTRACE_SINGLESTEP = 9

PTRACE_GETREGS = 12

PTRACE_SETREGS = 13

PTRACE_GETFPREGS = 14

PTRACE_SETFPREGS = 15

PTRACE_ATTACH = 16

PTRACE_DETACH = 17

PTRACE_GETFPXREGS = 18

PTRACE_SETFPXREGS = 19

PTRACE_SYSCALL = 24

PTRACE_SETOPTIONS = 16896

PTRACE_GETEVENTMSG = 16897

PTRACE_GETSIGINFO = 16898

PTRACE_SETSIGINFO = 16899

PTRACE_GETREGSET = 16900

PTRACE_SETREGSET = 16901

PTRACE_SEIZE = 16902

PTRACE_INTERRUPT = 16903

PTRACE_LISTEN = 16904

PTRACE_PEEKSIGINFO = 16905

PTRACE_GETSIGMASK = 16906

PTRACE_SETSIGMASK = 16907

PTRACE_SECCOMP_GET_FILTER = 16908

PTRACE_SECCOMP_GET_METADATA = 16909

PTRACE_GET_SYSCALL_INFO = 16910

libdebug.ptrace.ptrace_interface module

class libdebug.ptrace.ptrace_interface.PtraceInterface

Bases: DebuggingInterface

The interface used by _InternalDebugger to communicate with the ptrace debugging backend.

process_id: int | None

The process ID of the debugged process.

detached: bool

Whether the process was detached or not.

hardware_bp_helpers: dict[int, PtraceHardwareBreakpointManager]

The hardware breakpoint managers (one for each thread).

reset() → None

Resets the state of the interface.

run() → None

Runs the specified process.

attach(pid: int) → None

Attaches to the specified process.

Parameters:

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

detach() → None

Detaches from the process.

kill() → None

Instantly terminates the process.

cont() → None

Continues the execution of the process.

step(thread: ThreadContext) → None

Executes a single instruction of the process.

Parameters:

thread (ThreadContext) – The thread to step.

step_until(thread: ThreadContext, address: int, max_steps: int) → None

Executes instructions of the specified thread until the specified address is reached.

Parameters:

• thread (ThreadContext) – The thread to step.

• address (int) – The address to reach.

• max_steps (int) – The maximum number of steps to execute.

finish(thread: ThreadContext, heuristic: str) → None

Continues execution until the current function returns.

Parameters:

• thread (ThreadContext) – The thread to step.

• heuristic (str) – The heuristic to use.

wait() → None

Waits for the process to stop. Returns True if the wait has to be repeated.

forward_signal() → None

Set the signals to forward to the threads.

migrate_to_gdb() → None

Migrates the current process to GDB.

migrate_from_gdb() → None

Migrates the current process from GDB.

register_new_thread(new_thread_id: int) → None

Registers a new thread.

Parameters:

new_thread_id (int) – The new thread ID.

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

Unregisters a thread.

Parameters:

• thread_id (int) – The thread ID.

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

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

set_breakpoint(bp: Breakpoint, insert: bool = True) → None

Sets a breakpoint at the specified address.

Parameters:

• bp (Breakpoint) – The breakpoint to set.

• insert (bool) – Whether the breakpoint has to be inserted or just enabled.

unset_breakpoint(bp: Breakpoint, delete: bool = True) → None

Restores the breakpoint at the specified address.

Parameters:

• bp (Breakpoint) – The breakpoint to unset.

• delete (bool) – Whether the breakpoint has to be deleted or just disabled.

set_syscall_hook(hook: SyscallHook) → None

Sets a syscall hook.

Parameters:

hook (SyscallHook) – The syscall hook to set.

unset_syscall_hook(hook: SyscallHook) → None

Unsets a syscall hook.

Parameters:

hook (SyscallHook) – The syscall hook to unset.

set_signal_hook(hook: SignalHook) → None

Sets a signal hook.

Parameters:

hook (SignalHook) – The signal hook to set.

unset_signal_hook(hook: SignalHook) → None

Unsets a signal hook.

Parameters:

hook (SignalHook) – The signal hook to unset.

peek_memory(address: int) → int

Reads the memory at the specified address.

poke_memory(address: int, value: int) → None

Writes the memory at the specified address.

maps() → list[MemoryMap]

Returns the memory maps of the process.

libdebug.ptrace.ptrace_register_holder module

class libdebug.ptrace.ptrace_register_holder.PtraceRegisterHolder(register_file: object)

Bases: RegisterHolder

An abstract class that holds the state of the registers of a process, providing setters and getters for them.

Intended for use with the Ptrace debugging backend.

register_file: object

The register file of the target process, as returned by ptrace.

poll(target: ThreadContext) → None

Poll the register values from the specified target.

flush(source: ThreadContext) → None

Flush the register values from the specified source.

libdebug.ptrace.ptrace_status_handler module

class libdebug.ptrace.ptrace_status_handler.PtraceStatusHandler

Bases: object

This class handles the states return by the waitpid calls on the debugger process.

manage_change(result: list[tuple]) → None

Manage the result of the waitpid and handle the changes.

check_for_new_threads(pid: int) → None

Check for new threads in the process and register them.

Module contents