containers /bubblewrap
Low-level unprivileged sandboxing tool used by Flatpak and similar projects
★ 9,498⑂ 411👁 62⑃ 421● 406▤ 28
+9
Daily
9,498
stars
411
forks
62
watchers
421
prs
406
issues
28
releases
README
Bubblewrap ========== Many container runtime tools like systemd-nspawn, docker, etc. focus on providing infrastructure for system administrators and orchestration tools (e.g. Kubernetes) to run containers. These tools are not suitable to give to unprivileged users, because it is trivial to turn such access into a fully privileged root shell on the host. User namespaces --------------- There is a feature in the Linux kernel called user namespaces which allows unprivileged users to use container features. Bubblewrap uses these to build the sandbox, allowing any user to use the tool. Historically, bubblewrap also supported a setuid mode for systems where unprivileged user namespaces were not supported. However, this has been removed. The original bubblewrap code existed before user namespaces - it inherits code from xdg-app helper which in turn distantly derives from linux-user-chroot. System security --------------- The maintainers of this tool believe that it does not, even when used in combination with typical software installed on that distribution, allow privilege escalation. It may increase the ability of a logged in user to perform denial of service attacks, however. In particular, bubblewrap uses PR_SET_NO_NEW_PRIVS to turn off setuid binaries, which is the traditional way to get out of things like chroots. Sandbox security ---------------- bubblewrap is a tool for constructing sandbox environments. bubblewrap is not a complete, ready-made sandbox with a specific security policy. Some of bubblewrap's use-cases want a security boundary between the sandbox and the real system; other use-cases want the ability to change the layout of the filesystem for processes inside the sandbox, but do not aim to be a security boundary. As a result, the level of protection between the sandboxed processes and the host system is entirely determined by the arguments passed to bubblewrap. Whatever program constructs the command-line arguments for bubblewrap (often a larger framework like Flatpak, libgnome-desktop, sandwine or an ad-hoc script) is responsible for defining its own security model, and choosing appropriate bubblewrap command-line arguments to implement that security model. Some aspects of sandbox security that require particular care are described in the Limitations section below. Users ----- This program can be shared by all container tools which perform non-root operation, such as: - Flatpak - rpm-ostree unprivileged - bwrap-oci We would also like to see this be available in Kubernetes/OpenShift clusters. Having the ability for unprivileged users to use container features would make it significantly easier to do interactive debugging scenarios and the like. Installation ------------ bubblewrap is available in the package repositories of the most Linux distributions and can be installed from there. If you need to build bubblewrap from source, you can do this with meson: sh meson setup _builddir meson compile -C _builddir
Top issues
#380bwrap refuses to run with ambient capabilities25 comments · 2020-06-23#139Unable to run even though I appear to have all relevant features except CONFIG_USER_NS22 comments · 2017-01-06#132Design for setting up fuse mounts (setuid)21 comments · 2016-12-20#134breaks with /proc/xen mounted (QubesOS)20 comments · 2016-12-26#468Support for user and group ID mappings18 comments · 2021-12-29#390Bind mounting over symlinks attempts to create their targets and bind mount over them17 comments · 2020-09-14#384O(N^2) performance in the number of "--bind" flags17 comments · 2020-08-13#2move fs templating out via static copy, handling /tmp16 comments · 2016-02-17
Latest release
0.13.1 v0.13.1 2026-10-14Enhancements:
bwrap now accepts multiple --sync-fd arguments and will handle
all of the fds.
Bug fixes:
O_PATH is used when opening parent directories in the new root,
fixing an error when read permission is missing. (806, ValveSoftware/steam-runtime855).
Thanks: smcv, swick
0e85c8702248b8dd64144f594147553650cdd0e4c951690345faace79c217c4d bubblewrap-0.13.1.tar.xz