Bands executes untrusted scripts in isolated Linux VMs. This document describes what is enforced, what is not, and the threat model.
| Layer | Mechanism | Detail |
|---|---|---|
| Network egress | Per-execution iptables chain, UID-owner matched | Default REJECT. Explicit ACCEPT for allow.net hosts. deny.net adds REJECT before ACCEPT. No subprocess can bypass. |
| Filesystem | Bubblewrap mount namespace | allow.read mounted read-only. allow.write mounted read-write. deny.read/deny.write excluded from mounts. All other paths invisible. |
| User separation | Scripts run as band-runner via sudo inside bwrap |
Cannot read other users' files or escalate. UID preserved for iptables matching. |
| Process isolation | Full VM boundary (KVM / Virtualization.framework) | Hypervisor-level. |
| Layer | Mechanism | Detail |
|---|---|---|
| CLI allow | PATH set to wrapper-only directory | Commands not in allow.cli do not exist. |
| CLI deny | Proxy wrappers check full command line against deny globs | deny.cli: ["rm -rf *"] blocks rm -rf / but allows rm file. |
| Insist | CLI wrappers log invocations, server checks ops after execution | Run fails if insist patterns are not satisfied. |
| Feature | Status |
|---|---|
maxInputBytes / maxOutputBytes |
Parsed, not checked |
maxCostDollars |
Parsed, not checked |
| seccomp profiles | Not implemented. Mitigated by bwrap namespace + VM boundary. |
- Band server writes
input.jsonto a fresh workdir - Script runs inside bubblewrap — only declared paths visible
- Script writes to
$OUTPUT_PATH - Band server reads output, returns JSON
- Workdir deleted after every execution
Secrets passed as env vars via env.sh in the workdir. Only visible inside the bwrap mount namespace. Cleaned up after every execution.
Designed for trusted skill authors whose scripts may have bugs or unintended behavior. Isolation prevents accidental data exfiltration, network abuse, and cross-skill interference.
Not designed for determined adversaries with arbitrary code execution inside the VM. The VM boundary is the hard security line. Everything inside is defense-in-depth.
- Bash builtins (
echo,test,[,eval,source) bypass PATH wrappers and the DEBUG trap. They are not subject todeny.cliand won't be tracked for insist enforcement. - DNS-based iptables rules resolve hostnames at execution time. CDN IP rotation mid-request may cause connection failure.
- IPv6 traffic is not filtered. Only IPv4 iptables rules are applied — AAAA-resolvable hosts reachable via IPv6 are not subject to
allow.net/deny.net. - Symlinks inside
allow.read/allow.writedirectories are followed by the kernel. A symlink at an allowed path that points outside the allowed tree lets the script read or write the target. Avoid mounting directories that contain attacker-controlled symlinks. /procand/devare mounted inside the sandbox. Scripts can read/proc/self/*and other process metadata visible to the unprivilegedband-runnerUID.