README.md

sb — Sandbox Runner for Untrusted Programs

Why this exists

Every day, developers and users install software they haven't fully audited: cloned repos, pip packages, npm modules, random tools from GitHub. Each of these pulls in dependency trees that nobody reads line by line. Sometimes the malware isn't even in the project itself — it's in a transitive dependency that got compromised upstream.

The standard advice is "use containers" or "run it in a VM." But the reality is that most people don't. Setting up full containerization for every project you want to try is friction that almost nobody accepts in daily workflow. The result is a massive gap: millions of developers running unvetted code with full access to their filesystem, network, credentials, and SSH keys.

Existing tools each cover part of the problem but none cover the practical workflow:

• OpenSnitch provides interactive network prompts (like Little Snitch for Linux), but rules are per-binary — useless when the binary is python3 and you have dozens of unrelated Python projects.
• Firejail offers sandboxing profiles, but it's config-file-driven with no interactive prompting. You write rules up front or get nothing.
• Bubblewrap/Flatpak provide namespace isolation, but only for apps packaged in their format. Your cloned git project doesn't qualify.
• AppArmor/SELinux can do per-binary policy, but writing profiles is a specialized skill and there's still no interactive workflow.
• Full containers (Docker, Podman) work but impose real overhead: filesystem mapping, networking setup, GPU passthrough, permission juggling. It's not something you do casually for pip install some-tool && some-tool --help.

sb fills this gap. It's a thin wrapper around Linux kernel security features (Landlock, seccomp user notification) that lets you run any program — installed or not, interpreted or compiled — with controlled filesystem and network access. No containers, no packaging, no root required for basic operation.

What it does

# Run a program with a security profile
sb -p myproject ./run.sh

# First time? Create a profile
sb manage create myproject

# Just want to see what a program does?
sb --log-only ./suspicious-script.sh

# Dry-run to check the config
sb -p myproject --dry-run ./something

When a sandboxed program tries to make a network connection that isn't in your allow list, sb pauses the syscall and asks you — via a GUI dialog or terminal prompt — whether to allow it. You can allow once, for the session, or permanently (saved to the profile). This is how you discover that your markdown linter phones home to a telemetry server, or that a build tool downloads resources from unexpected domains.

Filesystem access is enforced via Landlock: you declare which directories the program can read and write, with ordered rules (first match wins) and a deny-all catch-all. The program gets EACCES for anything outside the whitelist — it can't read your SSH keys, can't modify your .bashrc, can't exfiltrate your credentials.

Architecture

sb (profile manager + launcher)
 └─ sb-supervisor (enforcement engine)
     ├─ Landlock LSM ──── filesystem allow/deny (kernel-enforced, zero overhead)
     ├─ seccomp-notify ── network syscall interception (pause-and-prompt)
     └─ OverlayFS ─────── write capture without touching real fs (optional, needs root)

Profiles are TOML files in ~/.config/sb/profiles/. Network events are logged to ~/.local/share/sb/logs/ as JSONL.

Requirements

• Linux kernel 5.13+ (for Landlock; seccomp-notify needs 5.9+)
• Python 3.11+
• yad or zenity for GUI prompts (falls back to terminal)
• Landlock enabled: check cat /sys/kernel/security/lsm includes landlock

Status

Active development. See CURRENT-STATE.md for where things stand.

License

TBD