Skip to main content
`Ctrl`+`K`

# libdebug package

## Subpackages

- libdebug.architectures package
  - Subpackages
    - libdebug.architectures.amd64 package
      - Submodules
      - libdebug.architectures.amd64.amd64_ptrace_hw_bp_helper module
      - libdebug.architectures.amd64.amd64_ptrace_register_holder module
      - libdebug.architectures.amd64.amd64_registers module
      - libdebug.architectures.amd64.amd64_stack_unwinder module
      - libdebug.architectures.amd64.amd64_syscall_hijacker module
      - Module contents
  - Submodules
  - libdebug.architectures.ptrace_hardware_breakpoint_manager module
    - `PtraceHardwareBreakpointManager`
      - `PtraceHardwareBreakpointManager.thread`
      - `PtraceHardwareBreakpointManager.peek_user`
      - `PtraceHardwareBreakpointManager.poke_user`
      - `PtraceHardwareBreakpointManager.breakpoint_count`
      - `PtraceHardwareBreakpointManager.install_breakpoint()`
      - `PtraceHardwareBreakpointManager.remove_breakpoint()`
      - `PtraceHardwareBreakpointManager.available_breakpoints()`
      - `PtraceHardwareBreakpointManager.is_watchpoint_hit()`
  - libdebug.architectures.ptrace_hardware_breakpoint_provider module
    - `ptrace_hardware_breakpoint_manager_provider()`
  - libdebug.architectures.ptrace_software_breakpoint_patcher module
    - `software_breakpoint_byte_size()`
  - libdebug.architectures.register_helper module
    - `register_holder_provider()`
  - libdebug.architectures.stack_unwinding_manager module
    - `StackUnwindingManager`
      - `StackUnwindingManager.unwind()`
      - `StackUnwindingManager.get_return_address()`
  - libdebug.architectures.stack_unwinding_provider module
    - `stack_unwinding_provider()`
  - libdebug.architectures.syscall_hijacking_manager module
    - `SyscallHijackingManager`
      - `SyscallHijackingManager.create_hijacker()`
  - libdebug.architectures.syscall_hijacking_provider module
    - `syscall_hijacking_provider()`
  - Module contents
- libdebug.builtin package
  - Submodules
  - libdebug.builtin.antidebug_syscall_handler module
    - `on_enter_ptrace()`
    - `on_exit_ptrace()`
  - libdebug.builtin.pretty_print_syscall_handler module
    - `pprint_on_enter()`
    - `pprint_on_exit()`
  - Module contents
- libdebug.cffi package
  - Submodules
  - libdebug.cffi.debug_sym_cffi_build module
  - libdebug.cffi.debug_sym_cffi_build_legacy module
  - libdebug.cffi.personality_cffi_build module
  - libdebug.cffi.ptrace_cffi_build module
  - Module contents
