## https://sploitus.com/exploit?id=3F7376C1-CE9F-5F14-9701-5E3C1C613D73
# Kernel-Dojo Lab
An interactive practice environment for the [Kernel-Exploit-Dojo](https://github.com/mito753/Kernel-Exploit-Dojo) challenge archive. Pick any of the 112+ Linux kernel CTF challenges, launch a QEMU lab with the vulnerable kernel, and get a Socratic AI coach that knows the source code and guides you through the exploit โ without just handing you the answer.
---
## How it works
```
You
โ
โโ cli.py list / info Browse challenges
โ
โโ cli.py select Extract archive โ patch run.sh โ launch QEMU
โ (your work/ folder appears at /exploit inside the VM)
โ
โโ cli.py coach Load source code + technique docs โ start AI chat
```
The three main components:
| File | Role |
|---|---|
| `indexer.py` | Crawls the repo, parses the README challenge table, inspects archives, writes `challenges_index.json` |
| `lab_manager.py` | Extracts the distribution archive, patches `run.sh` for work-folder sharing, launches QEMU |
| `context_builder.py` | Reads source files and technique docs, builds the system prompt for the coach |
| `coach.py` | Streaming AI chat loop (Anthropic Claude or Ollama) |
| `cli.py` | Single entry point that ties everything together |
---
## Setup
```bash
# 1. Install dependencies
pip install -r requirements.txt
# 2. Clone the challenge archive this tool wraps (NOT included in this repo)
git clone https://github.com/mito753/Kernel-Exploit-Dojo.git
# Recommended: fetch the full challenge binaries (several GB, needs git-lfs).
# Without this, only the challenges already shipped with real files are launchable.
# cd Kernel-Exploit-Dojo && git lfs pull && cd ..
# 3. Configure
cp .env.example .env
# Edit .env โ add at least one LLM key (see Configuration section below)
# 4. Build the challenge index (fast, no API key needed)
python cli.py index
# 5. Browse challenges
python cli.py list
```
> **Note:** the `Kernel-Exploit-Dojo/` repo is intentionally *not* vendored here
> (it's 2.2 GB with its own git history and Git LFS binaries). It's a prerequisite
> โ clone it to `./Kernel-Exploit-Dojo` as shown above, or point `DOJO_REPO_PATH`
> in `.env` at an existing clone.
**QEMU is required to run labs.** Install it before using `cli.py select`:
- macOS: `brew install qemu`
- Debian/Ubuntu: `sudo apt install qemu-system-x86`
---
## Usage
### Browse challenges
```bash
python cli.py list # only challenges that can launch a lab now
python cli.py list --all # all 112, including not-yet-launchable ones
python cli.py list --filter uaf # filter by vuln type
python cli.py list --filter 2024 # filter by year
python cli.py list --filter modprobe # filter by technique
python cli.py list --filter easy # filter by difficulty
```
By default `list` shows only the challenges whose files are fully present locally โ
the archive opens and contains a `run.sh`, kernel, and rootfs (19 out of 112 on a
fresh clone). The rest are hidden because they're un-pulled Git LFS archives,
unsupported `.tar.zst` bundles, or online-only CTFs with no downloadable files.
Run `git lfs pull` in the Dojo repo (see Setup) to unlock most of them, then
re-run `python cli.py index`. See [`TODO.md`](./TODO.md) for the full breakdown.
### Inspect a challenge
```bash
python cli.py info welkerme
```
Shows: difficulty, bug/vuln type, exploitation primitive, final technique, technique categories, protections, author, points, solves, archive status.
### Launch a lab
```bash
python cli.py select welkerme # normal launch
python cli.py select welkerme --debug # adds GDB on port 12345
python cli.py select welkerme --no-virtfs # skip 9p work-folder patching
```
On first launch for a challenge, the distribution archive is extracted to `cache/`. Subsequent launches reuse the cached extraction.
**Work folder sharing:** The lab patches `run.sh` to share your local `work/` folder into the VM via QEMU's 9p virtfs. Inside the VM, mount it with:
```
mkdir -p /exploit && mount -t 9p -o trans=virtio exploit /exploit
```
If the kernel doesn't have `CONFIG_9P_FS` (older CTF kernels), the mount will fail โ you can still write exploit code locally and copy it in via the QEMU console.
**Exiting QEMU:** press `Ctrl-A X`.
### Start the AI coach
```bash
python cli.py coach welkerme # basic session
python cli.py coach welkerme --writeup # include writeup hints in context
python cli.py coach welkerme --model claude-opus-4-8 # override LLM model
python cli.py coach welkerme --deep # deep learning mode
```
The coach is pre-loaded with the challenge's kernel module source, exploitation technique documentation, and security mitigations. It guides you with questions and hints rather than dumping the solution. Built-in commands during a session:
| Command | What it does |
|---|---|
| `/hint` | Ask for a small, concrete nudge without spoiling the solution |
| `/source` | Print the kernel module source code |
| `/solution` | Explicitly request the full exploit walkthrough |
| `/deepdive` | In-depth explanation of the kernel concept or subsystem currently in focus |
| `/prereqs` | List the background knowledge needed before attempting this challenge |
| `exit` / `quit` | End the session |
**`--deep` mode:** Changes the coach's default posture for the whole session โ it proactively draws real-world parallels, explains the 'why' behind kernel design decisions, and connects exploit techniques to how production systems defend against them. Without `--deep`, the coach stays tightly scoped to CTF guidance unless you explicitly invoke `/deepdive` or `/prereqs`.
### Rebuild the index
```bash
python cli.py index # parse repo and regenerate challenges_index.json
```
Run this after pulling updates to the Kernel-Exploit-Dojo repo. The index is built entirely from the repo's README tables โ no API key or LLM needed.
---
## Configuration (`.env`)
Copy `.env.example` to `.env` and fill in at least one LLM backend. Anthropic is used if `ANTHROPIC_API_KEY` is set; Ollama is used as fallback.
| Variable | Default | Description |
|---|---|---|
| `DOJO_REPO_PATH` | `./Kernel-Exploit-Dojo` | Path to the cloned Kernel-Exploit-Dojo repo |
| `CACHE_DIR` | `./cache` | Where challenge archives are extracted |
| `WORK_DIR` | `./work` | Local folder shared into the VM at `/exploit` |
| `ANTHROPIC_API_KEY` | โ | Your Anthropic API key |
| `ANTHROPIC_MODEL` | `claude-sonnet-4-6` | Claude model to use for the coach |
| `OLLAMA_MODEL` | โ | Ollama model name (e.g. `deepseek-r1:14b`) |
| `OLLAMA_HOST` | `http://localhost:11434` | Ollama server address |
---
## Directory structure
```
Kernel-Dojo/
โโโ Kernel-Exploit-Dojo/ โ the cloned challenge repo
โโโ cache/ โ extracted challenge archives (auto-created)
โโโ work/ โ your exploit workspace, shared into VMs
โโโ challenges_index.json โ generated by cli.py index
โโโ cli.py โ main entry point
โโโ indexer.py โ repo crawler and index builder
โโโ lab_manager.py โ QEMU launcher
โโโ context_builder.py โ LLM context assembler
โโโ coach.py โ AI chat loop
โโโ requirements.txt
โโโ .env โ your config (not committed)
```
---
## Where to start
**welkerme** (CakeCTF 2022) is the intended entry point โ Very-Easy difficulty, no protections, the kernel module literally lets you call any function pointer as kernel code. Good first challenge to verify the whole toolchain works.
```bash
python cli.py info welkerme
python cli.py select welkerme # terminal 1: QEMU shell
python cli.py coach welkerme # terminal 2: AI coach
```
---
## Credits & License
This is a practice harness built **around** the
[Kernel-Exploit-Dojo](https://github.com/mito753/Kernel-Exploit-Dojo) challenge
archive by [@mito753](https://github.com/mito753). All challenge content โ kernel
modules, images, writeups, and the README/TECHNIQUES tables this tool parses โ is
theirs and is **not redistributed here**; you clone it yourself during setup. Please
refer to that repository for the challenge authors and their respective licenses.
The wrapper code in this repo (`cli.py`, `indexer.py`, `lab_manager.py`,
`context_builder.py`, `coach.py`) is the original work of this project. No license
file is included yet โ add one (e.g. MIT) before sharing if you want to set explicit
reuse terms.