From 862feada053d81c3750e23c3111abe5ef66425fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krist=C3=B3f=20T=C3=B3th?= Date: Wed, 22 Apr 2026 23:14:39 +0200 Subject: [PATCH] Document hardening, network default, and profile merge rules --- README.md | 12 ++++++++++-- src/cli.rs | 2 +- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b3aa868..032f57b 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Sandbox agentic coding assistants with [bubblewrap](https://github.com/container ### Whitelist -Tight sandbox for normal agent coding tasks. Only explicitly listed paths are visible — system binaries, libraries, a subset of `/etc`, `/sys` (all read-only), synthetic `/dev`, private `/proc`, `/tmp`, `/run`, and the working directory (read-write). Everything else is invisible. +Tight sandbox for normal agent coding tasks. Only explicitly listed paths are visible — system binaries, libraries, a subset of `/etc`, `/sys` (all read-only), synthetic `/dev`, private `/proc`, `/tmp`, `/run`, and the working directory (read-write). Everything else is invisible. Whitelist always runs with hardening on (see below). ### Blacklist @@ -16,6 +16,14 @@ The threat model is prompt injection and accidental damage, not a determined att **Not protected in blacklist mode:** arbitrary readable files outside the sensitive paths list, and D-Bus method calls (access control is daemon-side). +### Hardening + +`--hardened` unshares the IPC, PID, and UTS namespaces and sets the hostname to `sandbox`. This is independent of the filesystem mode and can be combined with either. Whitelist mode enables it unconditionally; blacklist mode leaves it off by default. Use `--no-hardened` to override a config-file `hardened = true` (note: it cannot disable the implicit hardening that comes with whitelist mode). + +### Network + +The network namespace is shared with the host by default. Pass `--unshare-net` (or set `unshare-net = true` in the config) to isolate it; `--share-net` overrides a config-file `unshare-net = true`. + ## Environment filtering Both modes clamp the environment the child sees so prompt-injected agents can't `printenv` their way to secrets. @@ -37,7 +45,7 @@ Settings can be stored in a TOML config file at `$XDG_CONFIG_HOME/agent-sandbox/ ln -sf "$(pwd)/config-example.toml" "${XDG_CONFIG_HOME:-$HOME/.config}/agent-sandbox/config.toml" ``` -Top-level keys set defaults; `[profile.]` sections define named presets selectable with `--profile `. CLI flags always take highest precedence, followed by the active profile, then top-level defaults. +Top-level keys set defaults; `[profile.]` sections define named presets selectable with `--profile `. CLI flags always take highest precedence, followed by the active profile, then top-level defaults. When a profile is active, list-valued fields (`ro`, `rw`, `mask`, `env`, `unsetenv`, `bwrap-args`) append to the globals; scalar fields (modes, flags, `entrypoint`, `command`, `chdir`) replace them. ```toml # Global defaults diff --git a/src/cli.rs b/src/cli.rs index 7e86d62..45f6c5b 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -18,7 +18,7 @@ pub struct Args { #[arg(long)] pub whitelist: bool, - /// Harden: unshare IPC, PID, UTS; private /tmp, /dev, /run + /// Harden: unshare IPC, PID, UTS namespaces and set hostname to "sandbox" (implied by --whitelist) #[arg(long, overrides_with = "no_hardened")] pub hardened: bool,