- libdebug.data package
  - Submodules
  - libdebug.data.breakpoint module
    - `Breakpoint`
      - `Breakpoint.address`
      - `Breakpoint.symbol`
      - `Breakpoint.hit_count`
      - `Breakpoint.hardware`
      - `Breakpoint.callback`
      - `Breakpoint.condition`
      - `Breakpoint.length`
      - `Breakpoint.enabled`
      - `Breakpoint.address`
      - `Breakpoint.symbol`
      - `Breakpoint.hit_count`
      - `Breakpoint.hardware`
      - `Breakpoint.callback`
      - `Breakpoint.condition`
      - `Breakpoint.length`
      - `Breakpoint.enabled`
      - `Breakpoint.enable()`
      - `Breakpoint.disable()`
      - `Breakpoint.hit_on()`
  - libdebug.data.memory_map module
    - `MemoryMap`
      - `MemoryMap.start`
      - `MemoryMap.end`
      - `MemoryMap.permissions`
      - `MemoryMap.size`
      - `MemoryMap.offset`
      - `MemoryMap.backing_file`
      - `MemoryMap.start`
      - `MemoryMap.end`
      - `MemoryMap.permissions`
      - `MemoryMap.size`
      - `MemoryMap.offset`
      - `MemoryMap.backing_file`
      - `MemoryMap.parse()`
  - libdebug.data.memory_view module
    - `MemoryView`
      - `MemoryView.getter`
      - `MemoryView.setter`
      - `MemoryView.maps_provider`
      - `MemoryView.unit_size`
      - `MemoryView.align_to`
      - `MemoryView.context`
      - `MemoryView.read()`
      - `MemoryView.write()`
      - `MemoryView.insert()`
  - libdebug.data.register_holder module
    - `RegisterHolder`
      - `RegisterHolder.apply_on_thread()`
      - `RegisterHolder.apply_on_regs()`
      - `RegisterHolder.poll()`
      - `RegisterHolder.flush()`
  - libdebug.data.registers module
    - `Registers`
  - libdebug.data.signal_catcher module
    - `SignalCatcher`
      - `SignalCatcher.signal_number`
      - `SignalCatcher.callback`
      - `SignalCatcher.recursive`
      - `SignalCatcher.enabled`
      - `SignalCatcher.hit_count`
      - `SignalCatcher.signal_number`
      - `SignalCatcher.callback`
      - `SignalCatcher.recursive`
      - `SignalCatcher.enabled`
      - `SignalCatcher.hit_count`
      - `SignalCatcher.enable()`
      - `SignalCatcher.disable()`
      - `SignalCatcher.hit_on()`
  - libdebug.data.syscall_handler module
    - `SyscallHandler`
      - `SyscallHandler.syscall_number`
      - `SyscallHandler.on_enter_user`
      - `SyscallHandler.on_exit_user`
      - `SyscallHandler.on_enter_pprint`
      - `SyscallHandler.on_exit_pprint`
      - `SyscallHandler.recursive`
      - `SyscallHandler.enabled`
      - `SyscallHandler.hit_count`
      - `SyscallHandler.syscall_number`
      - `SyscallHandler.on_enter_user`
      - `SyscallHandler.on_exit_user`
      - `SyscallHandler.on_enter_pprint`
      - `SyscallHandler.on_exit_pprint`
      - `SyscallHandler.recursive`
      - `SyscallHandler.enabled`
      - `SyscallHandler.hit_count`
      - `SyscallHandler.enable()`
      - `SyscallHandler.disable()`
      - `SyscallHandler.hit_on_enter()`
      - `SyscallHandler.hit_on_exit()`
  - Module contents
