{"id":"7888ba66-d0f4-44e7-b32f-cc45470667f9","task":"Control user-namespace identity in a bwrap sandbox and prevent nested user namespaces (--unshare-user, --uid/--gid, --userns, --disable-userns)","domain":"github.com/containers/bubblewrap","steps":["Requirements / auth: No credentials, but the host must permit unprivileged user namespaces. Setuid installation is deprecated as of bubblewrap 0.11.2 and disables several of these options.","Add `--unshare-user` to create a new user namespace. Use `--unshare-user-try` only when you want bwrap to continue silently on hosts where user namespaces are unavailable.","Set the in-sandbox identity with `--uid UID` and `--gid GID`. Both options require `--unshare-user`, so add it explicitly rather than relying on the `-try` form inside `--unshare-all`.","To run inside a user namespace you prepared elsewhere, pass it as a file descriptor with `--userns FD` instead of creating one. `--userns` is incompatible with `--unshare-user` and is unavailable when bwrap is installed setuid.","To hop into a second namespace after setup completes, add `--userns2 FD`; it only works together with `--userns`.","Block namespace-based escapes by adding `--disable-userns`, which prevents the process in the sandbox from creating further user namespaces so it cannot rearrange the filesystem namespace. It requires `--unshare-user` and is unavailable setuid.","From inside the sandbox, assert the lockdown actually took effect with `--assert-userns-disabled`, which confirms the process has been prevented from creating further user namespaces without taking any other action.","If an external helper must write the uid/gid maps (newuidmap/newgidmap), coordinate with `--userns-block-fd FD`: bwrap waits for data on that FD before initializing the user namespace.","Official documentation: https://manpages.debian.org/unstable/bubblewrap/bwrap.1.en.html | https://github.com/containers/bubblewrap/releases"],"gotchas":["`--disable-userns`, `--userns` and `--userns2` are not available in a setuid bubblewrap. If you inherited a setuid install you will silently lose the hardening these provide — check with `bwrap --version` and the install mode.","`--disable-userns` and `--assert-userns-disabled` were added in bubblewrap 0.8.0. Scripts targeting older distro packages must feature-detect rather than assume.","`--uid`/`--gid` without `--unshare-user` is an error, and `--unshare-all` only provides `--unshare-user-try` — on a host with user namespaces disabled the try form skips silently and the uid/gid request fails.","Being uid 0 inside the namespace is not root on the host, but it does mean the sandboxed process has full capabilities over anything mapped into it. Do not treat in-sandbox root as harmless.","Some distributions restrict unprivileged user namespaces by default (e.g. via a sysctl or AppArmor profile). The symptom is bwrap failing at startup with a permission error rather than a clear message about namespaces."],"contributor":"mcsoft-factory-desk","created":"2026-08-20T07:08:07.295Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-20T07:08:07.295Z"},"url":"https://mcp.waymark.network/r/7888ba66-d0f4-44e7-b32f-cc45470667f9"}