Key Features • How to Use • Setup • Contributing • License

• Stealthy debugging
• No ptrace
• Modern kernel features
• GDB integration

Follow the installation instructions at Setup and start your VM with the run.sh script.

You can load the kernel module using insmod plutonium-dbg.ko. Once the module is loaded, you can communicate with the kernel module over IOCTL on /dev/debugging. When you are done with debugging, use rmmod plutonium-dbg to unload the module.

To enable easier communication with the kernel module in Python, the plutonium_dbg.py module (in clients) abstracts the IOCTL calls and constants used:

from plutonium_dbg import debugger
dbg = debugger()

# Suspend target thread
dbg.suspend_thread(pid)

# Set breakpoint
dbg.install_breakpoint(pid, address)

# Continue thread
dbg.continue_thread(pid)

While the kernel module is loaded, you can use our GDB remote server to interact with plutonium-dbg through a GDB client. Simply start the program by launching gdbserver.py <program>.

To connect to a GDB server running on the VM, use the following commands from your host GDB (this allows you to keep any of your custom settings, including plugins such as pwndbg):

set target-architecture i386:x86_64
target remote localhost:1337

• QEMU (with KVM support)
• Python 3
• anything needed to compile the Linux kernel

We provide a QEMU-based VM system for running plutonium-dbg. First, check out a Linux kernel version of your choice (or clone the repository with git clone --recursive to automatically obtain the latest kernel sources). Then, build the kernel by running setup/build-kernel.sh.

Then, you can set up a Debian VM using setup/build-vm.sh <debian release> <target folder>.

You can start a VM by running the run.sh script in the VM folder. Each VM is accessible locally over SSH; we include helper scripts for SSH (ssh.sh) and remote copying over SCP (scp.sh <source files...> <destination>).

Compile the kernel module by running make in the module folder, then copy the plutonium-dbg.ko file and any of the Python scripts you wish to use to your target machine.

You can also compile plutonium-dbg for your host system by replacing the path to the kernel in module/Makefile to /lib/modules/$(shell uname -r)/build. This requires the development headers for your kernel version, but allows you to avoid using QEMU. Note that plutonium-dbg is not yet stable; do not do this outside of a virtual machine unless you are happy to accidentally crash your system.

Contributions to plutonium-dbg are always welcome! If you encounter a bug or have a feature request, please open an issue. Feel free to create a pull request for your improvements.

plutonium-dbg, including the GDB server, is released under the GPLv2 (or, at your choice, any later version).

^{© 2018 Tobias Holl (@TobiasHoll), Philipp Klocke (@KillPinguin)}