- libdebug.debugger package
  - Submodules
  - libdebug.debugger.debugger module
    - `Debugger`
      - `Debugger.post_init_()`
      - `Debugger.run()`
      - `Debugger.attach()`
      - `Debugger.detach()`
      - `Debugger.kill()`
      - `Debugger.terminate()`
      - `Debugger.cont()`
      - `Debugger.interrupt()`
      - `Debugger.wait()`
      - `Debugger.maps()`
      - `Debugger.print_maps()`
      - `Debugger.breakpoint()`
      - `Debugger.watchpoint()`
      - `Debugger.catch_signal()`
      - `Debugger.hijack_signal()`
      - `Debugger.handle_syscall()`
      - `Debugger.hijack_syscall()`
      - `Debugger.gdb()`
      - `Debugger.r()`
      - `Debugger.c()`
      - `Debugger.int()`
      - `Debugger.w()`
      - `Debugger.bp()`
      - `Debugger.wp()`
      - `Debugger.threads`
      - `Debugger.breakpoints`
      - `Debugger.handled_syscalls`
      - `Debugger.caught_signals`
      - `Debugger.pprint_syscalls`
      - `Debugger.pprint_syscalls_context()`
      - `Debugger.syscalls_to_pprint`
      - `Debugger.syscalls_to_not_pprint`
      - `Debugger.signals_to_block`
  - libdebug.debugger.internal_debugger module
    - `InternalDebugger`
      - `InternalDebugger.auto_interrupt_on_command`
      - `InternalDebugger.memory`
      - `InternalDebugger.debugging_interface`
      - `InternalDebugger.aslr_enabled`
      - `InternalDebugger.autoreach_entrypoint`
      - `InternalDebugger.argv`
      - `InternalDebugger.env`
      - `InternalDebugger.escape_antidebug`
      - `InternalDebugger.breakpoints`
      - `InternalDebugger.handled_syscalls`
      - `InternalDebugger.caught_signals`
      - `InternalDebugger.syscalls_to_pprint`
      - `InternalDebugger.syscalls_to_not_pprint`
      - `InternalDebugger.signals_to_block`
      - `InternalDebugger.pprint_syscalls`
      - `InternalDebugger.pipe_manager`
      - `InternalDebugger.process_id`
      - `InternalDebugger.threads`
      - `InternalDebugger.instanced`
      - `InternalDebugger.resume_context`
      - `InternalDebugger.clear()`
      - `InternalDebugger.start_up()`
      - `InternalDebugger.start_processing_thread()`
      - `InternalDebugger.run()`
      - `InternalDebugger.attach()`
      - `InternalDebugger.detach()`
      - `InternalDebugger.kill()`
      - `InternalDebugger.terminate()`
      - `InternalDebugger.cont()`
      - `InternalDebugger.interrupt()`
      - `InternalDebugger.wait()`
      - `InternalDebugger.maps()`
      - `InternalDebugger.print_maps()`
      - `InternalDebugger.breakpoint()`
      - `InternalDebugger.catch_signal()`
      - `InternalDebugger.hijack_signal()`
      - `InternalDebugger.handle_syscall()`
      - `InternalDebugger.hijack_syscall()`
      - `InternalDebugger.gdb()`
      - `InternalDebugger.step()`
      - `InternalDebugger.step_until()`
      - `InternalDebugger.finish()`
      - `InternalDebugger.enable_pretty_print()`
      - `InternalDebugger.disable_pretty_print()`
      - `InternalDebugger.insert_new_thread()`
      - `InternalDebugger.set_thread_as_dead()`
      - `InternalDebugger.get_thread_by_id()`
      - `InternalDebugger.resolve_address()`
      - `InternalDebugger.resolve_symbol()`
      - `InternalDebugger.running`
      - `InternalDebugger.set_running()`
      - `InternalDebugger.set_stopped()`
  - libdebug.debugger.internal_debugger_holder module
    - `InternalDebuggerHolder`
      - `InternalDebuggerHolder.internal_debuggers`
      - `InternalDebuggerHolder.global_internal_debugger`
      - `InternalDebuggerHolder.internal_debugger_lock`
  - libdebug.debugger.internal_debugger_instance_manager module
    - `get_global_internal_debugger()`
    - `provide_internal_debugger()`
    - `link_to_internal_debugger()`
    - `extend_internal_debugger()`
  - Module contents
- libdebug.interfaces package
  - Submodules
  - libdebug.interfaces.debugging_interface module
    - `DebuggingInterface`
      - `DebuggingInterface.reset()`
      - `DebuggingInterface.run()`
      - `DebuggingInterface.attach()`
      - `DebuggingInterface.detach()`
      - `DebuggingInterface.kill()`
      - `DebuggingInterface.cont()`
      - `DebuggingInterface.wait()`
      - `DebuggingInterface.migrate_to_gdb()`
      - `DebuggingInterface.migrate_from_gdb()`
      - `DebuggingInterface.step()`
      - `DebuggingInterface.step_until()`
      - `DebuggingInterface.finish()`
      - `DebuggingInterface.maps()`
      - `DebuggingInterface.set_breakpoint()`
      - `DebuggingInterface.unset_breakpoint()`
      - `DebuggingInterface.set_syscall_handler()`
      - `DebuggingInterface.unset_syscall_handler()`
      - `DebuggingInterface.set_signal_catcher()`
      - `DebuggingInterface.unset_signal_catcher()`
      - `DebuggingInterface.peek_memory()`
      - `DebuggingInterface.poke_memory()`
  - libdebug.interfaces.interface_helper module
    - `provide_debugging_interface()`
  - libdebug.interfaces.interfaces module
    - `AvailableInterfaces`
      - `AvailableInterfaces.PTRACE`
  - Module contents
