bwrap

Run a program in a read-only environment

Give the environment access to devices, process information and create a tmpfs for it

bwrap [OPTIONS...] COMMAND [ARGS...]

The COMMAND and its ARGS are executed inside the newly created sandboxed environment.

--bind OLD NEW
    Mounts the file or directory OLD from the host into the sandbox at NEW. This exposes host paths to the sandboxed application.

--ro-bind OLD NEW
    Mounts the file or directory OLD from the host read-only into the sandbox at NEW.

--tmpfs PATH
    Creates a temporary filesystem (tmpfs) mounted at PATH inside the sandbox. Its contents are lost when the sandbox exits.

--dev PATH
    Creates a new /dev filesystem at PATH inside the sandbox, only populated with essential device files like /dev/null, /dev/zero, etc.

--proc PATH
    Creates a new /proc filesystem at PATH inside the sandbox, showing only processes within the sandbox's PID namespace.

--symlink TARGET LINK_NAME
    Creates a symbolic link LINK_NAME pointing to TARGET inside the sandbox.

--clearenv
    Clears the environment variables inherited from the parent process, providing a clean environment.

--setenv KEY VALUE
    Sets an environment variable KEY to VALUE inside the sandbox for the executed command.

--unshare-user
    Creates a new user namespace. The sandboxed process will run as root within this namespace, mapped to a non-privileged user on the host.

--unshare-pid
    Creates a new PID namespace. Processes inside the sandbox will have their own PID 1, isolated from host processes.

--unshare-net
    Creates a new network namespace. The sandbox will have an isolated network stack, effectively preventing network access by default.

--share-net
    Shares the host's network namespace, allowing the sandboxed process to access the network as usual (no network isolation).

--die-with-parent
    Kills the sandboxed process if the parent process (the one that invoked bwrap) dies.

--new-session
    Creates a new session for the sandboxed process, detaching it from the calling terminal. Useful for daemon processes.

--cap-drop CAP
    Drops the specified Linux capability for the sandboxed process. Can be used multiple times to remove various privileges.

--seccomp FILE
    Applies a seccomp-bpf filter program from FILE to restrict system calls the sandboxed process can make.

bwrap (short for "bubblewrap") is a lightweight, low-level sandboxing tool for Linux. Its primary purpose is to create isolated execution environments for applications, leveraging various Linux kernel features, most notably namespaces (mount, user, PID, network, IPC, UTS, cgroup) and seccomp-bpf filters.

Unlike full virtual machines or containers like Docker, bwrap doesn't virtualize an entire operating system; instead, it focuses on isolating a process from the host system's files, processes, and network. It achieves this by creating new namespaces for the process, effectively giving it its own view of the system resources. For example, it can present a custom root filesystem, hide the host's /proc or /dev, or prevent network access.

bwrap is a fundamental building block for higher-level sandboxing solutions, most notably Flatpak, where it provides the underlying security isolation for GUI applications. Its design prioritizes security and unprivileged operation, allowing users to run potentially untrusted applications in a controlled environment without requiring root privileges for the sandboxing itself (though setting up user namespaces might require system-wide configuration or capabilities). It provides a powerful and flexible mechanism for controlling what an application can see and do on the system.

• Privilege Requirements: While bwrap aims for unprivileged sandboxing, creating user namespaces (via --unshare-user) often requires specific kernel configurations (kernel.unprivileged_userns_clone sysctl enabled) or a setuid binary. If user namespaces are disabled, bwrap typically needs CAP_SYS_ADMIN or root privileges to function fully.
• Not Full Virtualization: bwrap isolates processes but does not provide a full virtual machine. Kernel vulnerabilities or misconfigurations can still impact the host system.
• Complexity: Building a secure and functional sandbox with bwrap can be complex due to the granular control it offers over namespaces and mounts. Incorrect configurations can lead to security holes or broken applications.
• Kernel Dependency: Relies heavily on modern Linux kernel features (namespaces, cgroups, seccomp). Older kernels may not support all features or behave differently.

bwrap's security model is built upon the Linux kernel's namespaces and seccomp-bpf.

• Namespaces: Isolate the sandboxed process's view of system resources (filesystems, PIDs, users, network). For example, a new mount namespace means the process sees a custom root filesystem, and a new user namespace allows the process to run as root within its sandbox without being root on the host.
  
• Seccomp-bpf: Allows for fine-grained control over which system calls the sandboxed process is permitted to make, significantly reducing the attack surface by preventing access to dangerous kernel functions.

By combining these features, bwrap provides a powerful isolation mechanism, reducing the potential impact of vulnerabilities within sandboxed applications.

A common pattern for using bwrap involves setting up a minimal, isolated environment by explicitly binding necessary directories from the host, creating new filesystems for temporary data, and unsharing various namespaces:

bwrap \
  --bind /usr /usr \
  --bind /bin /bin \
  --bind /lib /lib \
  --bind /lib64 /lib64 \
  --tmpfs /tmp \
  --proc /proc \
  --dev /dev \
  --unshare-pid \
  --unshare-net \
  --die-with-parent \
  -- command args...

This creates an isolated sandbox, provides essential system directories, and ensures the sandboxed command has its own process and network space, while also ensuring it cleans up when the parent process exits.

The bwrap utility was developed as a core component of the Flatpak (originally xdg-app) project, which aims to revolutionize how desktop applications are distributed and run on Linux. Before bwrap, Flatpak utilized OSTree and other mechanisms for application bundling, but a robust and unprivileged sandboxing solution was needed. bwrap was created to fill this gap, providing a secure, lightweight, and user-namespace-aware primitive for creating application sandboxes. Its development focused on being simple, auditable, and resilient against typical sandbox escapes, making it an essential part of the modern Linux desktop application ecosystem.

unshare(1), namespaces(7), mount(8), chroot(1), flatpak(1), firejail(1), systemd-nspawn(1)