bwrap

Run a program in a read-only environment

$ bwrap --ro-bind / / [/bin/bash]

$ bwrap --dev-bind /dev /dev --proc /proc --ro-bind / / --tmpfs /tmp [/bin/bash]

bwrap [options] -- program [arguments...]

--bind host-path sandbox-path
    Bind mounts host-path to sandbox-path. Makes the host's file or directory accessible within the sandbox.

--ro-bind host-path sandbox-path
    Read-only bind mount. Similar to --bind, but the mounted file/directory is read-only inside the sandbox.

--tmpfs sandbox-path
    Creates a tmpfs mount at sandbox-path. tmpfs is an in-memory filesystem, providing a temporary and isolated storage space.

--unshare-net
    Creates a new network namespace, isolating the sandbox's network from the host's.

--unshare-ipc
    Creates a new IPC namespace. Isolates Inter-Process Communication.

--unshare-pid
    Creates a new PID namespace, Isolates process IDs.

--new-session
    Start a new session.

--chdir sandbox-path
    Changes the current directory inside the sandbox.

--dev-bind host-path sandbox-path
    Bind mounts a device from the host.

--ro-bind-try host-path sandbox-path
    Same as --ro-bind, but ignores errors if the source doesn't exist.

--proc sandbox-path
    Mounts a procfs instance.

--die-with-parent
    The bubblewrap process exits when the parent process exits.

--setenv VAR VALUE
    Sets an environment variable within the sandbox.

--clearenv
    Clears all environment variables within the sandbox.

--root sandbox-path
    Sets the root directory to sandbox-path within the sandbox.

--perms permissions
    Sets the permissions of a mount point (e.g., rw, ro).

bwrap, short for bubblewrap, is a sandboxing tool on Linux that creates lightweight containers for running applications. It provides a secure and isolated environment by restricting access to the host system's resources such as the file system, network, and process namespaces. This isolation helps prevent potentially malicious or untrusted applications from harming the main system.

bwrap utilizes Linux namespaces and seccomp to achieve its isolation. It creates a new mount namespace, allowing it to define a custom root filesystem for the sandboxed process. It can also restrict network access, limit resource usage, and prevent the application from accessing sensitive data on the host system. The primary use case is for safely running untrusted code or applications requiring a pristine environment. It's frequently used in conjunction with Flatpak to distribute applications. Bubblewrap is designed to be unprivileged and can be run by regular users without requiring root access, enhancing its accessibility and security.

While bwrap provides a significant degree of isolation, it is not a full virtual machine. Kernel vulnerabilities could still potentially allow escape from the sandbox. Care should be taken when dealing with highly sensitive or untrusted code. Seccomp is architecture dependent and the available syscalls can vary.

It is important to understand the limitations of bwrap's security model. While it provides a good level of isolation, it's not a substitute for full virtualization. Users should always exercise caution when running untrusted code, even within a bwrap sandbox. Pay special attention to resource limits and network access configurations.

Problems with bwrap often relate to incorrect mount configurations or insufficient permissions. Check that the specified paths exist and that the user running bwrap has the necessary permissions to access them. Inspect error messages carefully, as they often provide clues about the cause of the issue. Consider enabling verbose output for debugging purposes.

bwrap was created by Alexander Larsson and is actively maintained. It was developed to provide a lightweight sandboxing solution for applications, particularly within the context of Flatpak. Its initial focus was on enabling secure execution of desktop applications in a containerized environment without requiring root privileges. The command has evolved significantly over time to incorporate more advanced isolation features, enhanced security, and improved usability. It became a core component of the Flatpak ecosystem and has been widely adopted for its ability to improve application security and reproducibility.

flatpak(1), unshare(1), namespaces(7)