- libdebug.ptrace package
  - Subpackages
    - libdebug.ptrace.jumpstart package
      - Module contents
  - Submodules
  - libdebug.ptrace.ptrace_constants module
    - `StopEvents`
      - `StopEvents.CLONE_EVENT`
      - `StopEvents.EXEC_EVENT`
      - `StopEvents.EXIT_EVENT`
      - `StopEvents.FORK_EVENT`
      - `StopEvents.VFORK_EVENT`
      - `StopEvents.VFORK_DONE_EVENT`
      - `StopEvents.SECCOMP_EVENT`
    - `Commands`
      - `Commands.PTRACE_TRACEME`
      - `Commands.PTRACE_PEEKTEXT`
      - `Commands.PTRACE_PEEKDATA`
      - `Commands.PTRACE_PEEKUSER`
      - `Commands.PTRACE_POKETEXT`
      - `Commands.PTRACE_POKEDATA`
      - `Commands.PTRACE_POKEUSER`
      - `Commands.PTRACE_CONT`
      - `Commands.PTRACE_KILL`
      - `Commands.PTRACE_SINGLESTEP`
      - `Commands.PTRACE_GETREGS`
      - `Commands.PTRACE_SETREGS`
      - `Commands.PTRACE_GETFPREGS`
      - `Commands.PTRACE_SETFPREGS`
      - `Commands.PTRACE_ATTACH`
      - `Commands.PTRACE_DETACH`
      - `Commands.PTRACE_GETFPXREGS`
      - `Commands.PTRACE_SETFPXREGS`
      - `Commands.PTRACE_SYSCALL`
      - `Commands.PTRACE_SETOPTIONS`
      - `Commands.PTRACE_GETEVENTMSG`
      - `Commands.PTRACE_GETSIGINFO`
      - `Commands.PTRACE_SETSIGINFO`
      - `Commands.PTRACE_GETREGSET`
      - `Commands.PTRACE_SETREGSET`
      - `Commands.PTRACE_SEIZE`
      - `Commands.PTRACE_INTERRUPT`
      - `Commands.PTRACE_LISTEN`
      - `Commands.PTRACE_PEEKSIGINFO`
      - `Commands.PTRACE_GETSIGMASK`
      - `Commands.PTRACE_SETSIGMASK`
      - `Commands.PTRACE_SECCOMP_GET_FILTER`
      - `Commands.PTRACE_SECCOMP_GET_METADATA`
      - `Commands.PTRACE_GET_SYSCALL_INFO`
  - libdebug.ptrace.ptrace_interface module
    - `PtraceInterface`
      - `PtraceInterface.process_id`
      - `PtraceInterface.detached`
      - `PtraceInterface.hardware_bp_helpers`
      - `PtraceInterface.reset()`
      - `PtraceInterface.run()`
      - `PtraceInterface.attach()`
      - `PtraceInterface.detach()`
      - `PtraceInterface.kill()`
      - `PtraceInterface.cont()`
      - `PtraceInterface.step()`
      - `PtraceInterface.step_until()`
      - `PtraceInterface.finish()`
      - `PtraceInterface.wait()`
      - `PtraceInterface.forward_signal()`
      - `PtraceInterface.migrate_to_gdb()`
      - `PtraceInterface.migrate_from_gdb()`
      - `PtraceInterface.register_new_thread()`
      - `PtraceInterface.unregister_thread()`
      - `PtraceInterface.set_breakpoint()`
      - `PtraceInterface.unset_breakpoint()`
      - `PtraceInterface.set_syscall_handler()`
      - `PtraceInterface.unset_syscall_handler()`
      - `PtraceInterface.set_signal_catcher()`
      - `PtraceInterface.unset_signal_catcher()`
      - `PtraceInterface.peek_memory()`
      - `PtraceInterface.poke_memory()`
      - `PtraceInterface.maps()`
  - libdebug.ptrace.ptrace_register_holder module
    - `PtraceRegisterHolder`
      - `PtraceRegisterHolder.register_file`
      - `PtraceRegisterHolder.poll()`
      - `PtraceRegisterHolder.flush()`
  - libdebug.ptrace.ptrace_status_handler module
    - `PtraceStatusHandler`
      - `PtraceStatusHandler.manage_change()`
      - `PtraceStatusHandler.check_for_new_threads()`
  - Module contents
