A kernel-based debugger for Linux applications
- Stealthy debugging
- Modern kernel features
- GDB integration
How to Use
Follow the installation instructions at Setup and start your VM with the
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 either
gdbserver.py --tcp <port> <program> or
gdbserver.py --unix <socket_name> <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):
First set the architecture you want to debug with e.g.
set architecture i386:x86_64. Once we implement the
vFile extensions, this will no longer be necessary.
Then, depending on how you started the server, connect either via TCP with
target remote localhost:1337 or through a Unix Socket with
target remote | socat UNIX:socket_name -.
Note that socat needs to be installed for the latter option.
- 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
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>).
Compilation and Installation
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.
Compilation for Host System
You can also compile plutonium-dbg for your host system by replacing the path to the kernel in
/lib/modules/$(shell uname -r)/build (just uncomment the corresponding line). 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.
On a Debian-based distro (e.g. Ubuntu), you may install the development headers for your kernel version with:
sudo apt-get install linux-headers-$(uname -r)
On a Red Hat'ish distro (e.g. Fedora, RHEL, CentOS), you may do it with:
sudo yum install kernel-devel
Unfortunately, plutonium-dbg currently does not actually build with RHEL7'ish (e.g., CentOS 7) kernel headers - pull requests to make this actually work are welcome.
- Debian Stretch (4.17-rc2)
- OpenSUSE Tumbleweed (4.18.12)
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)