How to Use the bwrap Command in Linux to Sandbox and Isolate Untrusted Applications

In modern Linux workstation and server security, executing untrusted binaries, downloaded proprietary applications, or third-party parsing scripts (such as PDF renderers and media decoders) poses significant risks of data exfiltration and host compromise. Traditional confinement methods often fall short: standard chroot requires elevated root privileges and fails to isolate network or process namespaces, while container runtimes like Docker or Podman introduce daemon complexity and heavyweight virtualization overhead. To provide a minimalist, unprivileged, and robust sandboxing primitive, the Flatpak and Red Hat teams developed Bubblewrap, executed via the bwrap command.

Leveraging Linux kernel namespaces—specifically User (CLONE_NEWUSER), Mount (CLONE_NEWNS), Network (CLONE_NEWNET), and PID (CLONE_NEWPID)—bwrap allows standard, unprivileged users to construct ephemeral, granular sandbox filesystems. Inside a Bubblewrap container, an application only sees the exact directories, device nodes, and network sockets explicitly granted by the user on the command line. This comprehensive guide outlines the sandboxing architecture of bwrap, demonstrates how to construct minimal container environments, and explains how to isolate network access and capabilities.

Sandboxing Tool Comparison: bwrap vs. Traditional Isolation

Comparing Bubblewrap against alternative Linux isolation mechanisms illustrates its design strengths:

Isolation Utility	Root Privileges Required	Namespace Isolation Scope	Primary Use Case
bwrap (Bubblewrap)	No (Unprivileged User Namespaces)	Full: Mount, Network, PID, IPC, User	Application sandboxing (Flatpak core engine), script containment.
chroot	Yes (Root required)	Filesystem root path only (Zero PID/Network isolation)	Legacy recovery environments and OS bootstrap installs.
firejail	Requires SUID root helper	Full: Seccomp, Namespaces, AppArmor	Desktop application sandboxing with pre-built profiles.
docker / podman	Daemon / Rootless subuid mapping	Full: Cgroups, Namespaces, Seccomp, OverlayFS	Server microservices, CI/CD pipelines, container orchestration.

Installing Bubblewrap and Verifying Kernel Support

Bubblewrap is available in the default repositories of all major Linux distributions:

• Ubuntu / Debian: sudo apt install bubblewrap
• Fedora / RHEL: sudo dnf install bubblewrap
• Arch Linux: sudo pacman -S bubblewrap

Verify that your Linux kernel permits unprivileged user namespaces:

sysctl kernel.unprivileged_userns_clone

If the command outputs 1 (or is absent on newer kernels where unprivileged user namespaces are natively enabled), bwrap is ready for immediate deployment.

Constructing a Minimal Sandbox Environment

Because Bubblewrap starts with an empty root filesystem, you must explicitly bind-mount the system binaries and shared libraries required for the target application to execute.

To launch a minimal, isolated bash shell:

bwrap \
  --ro-bind /usr /usr \
  --ro-bind /lib /lib \
  --ro-bind /lib64 /lib64 \
  --ro-bind /bin /bin \
  --dev /dev \
  --proc /proc \
  --tmpfs /tmp \
  --unshare-all \
  /bin/bash

In this command:

• --ro-bind /usr /usr: Mounts host binaries and system libraries in read-only mode, preventing the sandboxed process from modifying system files.
• --dev /dev: Creates a clean, isolated pseudo-device filesystem (providing /dev/null, /dev/urandom, and /dev/zero while concealing physical disk block devices).
• --proc /proc: Mounts a virtualised /proc filesystem where the container only sees its own process hierarchy.
• --tmpfs /tmp: Allocates an ephemeral in-memory filesystem for temporary files that is wiped the instant the container exits.
• --unshare-all: Simultaneously unshares all kernel namespaces: Mount, User, PID, IPC, UTS, and Network.

Once inside the shell, test your isolation:

ls /home

The /home directory does not exist. The sandboxed shell cannot read your SSH keys, documents, browser cookies, or cloud tokens.

Restricting Network Access and Socket Communication

By default, untrusted scripts might attempt to beacon data back to command-and-control servers. Passing the --unshare-net flag creates an isolated, loopback-only network namespace:

bwrap \
  --ro-bind /usr /usr \
  --ro-bind /lib /lib \
  --ro-bind /lib64 /lib64 \
  --ro-bind /bin /bin \
  --proc /proc \
  --dev /dev \
  --unshare-net \
  /bin/bash -c "curl -I https://digitash.com"

The curl command immediately fails with Could not resolve host or network unreachable, proving that external socket communication is physically impossible within the sandbox.

Practical Scenario: Sandboxing an Untrusted PDF Viewer

When opening an untrusted PDF or document, you can grant read-only access strictly to that individual file and expose the display server without exposing your broader home directory:

bwrap \
  --ro-bind /usr /usr \
  --ro-bind /lib /lib \
  --ro-bind /lib64 /lib64 \
  --ro-bind /etc/fonts /etc/fonts \
  --ro-bind /etc/ld.so.cache /etc/ld.so.cache \
  --ro-bind "$XDG_RUNTIME_DIR/wayland-0" "$XDG_RUNTIME_DIR/wayland-0" \
  --setenv WAYLAND_DISPLAY "wayland-0" \
  --ro-bind /home/user/Downloads/suspicious_contract.pdf /doc.pdf \
  --dev /dev \
  --proc /proc \
  --tmpfs /tmp \
  --unshare-all \
  --die-with-parent \
  evince /doc.pdf

Key defensive parameters here include:

• --ro-bind ... /doc.pdf: Remaps the target file to root /doc.pdf inside the container, granting access exclusively to that single document.
• --die-with-parent: Ensures that if the parent terminal or launching application terminates, the sandboxed process is instantly killed, preventing orphaned background persistence.

Dropping Linux Capabilities and Enforcing Seccomp Filters

To eliminate privilege escalation risks, Bubblewrap can strip all Linux POSIX capabilities:

bwrap --cap-drop ALL ...

This ensures that even if an attacker manages to execute a setuid binary inside the sandbox, the kernel denies all elevated administrative capabilities (such as CAP_SYS_ADMIN or CAP_NET_RAW).

By mastering the bwrap command, Linux administrators and developers can execute untrusted software safely, build custom desktop application jails, and enforce strict principle-of-least-privilege boundaries without heavyweight container runtimes.