{"id":15003671,"url":"https://github.com/0xricksanchez/like-dbg","last_synced_at":"2025-05-16T17:04:09.324Z","repository":{"id":52304753,"uuid":"504825085","full_name":"0xricksanchez/like-dbg","owner":"0xricksanchez","description":"Fully dockerized Linux kernel debugging environment","archived":false,"fork":false,"pushed_at":"2024-09-23T09:51:54.000Z","size":5395,"stargazers_count":746,"open_issues_count":25,"forks_count":60,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-07T01:12:32.457Z","etag":null,"topics":["ctf","ctf-tools","debugging","docker","exploit","exploit-development","gdb","kernel","linux","linux-kernel","pwn","qemu"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xricksanchez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-18T11:29:49.000Z","updated_at":"2025-04-06T12:00:20.000Z","dependencies_parsed_at":"2023-10-03T17:48:33.396Z","dependency_job_id":"6e844d62-fb40-49f8-bd1e-8e591b5b3e3a","html_url":"https://github.com/0xricksanchez/like-dbg","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xricksanchez%2Flike-dbg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xricksanchez%2Flike-dbg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xricksanchez%2Flike-dbg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xricksanchez%2Flike-dbg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xricksanchez","download_url":"https://codeload.github.com/0xricksanchez/like-dbg/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254573589,"owners_count":22093731,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ctf","ctf-tools","debugging","docker","exploit","exploit-development","gdb","kernel","linux","linux-kernel","pwn","qemu"],"created_at":"2024-09-24T19:00:07.652Z","updated_at":"2025-05-16T17:04:09.302Z","avatar_url":"https://github.com/0xricksanchez.png","language":"Python","readme":"# LIKE-DBG\n\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Build Status: flake8](https://github.com/PyCQA/flake8/workflows/main/badge.svg)](https://github.com/0xricksanchez/like-dbg/actions?query=workflow%3Aflake8)\n[![Build Status: shellcheck](https://github.com/koalaman/shellcheck/actions/workflows/build.yml/badge.svg)](https://github.com/0xricksanchez/like-dbg/actions?query=workflow%3Ashellcheck)\n[![Build Status: hadolint](https://img.shields.io/badge/hadolint-passing-brightgreen)](https://github.com/0xricksanchez/like-dbg/actions?query=workflow%3Ahadolint)\n[![codecov](https://codecov.io/gh/0xricksanchez/like-dbg/branch/main/graph/badge.svg?token=SXF37MH4X6)](https://codecov.io/gh/0xricksanchez/like-dbg)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://tldrlegal.com/license/mit-license)\n[![GitHub Release](https://img.shields.io/github/release/0xricksanchez/like-dbg.svg)](https://github.com/0xricksanchez/like-dbg/releases/)\n\nLIKE-DBG (*LI*nux-*KE*rnel-*D*e*B*u*G*ger) aims at automating the boring steps when trying to set up a Linux kernel debugging environment.\nI set out to dive into kernel exploitation research and found existing solutions not usable enough.\nHence, 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.\nAll 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.\nCurrently, there's a dedicated docker container for every of the following steps:\n\n- Building the kernel\n- Creating a root file system to use with the kernel\n- Launching the kernel + file system as the _debuggee_\n- Attaching to the kernel as a _debugger_\n\n## Caveats\n\nAs this project is in its early stages, I expect things to change rapidly, while also introducing breaking changes along the way.\nMajor points to improve on are:\n\n- Getting towards true multi-architecture support beyond `x86_64` and `arm64`\n- Extend kernel builder to not only succeed in building recent™ kernels\n- Add android kernel support\n- Add (integration) tests\n- Elevate the debugging experience even more\n\n## Features\n\nOn the upside, despite its early stages, a couple of useful features are already present:\n\n- General:\n  - Minimal host system requirements due to dockerization of every step\n  - An easy to grasp `configs/user.ini` config that allows highly customizable sessions\n    - Or provide different configurations for different debugging setups via the command-line!\n  - CTF runner that's specifically designed to handle Linux kernel exploitation challenges\n    - `ctf/misc` that houses some nifty scripts to aid in CTFs\n  - Code quality measures:\n    - [black](https://github.com/psf/black) formatter for python code\n    - [flake8](https://github.com/PyCQA/flake8) linter for all python code\n    - [shellcheck](https://github.com/koalaman/shellcheck) linter for shell scripts\n    - [hadolint](https://github.com/hadolint/hadolint) linter for the Dockerfiles\n  - Operating system agnostic, meaning it should run just fine on:\n    - Debian/Ubuntu\n    - Arch Linux/Manjaro\n    - Fedora\n- Kernel builder:\n  - Multi-arch: `x86_64`, `arm64`\n  - Choose between `gcc` and `clang` to build the kernel\n  - Configuration modes:\n    - generic-mode,\n    - syzkaller-mode,\n    - custom-mode, or\n    - provide a usable kernel config\n  - Fine-granular version control to build from:\n    - Commit hash\n    - Release tag (e.g.: 5.10-rc)\n    - Major-Minor-Patch (e.g.: 5.10.77)\n  - Ability to automatically apply patch files\n  - Basic ability to add custom kernel modules\n- Root file system builder:\n  - Powered by [debootstrap](https://wiki.debian.org/Debootstrap)\n  - Automatic generation of file system that matches the kernels architecture\n  - Ability to customize:\n    - wanted packages in the file system\n    - the Debian release version to base everything on\n- Debuggee:\n  - Powered by [QEMU](https://github.com/qemu/qemu)\n  - Customization of QEMU runtime options from within the `configs/*.ini` files.\n- Debugger:\n  - Powered by [GDB (multiarch)](https://sourceware.org/gdb/) with either\n    - [GEF](https://github.com/hugsy/gef) and [GEF-extras](https://github.com/hugsy/gef-extras), or\n    - [pwndbg](https://github.com/pwndbg/pwndbg)\n  - Allow users to specify GDB script in `io/scripts/gdb_script` to allow a scenario-tailored debugging experience\n\n## Requirements\n\nTo get started, you have to ensure to have the following requirements set up in your system:\n\n- `docker`\n- `tmux`\n- `python\u003e=3.11`\n- `poetry` # \u003chttps://python-poetry.org/docs/\u003e\n\nIt is recommended to not run this as the `root` user, e.g. for testing purposes on a VPS.\nIt may work fine but in general I highly encourage creating a dedicated non-root user to put in the `docker` and `sudo` group!\n\n**Note**: If you're using a custom TMUX config, make sure that your first pane starts at `0`!\n\n### Optional\n\nThis 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.\n\n- [musl-gcc](https://www.musl-libc.org/how.html)\n- [ctags](https://github.com/universal-ctags/ctags)\n- [ropr](https://github.com/Ben-Lichtman/ropr)\n\n## Setup\n\nInside `like-dbg` run `poetry install`\n\n## Configuration\n\nFine-tuning the kernel debugging experience is one of the goals of this project.\nCurrently, all tunable options are exposed in the two configuration files: `configs/system.ini` and `configs/user.ini`.\nSome fields are recommended to not be altered as they're mainly for development reasons.\nHowever, all the ones to customize the environment to your needs should be self-explanatory as all of them are labeled with a brief comment.\n\n## Usage\n\n**Note:** On first time usage run `poetry install`.\n\nOnce you're set with writing/adapting a configuration, the usage depends on your scenario.\nThe easiest way to get started, which is based on the `configs/user.ini` configuration is the following:\n\n```sh\ntmux -f .tmux.conf\npoetry shell\n# This checks out a kernel, builds it, creates a root file system and starts the debugger and debuggee eventually\n./start_kgdb.py\n```\n\nThere exist 2 users for the automatically created filesystems:\n\n- `root` with no password\n- `user`:`user`\n\nThis is intended so you can develop and exploit from either perspective easily.\n\n### Extended Usage\n\n```sh\n# If you want to try a CTF challenge where you were given a (compressed) Linux Image and a root filesystem try:\n./start_kgdb.py --ctf \u003cImage\u003e \u003cRootFS\u003e\n\n# If you want to kill the current debugging session\n./start_kgdb.py -k\n\n# If you want to provide a custom 'user.ini' for a specific debugging setup\n./start_kgdb.py -c \u003cpath_to_cfg\u003e [other_args]\n\n# If you want to test some partial functionality of LIKE-DBG\n# Stage 1: Download Kernel\n# Stage 2: Stage 1 \u0026 unpack Kernel\n# Stage 3: Stage 2 \u0026 build Kernel\n# Stage 4: Only build a root file system\n# Stage 5: Stage 3+4 \u0026 start debuggee\n./start_kgdb.py -p \u003cstage_nr\u003e\n\n# Update all containers\n./start_kgdb.py -u\n```\n\n### Examples\n\nThe `examples` subdirectory houses samples on how `LIKE_DBG` may aid you in specific kernel debugging tasks.\nEach example contains a dedicated `README.md` as well that contains the necessary information to reproduce the examples.\n\n## Showcase\n\n![img/example.png](img/example.png)\n\n## Hacking\n\nThe python code should be quite readable, so feel free to extend the project with your own ideas. All PRs are very much welcome :)!\nOtherwise, feel free to create a feature-request issue or head over to the [discussions page](https://github.com/0xricksanchez/like-dbg/discussions) to brainstorm some cool new features!\n\nPS: If you want to provide a logo, feel free to do so.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xricksanchez%2Flike-dbg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xricksanchez%2Flike-dbg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xricksanchez%2Flike-dbg/lists"}