Kernel-based debugger for Linux applications
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
clients
module
setup
.gitmodules
README.md

README.md

plutonium-dbg

A kernel-based debugger for Linux applications

Key FeaturesHow to UseSetupContributingLicense

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 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.

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.

Tested Distributions

  • Debian Stretch (4.17-rc2)
  • OpenSUSE Tumbleweed (4.18.12)

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)