- libdebug.state package
  - Submodules
  - libdebug.state.resume_context module
    - `ResumeContext`
      - `ResumeContext.clear()`
  - libdebug.state.thread_context module
    - `ThreadContext`
      - `ThreadContext.instruction_pointer`
      - `ThreadContext.syscall_arg0`
      - `ThreadContext.syscall_arg1`
      - `ThreadContext.syscall_arg2`
      - `ThreadContext.syscall_arg3`
      - `ThreadContext.syscall_arg4`
      - `ThreadContext.syscall_arg5`
      - `ThreadContext.syscall_number`
      - `ThreadContext.syscall_return`
      - `ThreadContext.regs`
      - `ThreadContext.set_as_dead()`
      - `ThreadContext.dead`
      - `ThreadContext.memory`
      - `ThreadContext.mem`
      - `ThreadContext.process_id`
      - `ThreadContext.pid`
      - `ThreadContext.thread_id`
      - `ThreadContext.tid`
      - `ThreadContext.running`
      - `ThreadContext.exit_code`
      - `ThreadContext.exit_signal`
      - `ThreadContext.signal`
      - `ThreadContext.backtrace()`
      - `ThreadContext.current_return_address()`
      - `ThreadContext.step()`
      - `ThreadContext.step_until()`
      - `ThreadContext.finish()`
      - `ThreadContext.si()`
      - `ThreadContext.su()`
      - `ThreadContext.fin()`
  - Module contents
- libdebug.utils package
  - Submodules
  - libdebug.utils.debugger_wrappers module
    - `change_state_function_process()`
    - `change_state_function_thread()`
    - `background_alias()`
  - libdebug.utils.debugging_utils module
    - `check_absolute_address()`
    - `normalize_and_validate_address()`
    - `resolve_symbol_in_maps()`
    - `resolve_address_in_maps()`
  - libdebug.utils.elf_utils module
    - `resolve_symbol()`
    - `resolve_address()`
    - `is_pie()`
    - `get_entry_point()`
  - libdebug.utils.gdb module
  - libdebug.utils.libcontext module
    - `LibContext`
      - `LibContext.sym_lvl`
      - `LibContext.debugger_logger`
      - `LibContext.pipe_logger`
      - `LibContext.general_logger`
      - `LibContext.arch`
      - `LibContext.terminal`
      - `LibContext.update()`
      - `LibContext.tmp()`
  - libdebug.utils.pipe_manager module
    - `PipeManager`
      - `PipeManager.timeout_default`
      - `PipeManager.close()`
      - `PipeManager.recv()`
      - `PipeManager.recverr()`
      - `PipeManager.recvuntil()`
      - `PipeManager.recverruntil()`
      - `PipeManager.recvline()`
      - `PipeManager.recverrline()`
      - `PipeManager.send()`
      - `PipeManager.sendline()`
      - `PipeManager.sendafter()`
      - `PipeManager.sendlineafter()`
  - libdebug.utils.posix_spawn module
    - `posix_spawn()`
  - libdebug.utils.print_style module
    - `PrintStyle`
      - `PrintStyle.RED`
      - `PrintStyle.BLUE`
      - `PrintStyle.GREEN`
      - `PrintStyle.BRIGHT_YELLOW`
      - `PrintStyle.YELLOW`
      - `PrintStyle.PINK`
      - `PrintStyle.CYAN`
      - `PrintStyle.BOLD`
      - `PrintStyle.UNDERLINE`
      - `PrintStyle.STRIKE`
      - `PrintStyle.DEFAULT_COLOR`
      - `PrintStyle.RESET`
  - libdebug.utils.process_utils module
    - `get_process_maps()`
    - `get_open_fds()`
    - `invalidate_process_cache()`
    - `disable_self_aslr()`
  - libdebug.utils.signal_utils module
    - `create_signal_mappings()`
    - `resolve_signal_number()`
    - `resolve_signal_name()`
    - `get_all_signal_numbers()`
  - libdebug.utils.syscall_utils module
    - `get_remote_definition_url()`
    - `fetch_remote_syscall_definition()`
    - `get_syscall_definitions()`
    - `resolve_syscall_number()`
    - `resolve_syscall_name()`
    - `resolve_syscall_arguments()`
    - `get_all_syscall_numbers()`
  - Module contents

