Skip to main content
`Ctrl`+`K`

# libdebug.ptrace package

## Subpackages

- libdebug.ptrace.jumpstart package
  - Module contents

## Submodules

## libdebug.ptrace.ptrace_constants module

class libdebug.ptrace.ptrace_constants.StopEvents(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  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, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  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_handler(handler: SyscallHandler) → None

    Sets a handler for a syscall.

    Parameters:

      handler (HandledSyscall) – The syscall to set.

  unset_syscall_handler(handler: SyscallHandler) → None

    Unsets a handler for a syscall.

    Parameters:

      handler (HandledSyscall) – The syscall to unset.

  set_signal_catcher(catcher: SignalCatcher) → None

    Sets a catcher for a signal.

    Parameters:

      catcher (CaughtSignal) – The signal to set.

  unset_signal_catcher(catcher: SignalCatcher) → None

    Unset a catcher for a signal.

    Parameters:

      catcher (CaughtSignal) – The signal 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