Home

Awesome

LIKE-DBG

Code style: black Build Status: flake8 Build Status: shellcheck Build Status: hadolint codecov License: MIT GitHub Release

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:

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:

Features

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

Requirements

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

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:

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

img/example.png

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.