https://github.com/containers/bubblewrap Skip to content Sign up * Product + Features + Mobile + Actions + Codespaces + Packages + Security + Code review + Issues + Integrations + GitHub Sponsors + Customer stories * Team * Enterprise * Explore + Explore GitHub + Learn and contribute + Topics + Collections + Trending + Learning Lab + Open source guides + Connect with others + The ReadME Project + Events + Community forum + GitHub Education + GitHub Stars program * Marketplace * Pricing + Plans + Compare plans + Contact Sales + Education [ ] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this organization All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up {{ message }} containers / bubblewrap Public * Notifications * Fork 158 * Star 2.1k Unprivileged sandboxing tool View license 2.1k stars 158 forks Star Notifications * Code * Issues 104 * Pull requests 26 * Actions * Projects 0 * Wiki * Security * Insights More * Code * Issues * Pull requests * Actions * Projects * Wiki * Security * Insights This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. main Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags 12 branches 20 tags Code Latest commit @smcv smcv Merge pull request #484 from rusty-snake/install-instructions ... 34a8c8b Mar 22, 2022 Merge pull request #484 from rusty-snake/install-instructions Add install instruction to README.md 34a8c8b Git stats * 512 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time .github/workflows Disable test-specifying-pidns.sh under 'meson dist' while I investigate Feb 20, 2022 ci Add a Meson build system Feb 18, 2022 completions Add --add-seccomp-fd to bash/zsh completion Mar 22, 2022 demos bash: Invoke bash using /usr/bin/env Oct 14, 2021 m4 build: Sync default warning -> error set from ostree Dec 12, 2016 packaging Remove trailing whitespace Oct 14, 2021 tests tests: properly tag ok as being printf-like Mar 18, 2022 .dir-locals.el Add .editorconfig and .dir-locals.el May 6, 2016 .editorconfig Remove trailing whitespace Oct 14, 2021 CODE-OF-CONDUCT.md Use HEAD to refer to other projects' default branches in documentation Feb 13, 2022 COPYING Add LGPLv2+ COPYING (and LICENSE symlink) Apr 22, 2016 LICENSE Add LGPLv2+ COPYING (and LICENSE symlink) Apr 22, 2016 Makefile-bwrap.am Remove trailing whitespace Oct 14, 2021 Makefile-docs.am build: Dist bwrap.xml in tarball Nov 9, 2016 Makefile.am Add a Meson build system Feb 18, 2022 README.md Add install instruction to README.md Mar 22, 2022 SECURITY.md Use HEAD to refer to other projects' default branches in documentation Feb 13, 2022 autogen.sh bash: Fix shellcheck warnings Oct 14, 2021 bind-mount.c bind-mount: Be more const-correct Oct 11, 2021 bind-mount.h Add SPDX-License-Identifier for files that already specify license Aug 31, 2021 bubblewrap.c Fix --add-seccomp-fd argument name in usage Mar 22, 2022 bubblewrap.jpg Revert "README.md: Delete cat logo picture (not DFSG compliant)" Oct 4, 2018 bwrap.xml Allow loading more than one seccomp program Jan 31, 2022 configure.ac Prepare v0.6.1 Feb 25, 2022 git.mk build: Use git.mk Apr 22, 2016 meson.build Prepare v0.6.1 Feb 25, 2022 meson_options.txt meson: Run the Python test script with Python, not bash Feb 20, 2022 network.c Add SPDX-License-Identifier for files that already specify license Aug 31, 2021 network.h Add SPDX-License-Identifier for files that already specify license Aug 31, 2021 release-checklist.md Add a release checklist Feb 25, 2022 uncrustify.cfg Add uncruftify config May 13, 2016 uncrustify.sh Add uncruftify config May 13, 2016 utils.c Fix spelling Oct 14, 2021 utils.h utils: Add warn() Oct 10, 2021 View code [ ] Bubblewrap User namespaces Security Users Installation Usage Sandboxing Related project comparison: Firejail Related project comparison: Sandstorm.io Related project comparison: runc/binctr What's with the name?! README.md 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 an effort in the Linux kernel called user namespaces which attempts to allow unprivileged users to use container features. While significant progress has been made, there are still concerns about it, and it is not available to unprivileged users in several production distributions such as CentOS/Red Hat Enterprise Linux 7, Debian Jessie, etc. See for example CVE-2016-3135 which is a local root vulnerability introduced by userns. This March 2016 post has some more discussion. Bubblewrap could be viewed as setuid implementation of a subset of user namespaces. Emphasis on subset - specifically relevant to the above CVE, bubblewrap does not allow control over iptables. The original bubblewrap code existed before user namespaces - it inherits code from xdg-app helper which in turn distantly derives from linux-user-chroot. 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. 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 or autotools. meson: meson _builddir meson compile -C _builddir meson install -C _builddir autotools: ./autogen.sh make sudo make install Usage bubblewrap works by creating a new, completely empty, mount namespace where the root is on a tmpfs that is invisible from the host, and will be automatically cleaned up when the last process exits. You can then use commandline options to construct the root filesystem and process environment and command to run in the namespace. There's a larger demo script in the source code, but here's a trimmed down version which runs a new shell reusing the host's /usr. bwrap --ro-bind /usr /usr --symlink usr/lib64 /lib64 --proc /proc --dev /dev --unshare-pid bash This is an incomplete example, but useful for purposes of illustration. More often, rather than creating a container using the host's filesystem tree, you want to target a chroot. There, rather than creating the symlink lib64 -> usr/lib64 in the tmpfs, you might have already created it in the target rootfs. Sandboxing The goal of bubblewrap is to run an application in a sandbox, where it has restricted access to parts of the operating system or user data such as the home directory. bubblewrap always creates a new mount namespace, and the user can specify exactly what parts of the filesystem should be visible in the sandbox. Any such directories you specify mounted nodev by default, and can be made readonly. Additionally you can use these kernel features: User namespaces (CLONE_NEWUSER): This hides all but the current uid and gid from the sandbox. You can also change what the value of uid/ gid should be in the sandbox. IPC namespaces (CLONE_NEWIPC): The sandbox will get its own copy of all the different forms of IPCs, like SysV shared memory and semaphores. PID namespaces (CLONE_NEWPID): The sandbox will not see any processes outside the sandbox. Additionally, bubblewrap will run a trivial pid1 inside your container to handle the requirements of reaping children in the sandbox. This avoids what is known now as the Docker pid 1 problem. Network namespaces (CLONE_NEWNET): The sandbox will not see the network. Instead it will have its own network namespace with only a loopback device. UTS namespace (CLONE_NEWUTS): The sandbox will have its own hostname. Seccomp filters: You can pass in seccomp filters that limit which syscalls can be done in the sandbox. For more information, see Seccomp. Related project comparison: Firejail Firejail is similar to Flatpak before bubblewrap was split out in that it combines a setuid tool with a lot of desktop-specific sandboxing features. For example, Firejail knows about Pulseaudio, whereas bubblewrap does not. The bubblewrap authors believe it's much easier to audit a small setuid program, and keep features such as Pulseaudio filtering as an unprivileged process, as now occurs in Flatpak. Also, @cgwalters thinks trying to whitelist file paths is a bad idea given the myriad ways users have to manipulate paths, and the myriad ways in which system administrators may configure a system. The bubblewrap approach is to only retain a few specific Linux capabilities such as CAP_SYS_ADMIN, but to always access the filesystem as the invoking uid. This entirely closes TOCTTOU attacks and such. Related project comparison: Sandstorm.io Sandstorm.io requires unprivileged user namespaces to set up its sandbox, though it could easily be adapted to operate in a setuid mode as well. @cgwalters believes their code is fairly good, but it could still make sense to unify on bubblewrap. However, @kentonv (of Sandstorm) feels that while this makes sense in principle, the switching cost outweighs the practical benefits for now. This decision could be re-evaluated in the future, but it is not being actively pursued today. Related project comparison: runc/binctr runC is currently working on supporting rootless containers, without needing setuid or any other privileges during installation of runC (using unprivileged user namespaces rather than setuid), creation, and management of containers. However, the standard mode of using runC is similar to systemd nspawn in that it is tooling intended to be invoked by root. The bubblewrap authors believe that runc and systemd-nspawn are not designed to be made setuid, and are distant from supporting such a mode. However with rootless containers, runC will be able to fulfill certain usecases that bubblewrap supports (with the added benefit of being a standardised and complete OCI runtime). binctr is just a wrapper for runC, so inherits all of its design tradeoffs. What's with the name?! The name bubblewrap was chosen to convey that this tool runs as the parent of the application (so wraps it in some sense) and creates a protective layer (the sandbox) around it. [bubblewrap] (Bubblewrap cat by dancing_stupidity) About Unprivileged sandboxing tool Topics linux-containers user-namespaces Resources Readme License View license Code of conduct Code of conduct Stars 2.1k stars Watchers 60 watching Forks 158 forks Releases 16 0.6.1 Latest Feb 25, 2022 + 15 releases Packages 0 No packages published Contributors 47 * @alexlarsson * @smcv * @cgwalters * @giuseppe * @mrunalp * @pwithnall * @marcosps * @a1346054 * @haraldkubota * @vn971 * @rhatdan + 36 contributors Languages * C 64.1% * Shell 12.4% * Python 8.1% * M4 6.5% * Makefile 5.6% * Meson 3.3% * (c) 2022 GitHub, Inc. * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.