debsb
Debian Sid sandbox in one command. Downloads a Debian cloud image, boots it in QEMU/KVM, and gives you an isolated VM with auto-login, SSH, and shared filesystem. No kernel building, no complex setup.
Motivation
I just want a fully hackable Debian setup—both user space and kernel—within a restricted sandbox.
I want to avoid rebuilding an OpenSSH-enabled rootfs for each fuzzing test and repeatedly using the -kernel and -initrd flags in QEMU.
Install
pip install debsb
Dependencies
qemu-system-x86_64(with KVM support)cloud-image-utils(cloud-localds)whois(mkpasswd)wgetssh
On Debian/Ubuntu:
sudo apt install qemu-system-x86 cloud-image-utils whois wget openssh-client
For upstream kernel builds (debsb build <path>), additionally:
sudo apt install build-essential flex bison bc libelf-dev libssl-dev libncurses-dev dwarves pahole libdw-dev libdwarf-dev kmod debhelper
For --debian kernel builds, additionally:
sudo apt install python3-dacite python3-debian python3-jinja2 debhelper quilt rsync devscripts dh-python
Usage
Build the sandbox (one-time)
debsb build --size 20G
This downloads the Debian Sid cloud image, configures SSH keys and auto-login, and runs first boot. All artifacts are stored in ~/.debsb/.
Use --reset to skip the prompt and rebuild from scratch:
debsb build --size 20G --reset
Build with a custom kernel (upstream)
debsb build ~/linux --configitem CONFIG_KASAN=y --configitem CONFIG_KCOV=y
This:
- Sets up the cloud image (if not already done)
- Generates a default kernel config (
make defconfig) with VM-essential options - Applies
--configitementries - Runs
make olddefconfigandmake bindeb-pkg - Installs the resulting
.debinto the VM via GRUB
Build with Debian kernel
This kernel image is built based on the official Debian repository.
# Default branch (debian/latest)
debsb build --debian --configitem CONFIG_KASAN=y --configitem CONFIG_KCOV=y
# Specific branch
debsb build --debian --branch debian/sid
This clones the Debian kernel from salsa.debian.org/kernel-team/linux.git, applies config items to debian/config/config, and builds the amd64 kernel package using the Debian packaging rules. The resulting kernel is installed into the VM via GRUB.
Run the sandbox
# Serial console (auto-login as debian, Ctrl-A X to quit)
debsb run
# SSH session (as debian)
debsb run --ssh
# SSH as root
debsb run --ssh --root
# Run a command and auto-shutdown (requires --ssh)
debsb run --ssh --root --exec "apt update && apt upgrade -y"
# Graphical QEMU window
debsb run --graphics
# With sound
debsb run --sound
# Extra QEMU options
debsb run --qemu-opts='-m 8192'
Execute a command
--exec runs a command via SSH and shuts down automatically. Requires --ssh:
debsb run --ssh --exec "uname -a"
debsb run --ssh --root --exec "ls -ahl .debsb"
debsb run --ssh --exec "./my-script.sh"
This is useful for CI/automation. The exit code of the command is propagated.
Verbose mode
Show kernel boot messages:
debsb run --verbose
Shared filesystem
Your host ~/.debsb/ directory is mounted inside the VM at:
/root/.debsb(symlink to/mnt/debsb)/home/debian/.debsb(symlink to/mnt/debsb)
This is automatic — no manual mounting needed.
How it works
- Downloads
debian-sid-generic-amd64-daily.qcow2from cloud.debian.org - Creates a cloud-init ISO with SSH keys, user config, and auto-login
- Boots the VM with QEMU/KVM and waits for cloud-init to finish
- On subsequent
debsb run, boots the prepared image directly
When building with a kernel (debsb build <path> or debsb build --debian):
- The kernel
.debis installed into the VM - GRUB is updated to boot the new kernel by default
- No
-kernelor-initrdflags needed — GRUB handles boot
Accounts
| User | Access |
|---|---|
debian |
Serial auto-login, SSH with key, sudo NOPASSWD |
root |
SSH with key (--root flag) |
SSH key: ~/.debsb/id_ed25519 (auto-generated on first build)
License
GPL-2.0-only
Metadata
Release files for debsb 0.2.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| debsb-0.2.3.tar.gz | 24.4 kB | Without provenance | Details for debsb-0.2.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| debsb-0.2.3-py3-none-any.whl | Python 3 | none | any | Details for debsb-0.2.3-py3-none-any.whl |
Total release size: 48.0 kB
Release files / debsb-0.2.3.tar.gz
| Download URL | debsb-0.2.3.tar.gz |
|---|---|
| Size | 24.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b2ff5cb12c3b377440b8b43fca288d4cc075a669cfa4254548232296918a017d
|
|
BLAKE2b-256 checksum How to use checksums |
210da3d013fd81f975a666ca9d7845ac00a753eb5cf4116bfac5a52cdc3bfa2d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / debsb-0.2.3-py3-none-any.whl
| Download URL | debsb-0.2.3-py3-none-any.whl |
|---|---|
| Size | 23.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5ca80106b76924481a2928c3d2914db5897d4250959989f859821286a661a197
|
|
BLAKE2b-256 checksum How to use checksums |
a10055920fc77c5fd3102eec6b0f7a66c17643843a776b801f2cba5fbe9e0eb2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for debsb 0.2.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.