Skip to main content
`Ctrl`+`K`

# Quick Start

Welcome to libdebug! This powerful Python library can be used to debug your binary executables programmatically, providing a robust, user-friendly interface.

Debugging multithreaded applications can be a nightmare, but libdebug has you covered. Hijack, and manage signals and syscalls with a simple API.

## Looking for previous versions?

Go to https://docs.libdebug.org/archive/VERSION to find the documentation for a specific version of libdebug.

e.g, for version 0.5.0, go to https://docs.libdebug.org/archive/0.5.0

## Supported Architectures

libdebug currently supports Linux under the x86_64 architecture.

Other operating systems and architectures are not supported at this time.

## Dependencies

To install libdebug, you first need to have some dependencies that will not be automatically resolved. Depending on your distro, their names may change.

- Ubuntu
- Debian
- Arch Linux
- Fedora

    sudo apt install -y python3 python3-dev libdwarf-dev libelf-dev libiberty-dev linux-headers-generic libc6-dbg

    sudo apt install -y python3 python3-dev libdwarf-dev libelf-dev libiberty-dev linux-headers-generic libc6-dbg

    sudo pacman -S python libelf libdwarf gcc make debuginfod

    sudo dnf install -y python3 python3-devel kernel-devel binutils-devel libdwarf-devel

## Installation

Installing libdebug once you have dependencies is as simple as running the following command:

    python3 -m pip install libdebug

This will install the stable build of the library. If you don’t mind a few hiccups, you can install the latest dev build from the Github repository:

    python3 -m pip install git+https://github.com/libdebug/libdebug.git@dev

If you want to to test your installation when installing from source, we provide a suite of tests that you can run:

    cd test
    python run_suite.py

The test folder includes the Makefile that was used to build the required binaries for transparency. However, the compiled binaries may differ due to scheduling, hardware, and compiler versions. Some tests have hardcoded absolute addresses and will likely fail as a result.

## Your first script

Now that you have libdebug installed, you can start using it in your scripts. Here is a simple example of how to use libdebug to debug a binary:

    from libdebug import debugger

    d = debugger("./test")

    # Start debugging from the entry point
    d.run()

    my_breakpoint = d.breakpoint("function")

    # Continue the execution until the breakpoint is hit
    d.cont()

    # Print RAX
    print(f"RAX is {hex(d.regs.rax)}")

    # Kill the process
    d.kill()

The above script will run the binary test in the working directory and stop at the function corresponding to the symbol “function”. It will then print the value of the RAX register and kill the process.

## Conflicts with other python packages

The current version of libdebug is incompatible with Gallopsled/pwntools.

While having both installed in your python environment is not a problem, starting a process with pwntools in a libdebug scripts will cause unexpected behaviors as a result of some race conditions.

Examples of some known issues include:

- ptrace not intercepting SIGTRAP signals when process is run with pwntools.

    This behavior is described in libdebug/libdebug#48.

- Attaching libdebug to a process that was started with pwntools with `shell=True` will cause the process to attach to the shell process instead.

    This behavior is described in libdebug/libdebug#57.

Contents:

- Basic Features
  - Running the program
  - The command queue
- Register Access
- Memory Access
  - Absolute and Relative Addressing
- Control Flow Commands
  - Stepping
  - Continuing
- Detach and GDB Migration
- Graceful Termination
- Post Mortem Analysis
- Supported Architectures
- Breakpoints
  - Breakpoints
  - Watchpoints
- Syscalls
  - Handlers
  - Hijacking
- Signals
  - Signal Filtering
  - Arbitrary Signals
  - Signal Hijacking
- Multithreading
  - Control Flow Operations
  - Breakpoints
- Quality of Life
  - Automatic Evasion of Anti-Debugging Techniques
  - Syscall Trace Pretty Print
  - Symbol Resolution
- Logging
  - Debugger Logging
  - Pipe Logging
  - The best of both worlds
  - Temporary Logging
- Code Examples
  - CyberChallenge.IT 2024 - Workshop
  - DEFCON Quals 2023 - nlinks

Contents:

- libdebug package
  - Subpackages
  - Submodules
  - libdebug.libdebug module
  - libdebug.liblog module
  - Module contents

# Indices and tables

- Index

- Module Index

- Search Page