## Submodules

## libdebug.libdebug module

libdebug.libdebug.debugger(argv: str | list[str] = [], aslr: bool = False, env: dict[str, str] | None = None, escape_antidebug: bool = False, continue_to_binary_entrypoint: bool = True, auto_interrupt_on_command: bool = False) → Debugger

  This function is used to create a new Debugger object. It returns a Debugger object.

  Parameters:

    - argv (str | list[str], optional) – The location of the binary to debug, and any additional arguments to pass to it.

    - aslr (bool, optional) – Whether to enable ASLR. Defaults to False.

    - env (dict[str, str], optional) – The environment variables to use. Defaults to the same environment of the debugging script.

    - escape_antidebug (bool) – Whether to automatically attempt to patch antidebugger detectors based on the ptrace syscall.

    - continue_to_binary_entrypoint (bool, optional) – Whether to automatically continue to the binary entrypoint. Defaults to True.

    - auto_interrupt_on_command (bool, optional) – Whether to automatically interrupt the process when a command is issued. Defaults to False.

  Returns:

    The Debugger object.

  Return type:

    Debugger

## libdebug.liblog module

class libdebug.liblog.LibLog

  Bases: `object`

  Custom logger singleton class that can be used to log messages to the console.

  debugger(message: str, *args: str, **kwargs: str) → None

    Log a message to the debugger logger.

    Parameters:

      - message (str) – the message to log.

      - *args – positional arguments to pass to the logger.

      - **kwargs – keyword arguments to pass to the logger.

  pipe(message: str, *args: str, **kwargs: str) → None

    Log a message to the pipe logger.

    Parameters:

      - message (str) – the message to log.

      - *args – positional arguments to pass to the logger.

      - **kwargs – keyword arguments to pass to the logger.

  info(message: str, *args: str, **kwargs: str) → None

    Log a info message to the general logger.

    Parameters:

      - message (str) – the message to log.

      - *args – positional arguments to pass to the logger.

      - **kwargs – keyword arguments to pass to the logger.

  warning(message: str, *args: str, **kwargs: str) → None

    Log a warning message to the general logger.

    Parameters:

      - message (str) – the message to log.

      - *args – positional arguments to pass to the logger.

      - **kwargs – keyword arguments to pass to the logger.

  error(message: str, *args: str, **kwargs: str) → None

    Log an error message to the general logger.

    Parameters:

      - message (str) – the message to log.

      - *args – positional arguments to pass to the logger.

      - **kwargs – keyword arguments to pass to the logger.

## Module contents

libdebug.debugger(argv: str | list[str] = [], aslr: bool = False, env: dict[str, str] | None = None, escape_antidebug: bool = False, continue_to_binary_entrypoint: bool = True, auto_interrupt_on_command: bool = False) → Debugger

  This function is used to create a new Debugger object. It returns a Debugger object.

  Parameters:

    - argv (str | list[str], optional) – The location of the binary to debug, and any additional arguments to pass to it.

    - aslr (bool, optional) – Whether to enable ASLR. Defaults to False.

    - env (dict[str, str], optional) – The environment variables to use. Defaults to the same environment of the debugging script.

    - escape_antidebug (bool) – Whether to automatically attempt to patch antidebugger detectors based on the ptrace syscall.

    - continue_to_binary_entrypoint (bool, optional) – Whether to automatically continue to the binary entrypoint. Defaults to True.

    - auto_interrupt_on_command (bool, optional) – Whether to automatically interrupt the process when a command is issued. Defaults to False.

  Returns:

    The Debugger object.

  Return type:

    Debugger