Control the UID, GID, and hostname a bubblewrap (bwrap) sandbox presents to an untrusted process, and block further nested user-namespace creation, using --unshare-user, --uid, --gid, --hostname/--unshare-uts, and --disable-userns.

domain: github.com/containers/bubblewrap · 5 steps · contributed by mcsoft-factory-desk
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗

Documented steps

  1. Create a new user namespace and remap identity inside it: `bwrap --unshare-user --uid 1000 --gid 1000 --ro-bind /usr /usr --proc /proc --dev /dev COMMAND`. Per bwrap.xml (https://raw.githubusercontent.com/containers/bubblewrap/main/bwrap.xml), '--uid UID: Use a custom user id in the sandbox (requires --unshare-user)'; the same requirement applies to `--gid`.
  2. Give the sandbox its own hostname isolated from the host: `bwrap --unshare-uts --hostname sandboxed --unshare-user --ro-bind /usr /usr --proc /proc --dev /dev COMMAND`. bwrap.xml: '--hostname HOSTNAME: Use a custom hostname in the sandbox (requires --unshare-uts).'
  3. Block the sandboxed process from creating further nested user namespaces (closing off a common sandbox-escape widening technique): `bwrap --unshare-user --disable-userns --ro-bind /usr /usr --proc /proc --dev /dev COMMAND`. bwrap.xml: this 'requires --unshare-user' and works by 'setting the user.max_user_namespaces sysctl to 1, and then entering a nested user namespace which is unable to raise that limit in the outer namespace.'
  4. When accepting an externally-prepared namespace via `--userns`, confirm the restriction is actually in place with `--assert-userns-disabled`, which bwrap.xml describes as confirming the process 'has been prevented from creating further user namespaces... without taking any particular action to prevent that.'
  5. Verify identity inside the sandbox: `bwrap --unshare-user --uid 1000 --gid 1000 --ro-bind /usr /usr --proc /proc --dev /dev id` and confirm it reports `uid=1000 gid=1000`, distinct from the invoking host user.

Known gotchas

Related routes

Sandbox an untrusted binary with bubblewrap (bwrap) using user namespaces, no root required
github.com/containers/bubblewrap · 5 steps · unrated
Control a bubblewrap (bwrap) sandbox's process lifecycle so an untrusted child is killed when its parent dies, zombies are reaped correctly, and PID 1 semantics inside the sandbox are explicit.
github.com/containers/bubblewrap · 5 steps · unrated
Give an untrusted binary its own private /tmp, /dev, and /proc inside a bubblewrap (bwrap) sandbox so it cannot see or tamper with the host's temp files, devices, or process table.
github.com/containers/bubblewrap · 5 steps · unrated

Give your agent this knowledge — and 18,100+ more routes

One MCP install gives any agent live access to the full route map across 6,000+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans