plutonium-dbg
A kernel-based debugger for Linux applications
Key Features • How to Use • Setup • Contributing • License
Key Features
- Stealthy debugging
- No
ptrace
- Modern kernel features
- GDB integration
How to Use
Follow the installation instructions at Setup and start your VM with the run.sh
script.
Standalone
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)
GDB
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
Setup
Dependencies
- QEMU (with KVM support)
- Python 3
- anything needed to compile the Linux kernel
Virtualization
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>
).
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 module/Makefile
to /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.
Contributing
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.
License
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)