Skip to main content

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.

debsb tutorial

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)
  • wget
  • ssh

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:

  1. Sets up the cloud image (if not already done)
  2. Generates a default kernel config (make defconfig) with VM-essential options
  3. Applies --configitem entries
  4. Runs make olddefconfig and make bindeb-pkg
  5. Installs the resulting .deb into 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

  1. Downloads debian-sid-generic-amd64-daily.qcow2 from cloud.debian.org
  2. Creates a cloud-init ISO with SSH keys, user config, and auto-login
  3. Boots the VM with QEMU/KVM and waits for cloud-init to finish
  4. On subsequent debsb run, boots the prepared image directly

When building with a kernel (debsb build <path> or debsb build --debian):

  • The kernel .deb is installed into the VM
  • GRUB is updated to boot the new kernel by default
  • No -kernel or -initrd flags 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)

Source distribution for debsb 0.2.3
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)

Table of built distributions (wheels) for debsb 0.2.3
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page