LIKE-DBG

LIKE-DBG (LInux-KErnel-DeBuGger) aims at automating the boring steps when trying to set up a Linux kernel debugging environment. I set out to dive into kernel exploitation research and found existing solutions not usable enough. Hence, this is an attempt at making all necessary pre-steps before one can even think about diving into research as painless and fun as possible. All steps from building a kernel, running it inside an emulated environment, and attaching a debugger are transparently done inside docker containers to keep system requirements minimal. Currently, there's a dedicated docker container for every of the following steps:

Building the kernel
Creating a root file system to use with the kernel
Launching the kernel + file system as the debuggee
Attaching to the kernel as a debugger

Caveats

As this project is in its early stages, I expect things to change rapidly, while also introducing breaking changes along the way. Major points to improve on are:

Getting towards true multi-architecture support beyond x86_64 and arm64
Extend kernel builder to not only succeed in building recent™ kernels
Add android kernel support
Add (integration) tests
Elevate the debugging experience even more

Features

On the upside, despite its early stages, a couple of useful features are already present:

General:
- Minimal host system requirements due to dockerization of every step
- An easy to grasp configs/user.ini config that allows highly customizable sessions
  - Or provide different configurations for different debugging setups via the command-line!
- CTF runner that's specifically designed to handle Linux kernel exploitation challenges
  - ctf/misc that houses some nifty scripts to aid in CTFs
- Code quality measures:
  - black formatter for python code
  - flake8 linter for all python code
  - shellcheck linter for shell scripts
  - hadolint linter for the Dockerfiles
- Operating system agnostic, meaning it should run just fine on:
  - Debian/Ubuntu
  - Arch Linux/Manjaro
  - Fedora
Kernel builder:
- Multi-arch: x86_64, arm64
- Choose between gcc and clang to build the kernel
- Configuration modes:
  - generic-mode,
  - syzkaller-mode,
  - custom-mode, or
  - provide a usable kernel config
- Fine-granular version control to build from:
  - Commit hash
  - Release tag (e.g.: 5.10-rc)
  - Major-Minor-Patch (e.g.: 5.10.77)
- Ability to automatically apply patch files
- Basic ability to add custom kernel modules
Root file system builder:
- Powered by debootstrap
- Automatic generation of file system that matches the kernels architecture
- Ability to customize:
  - wanted packages in the file system
  - the Debian release version to base everything on
Debuggee:
- Powered by QEMU
- Customization of QEMU runtime options from within the configs/*.ini files.
Debugger:
- Powered by GDB (multiarch) with either
  - GEF and GEF-extras, or
  - pwndbg
- Allow users to specify GDB script in io/scripts/gdb_script to allow a scenario-tailored debugging experience

Requirements

To get started, you have to ensure to have the following requirements set up in your system:

docker
tmux
python>=3.11
poetry # https://python-poetry.org/docs/

It is recommended to not run this as the root user, e.g. for testing purposes on a VPS. It may work fine but in general I highly encourage creating a dedicated non-root user to put in the docker and sudo group!

Note: If you're using a custom TMUX config, make sure that your first pane starts at 0!

Optional

This section covers tools that are not required to run LIKE-DBG but are nice to have and assist heavily when debugging or writing an exploit.

Setup

Inside like-dbg run poetry install

Configuration

Fine-tuning the kernel debugging experience is one of the goals of this project. Currently, all tunable options are exposed in the two configuration files: configs/system.ini and configs/user.ini. Some fields are recommended to not be altered as they're mainly for development reasons. However, all the ones to customize the environment to your needs should be self-explanatory as all of them are labeled with a brief comment.

Usage

Note: On first time usage run poetry install.

Once you're set with writing/adapting a configuration, the usage depends on your scenario. The easiest way to get started, which is based on the configs/user.ini configuration is the following:

tmux -f .tmux.conf
poetry shell
# This checks out a kernel, builds it, creates a root file system and starts the debugger and debuggee eventually
./start_kgdb.py

There exist 2 users for the automatically created filesystems:

root with no password
user:user

This is intended so you can develop and exploit from either perspective easily.

Extended Usage

# If you want to try a CTF challenge where you were given a (compressed) Linux Image and a root filesystem try:
./start_kgdb.py --ctf <Image> <RootFS>

# If you want to kill the current debugging session
./start_kgdb.py -k

# If you want to provide a custom 'user.ini' for a specific debugging setup
./start_kgdb.py -c <path_to_cfg> [other_args]

# If you want to test some partial functionality of LIKE-DBG
# Stage 1: Download Kernel
# Stage 2: Stage 1 & unpack Kernel
# Stage 3: Stage 2 & build Kernel
# Stage 4: Only build a root file system
# Stage 5: Stage 3+4 & start debuggee
./start_kgdb.py -p <stage_nr>

# Update all containers
./start_kgdb.py -u

Examples

The examples subdirectory houses samples on how LIKE_DBG may aid you in specific kernel debugging tasks. Each example contains a dedicated README.md as well that contains the necessary information to reproduce the examples.

Showcase

Hacking

The python code should be quite readable, so feel free to extend the project with your own ideas. All PRs are very much welcome :)! Otherwise, feel free to create a feature-request issue or head over to the discussions page to brainstorm some cool new features!

PS: If you want to provide a logo, feel free to do so.

Badges

Extracted from project README