View source for Bubblewrap

{{Draft|The reasoning is most likely wrong for why to do some stuff.  Someone more experienced needs to look it over.}}
{{TOC right}}

[https://github.com/containers/bubblewrap Bubblewrap] is an
unprivileged sandboxing tool.  Kernel features it also has:
User/IPC/PID/Network/UTS/cgroup
[https://en.wikipedia.org/wiki/Linux_namespaces namespaces] and
[https://en.wikipedia.org/wiki/Seccomp Seccomp] filters.

How bubblewrap works, as stated in the
[https://github.com/containers/bubblewrap/blob/main/README.md#usage README.md]:
: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.

== Installation ==

Install {{Pkg|bubblewrap|arch=}}:

{{Cmd|# apk add bubblewrap}}

{{Note|The package is {{pkg|bubblewrap|arch=}} but the command to
manage it is {{Ic|bwrap}}.}}

== How to workout what a program needs ==

{{Tip|Look at [[Bubblewrap/Examples]] to see various ways {{Ic|bwrap}} can be used.}}

=== Prerequisites ===

First make sure to have a user editable directory in {{Path|"$PATH"}}.
This page will use {{Path|"${HOME}/.local/bin/"}}, create it if it does
not exist:

{{Cmd|$ mkdir -p ~/.local/bin}}

Add it to {{Path|~/.profile}}:

{{Cat|~/.profile|...<nowiki>
PATH="${PATH}":"${HOME}/.local/bin"
export PATH
</nowiki>...}}

Will need to relog for this to apply.

=== Basic bwrap setup ===

{{Note|With how we will be sandboxing everything that doesn't match our owner/group will show as {{Ic|nobody}}.}}

Lets assume you want to sandbox {{Pkg|imv|arch=}} and are using [[Wayland]]
only.  Here is how you might go about that.

Create {{Ic|bwrap-imv}} inside {{Path|"${HOME}/.local/bin/"}} and make it
executable:

{{Cmd|$ touch ~/.local/bin/bwrap-imv
$ chmod 0700 ~/.local/bin/bwrap-imv}}

Use {{Ic|file}} to determine the file type of {{Path|/usr/bin/imv}}:

{{Cmd|$ file /usr/bin/imv
/usr/bin/imv: POSIX shell script, ASCII text executable}}

Since it is just a shell script, we can use {{Ic|less}} to view it:

{{Cmd|$ less /usr/bin/imv}}

{{Cat|/usr/bin/imv|#!/bin/sh
if [ -n "${WAYLAND_DISPLAY}" ]; then
  exec /usr/libexec/imv-wayland "$@"
else
  exec /usr/libexec/imv-x11 "$@"
fi}}

Since we are assuming Wayland only we can just skip to
{{Path|/usr/libexec/imv-wayland}}.  Run {{Ic|file}} on it:

{{Cmd|$ file /usr/libexec/imv-wayland
/usr/libexec/imv-wayland: ELF 64-bit LSB pie executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-musl-x86_64.so.1, stripped}}

It is an
[https://en.wikipedia.org/wiki/Executable_and_Linkable_Format Executable and Linkable Format (ELF)]
file.  So we know we need the ELF interpreter
{{Path|/lib/ld-musl-x86_64.so.1}}.  We also know we need
{{Path|/usr/libexec/imv-wayland}}, since it has to know where the command
is located.

As the argument to {{Ic|/usr/libexec/imv-wayland}}, put
{{Ic|"${1:-./}"}}, this will pass '''only''' the first argument and if
there is none, will default to {{Path|./}}, the current directory.  We
will also need {{Ic|--ro-bind "${1:-./}" "$(realpath "${1:-./}")" \}},
since we are not passing the whole filesystem.  This will get the
absolute pathname using {{Ic|realpath}}, so you can pass a relative
argument and still bind the argument:
 --ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
 /usr/libexec/imv-wayland "${1:-./}"

{{Warning|If you don't pass anything and it defaults to the current directory, it will have '''everything''' under that directory shown to {{Ic|imv}}, recursively.}}
{{Todo|How can you pass 2+ arguments?}}

Find necessary shared libraries, except ones loaded at runtime:

{{Cmd|$ ldd /usr/libexec/imv-wayland}}

It outputs a lot of things but we only need a few; the directory path of
the majority {{Path|/usr/lib/*}} and the 4 paths that start with
{{Path|/lib/*}}.  Filter the output to see those clearer:

{{Cmd|$ ldd /usr/libexec/imv-wayland {{!}} grep ' /lib/'}}

In total:
 --ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
 --ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
 --ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
 --ro-bind /lib/libz.so.1 /lib/libz.so.1 \
 --ro-bind /usr/lib/ /usr/lib/ \

{{Note|It is not worth the time to limit {{Path|/usr/lib/*}}, the churn is too great.}}

{{Warning|The {{Ic|ldd}} manpage talks about some security implications.  It may not apply since they seem to be talking about glibc and {{Pkg|musl-utils|arch=}} makes {{Path|/lib/ld-musl-x86_64.so.1}} ldd [https://git.alpinelinux.org/aports/tree/main/musl/APKBUILD#n105].  Is this something to worry about?}}

Since this is a shell script, lets use a helpful command:
 set -u
if the shell tries to expand an unset parameter, it will error (with a
few exceptions).

Since this is for a GUI [[Wayland]] program, so lets also add some prerequisites:

{{Note|Make sure you have dealt with [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]].}}

 --setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
for determining the directory for the wayland socket;
 --setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
for determining the socket;
  --ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
mount readonly.

Lets also add some nice to haves:
 --unshare-all \
will create a new user/ipc/pid/net/utc namespaces and try to create a
new cgroup namespace if possible;
 --new-session
will create a new terminal session for the sandbox, disconnecting from
the controlling terminal so for example it can't inject input into the
terminal;
  --die-with-parent
will ensure child process ({{Ic|imv-wayland}} in this case) dies when
{{Ic|bwrap}} parent dies.

We might also have a {{Path|config}} file:
 --ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
this will add your local config to {{Ic|imv}} if you have one and if not
will still continue.

Pass {{Path|"$XDG_CONFIG_HOME"}} to sandbox:
 --setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
but this isn't always defined, so lets fallback to the
[https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory]
default:
 XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
this will use {{Path|"$XDG_CONFIG_HOME"}} if it's set, otherwise
fallback to the default of {{Path|"$HOME/.config"}}.

 --ro-bind /bin/sh /bin/sh \
Needed to use {{Path|config}} and have various information in the window
title.

{{Todo|This was found using: [[Bubblewrap#Can't_find_what_path_is_missing]], any better way?}}

{{Path|~/.local/bin/bwrap-imv}} now looks like:

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

/usr/bin/bwrap \
  --unshare-all \
  --new-session \
  --die-with-parent \
  --setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
  --setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
  --setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
  --ro-bind /bin/sh /bin/sh \
  --ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
  --ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
  --ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
  --ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
  --ro-bind /lib/libz.so.1 /lib/libz.so.1 \
  --ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
  --ro-bind /usr/lib/ /usr/lib/ \
  --ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
  --ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
  /usr/libexec/imv-wayland "${1:-./}"}}

Now lets run {{Ic|bwrap-imv}}, go into a directory with an image:

{{Cmd|$ bwrap-imv IMAGE
sh: eval: line 0: can't create /dev/null: nonexistent directory
...
sh: eval: line 0: can't create /dev/null: nonexistent directory
xkbcommon: ERROR: failed to add default include path /usr/share/X11/xkb
Assertion failed: keyboard->context (../src/keyboard.c: imv_keyboard_create: 20)}}

Add:
  --ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
to {{Ic|bwrap-imv}}.  [https://en.wikipedia.org/wiki/X_keyboard_extension XKB]
is a keyboard keymap support library.

After adding the above, run it again:

{{Cmd|$ bwrap-imv IMAGE
sh: eval: line 0: can't create /dev/null: nonexistent directory
...
sh: eval: line 0: can't create /dev/null: nonexistent directory
libEGL warning: wayland-egl: could not open /dev/dri/renderD128 (No such file or directory)}}

Add:
 --dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
and run again:

{{Cmd|$ bwrap-imv IMAGE
libEGL warning: wayland-egl: drmGetMagic failed}}

 --ro-bind /sys/dev/char/ /sys/dev/char/ \
Access to character devices.

{{Todo|This was found using: [[Bubblewrap#Can't_find_what_path_is_missing]], any better way?}}

 --ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
Access to PCI resources.

{{Todo|This was found using: [[Bubblewrap#Can't_find_what_path_is_missing]], any better way?}}

 --clearenv \
Finally we can unset all environment variables, except for
{{Path|"$PWD"}} and any we set with {{Ic|--setenv}}.

Now {{Ic|imv}} should show images and your {{Path|config}} file should
work (if you have one).  If you do not use commands, the finished
{{Path|~/.local/bin/bwrap-imv}} should look like:

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"

/usr/bin/bwrap \
  --unshare-all \
  --new-session \
  --die-with-parent \
  --clearenv \
  --setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
  --setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
  --setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
  --ro-bind /bin/sh /bin/sh \
  --dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
  --ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
  --ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
  --ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
  --ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
  --ro-bind /lib/libz.so.1 /lib/libz.so.1 \
  --ro-bind /sys/dev/char/ /sys/dev/char/ \
  --ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
  --ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
  --ro-bind /usr/lib/ /usr/lib/ \
  --ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
  --ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
  --ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
  /usr/libexec/imv-wayland "${1:-./}"}}

If you do use commands however, you will notice it is only showing
[https://en.wikipedia.org/wiki/Substitute_character substitute characters].

{{Tip|Commands in {{Ic|imv}} are entered by pressing {{Ic|:}}.}}

If you try to use a command it will say:

 Fontconfig error: Cannot load default config file: No such file: (null)

Look at the {{Ic|fonts-conf}} manpage (which is from
{{Pkg|fontconfig-doc|arch=}}) we see that {{Path|/etc/fonts/}} is the system
font configuration directory and
{{Path|"${XDG_CONFIG_HOME}/fontconfig/"}} is the per-user configuration
directory.  {{Path|"${XDG_CONFIG_HOME}/fontconfig/"}} is added with
{{Ic|--ro-bind-try}} so it doesn't have to exist:
 --ro-bind /etc/fonts/ /etc/fonts/ \
 --ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${XDG_CONFIG_HOME}/fontconfig/" \

The default directories scanned for font files are
{{Path|/usr/share/fonts/}} and {{Path|"${XDG_DATA_HOME}/fonts/"}}.
{{Path|"${XDG_DATA_HOME}/fonts/"}} added with {{Ic|--ro-bind-try}}:
 --ro-bind /usr/share/fonts/ /usr/share/fonts/ \
 --ro-bind-try "${XDG_DATA_HOME}/fonts/" "${XDG_DATA_HOME}/fonts/" \

Pass {{Path|"$XDG_DATA_HOME"}} to sandbox:
 --setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
just like for {{Path|"$XDG_CONFIG_HOME"}}, this isn't always defined, so
fallback to
[https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory]
default:
 XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
use {{Path|"$XDG_DATA_HOME"}} if set, else use {{Path|"$HOME/.local/share"}}.

The user cache of font information is also needed, by default
{{Path|"${XDG_CACHE_HOME}/fontconfig/"}}:
 --bind-try "${XDG_CACHE_HOME}/fontconfig/" "${XDG_CACHE_HOME}/fontconfig/" \

Pass {{Path|"$XDG_CACHE_HOME"}} to sandbox:
 --setenv XDG_CACHE_HOME "$XDG_CACHE_HOME" \
just like for {{Path|"$XDG_CONFIG_HOME"}}, this isn't always defined, so
fallback to
[https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory]
default:
 XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"
use {{Path|"$XDG_CACHE_HOME"}} if set, else use {{Path|"$HOME/.cache"}}.

 --ro-bind /usr/share/icu/ /usr/share/icu/ \
Is also needed or when you do {{Ic|:<backspace>}} it will terminate the
process.  ICU provides Unicode and Globalization support.

{{Todo|This was found using: [[Bubblewrap#Can't_find_what_path_is_missing]], any better way?}}

The updated {{Path|~/.local/bin/bwrap-imv}} should look like this:

{{Cat|~/.local/bin/bwrap-imv|#!/bin/sh

# imv wrapped in bwrap.

set -u

XDG_CACHE_HOME{{=}}"${XDG_CACHE_HOME:-$HOME/.cache}"
XDG_CONFIG_HOME{{=}}"${XDG_CONFIG_HOME:-$HOME/.config}"
XDG_DATA_HOME{{=}}"${XDG_DATA_HOME:-$HOME/.local/share}"

/usr/bin/bwrap \
  --unshare-all \
  --new-session \
  --die-with-parent \
  --clearenv \
  --setenv WAYLAND_DISPLAY "$WAYLAND_DISPLAY" \
  --setenv XDG_CACHE_HOME "$XDG_CACHE_HOME" \
  --setenv XDG_CONFIG_HOME "$XDG_CONFIG_HOME" \
  --setenv XDG_DATA_HOME "$XDG_DATA_HOME" \
  --setenv XDG_RUNTIME_DIR "$XDG_RUNTIME_DIR" \
  --ro-bind /bin/sh /bin/sh \
  --dev-bind /dev/dri/renderD128 /dev/dri/renderD128 \
  --ro-bind /etc/fonts/ /etc/fonts/ \
  --bind-try "${XDG_CACHE_HOME}/fontconfig/" "${XDG_CACHE_HOME}/fontconfig/" \
  --ro-bind-try "${XDG_CONFIG_HOME}/fontconfig/" "${XDG_CONFIG_HOME}/fontconfig/" \
  --ro-bind-try "${XDG_CONFIG_HOME}/imv/config" "${XDG_CONFIG_HOME}/imv/config" \
  --ro-bind-try "${XDG_DATA_HOME}/fonts/" "${XDG_DATA_HOME}/fonts/" \
  --ro-bind /lib/ld-musl-x86_64.so.1 /lib/ld-musl-x86_64.so.1 \
  --ro-bind /lib/libblkid.so.1 /lib/libblkid.so.1 \
  --ro-bind /lib/libmount.so.1 /lib/libmount.so.1 \
  --ro-bind /lib/libz.so.1 /lib/libz.so.1 \
  --ro-bind /sys/dev/char/ /sys/dev/char/ \
  --ro-bind /sys/devices/pci0000:00/ /sys/devices/pci0000:00/ \
  --ro-bind "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" "${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" \
  --ro-bind /usr/lib/ /usr/lib/ \
  --ro-bind /usr/libexec/imv-wayland /usr/libexec/imv-wayland \
  --ro-bind /usr/share/X11/xkb/ /usr/share/X11/xkb/ \
  --ro-bind /usr/share/fonts/ /usr/share/fonts/ \
  --ro-bind /usr/share/icu/ /usr/share/icu/ \
  --ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
  /usr/libexec/imv-wayland "${1:-./}"}}

==== See what exists in the sandbox ====

Finally test what all is allowed by replacing
{{Ic|/usr/libexec/imv-wayland "${1:-./}"}} with {{Ic|/bin/sh}} and
adding {{Ic|--ro-bind /bin/ /bin/ \}}.  Check around and see what the
filesystem is like:

{{Cat|~/.local/bin/bwrap-imv|  ...
  --ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
  --ro-bind /bin/ /bin/ \
  /bin/sh}}

Invoke {{Ic|bwrap-imv}}:

{{Cmd|$ bwrap-imv IMAGE}}

Show what environment variables are active:

{{Cmd|$ printenv}}

See what directories are at root:

{{Cmd|$ ls -la /
... bin
... dev
... etc
... home
... lib
... sys
... tmp
... usr}}

{{Ic|exit}} when done:

{{Cmd|$ exit}}

Do not forget to change it back:

{{Cat|~/.local/bin/bwrap-imv|  ...
  --ro-bind "${1:-./}" "$(realpath "${1:-./}")" \
  /usr/libexec/imv-wayland "${1:-./}"}}

All done with a basic {{Ic|bwrap}} wrapper.

=== Seccomp ===

{{Expand|}}

== .desktop integration ==

{{Obsolete|This should probably be documented in [[Default_applications]] and linked here.  Nothing is unique in using with {{Ic|bwrap}}.}}

{{Note|This section is also using {{Pkg|imv|arch=}} as the example.}}

[https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html XDG Desktop Entry Specification]
are a set of standards describing how a particular program is to be
launched, how it appears in menus, etc.

The default ''.desktop'' file for {{Ic|imv}} is at
{{Path|/usr/share/applications/imv.desktop}}.  Move it to
{{Path|"${XDG_DATA_HOME}/applications/bwrap-imv.desktop"}}.

Only 3 options will need to be changed: Name/Name[en_US], what shows up
in the application menu in a graphical file manager (if you have one
installed); Exec, program to execute:

{{Cat|"${XDG_DATA_HOME}/applications/bwrap-imv.desktop"|...<nowiki>
Name=bwrap-imv
Name[en_US]=bwrap-imv
Exec=bwrap-imv %F
</nowiki>...}}

The program {{Ic|xdg-open}} (from the {{Pkg|xdg-utils|arch=}} package) can be
used to open files based on the [https://en.wikipedia.org/wiki/MIME MIME]
type + corresponding entry in
{{Path|"${XDG_CONFIG_HOME}/mimeapps.list"}} and
{{Path|"${XDG_DATA_HOME}/applications/mimeinfo.cache"}}.

Install {{Pkg|desktop-file-utils|arch=}} if it is not installed already, it
comes with two commands that are needed {{Ic|desktop-file-validate}} and
{{Ic|update-desktop-database}}:

{{Cmd|# apk add desktop-file-utils}}

=== Validate ===

It is a good idea to validate {{Ic|imv.desktop}} using
{{Ic|desktop-file-validate}}:

{{Cmd|$ desktop-file-validate "${XDG_DATA_HOME}/applications/bwrap-imv.desktop"}}

=== Update database ===

This will make entries in {{Path|"${XDG_DATA_HOME}/applications/"}} take
precedence over system-wide files ({{Path|/usr/share/applications/}}).
However {{Path|"${XDG_CONFIG_HOME}/mimeapps.list"}} has precedence over
both.

Updating the database, will create
{{Path|"${XDG_DATA_HOME}/applications/mimeinfo.cache"}}:

{{Cmd|$ update-desktop-database "${XDG_DATA_HOME}/applications"}}

== Troubleshooting ==

=== Can't find what path is missing ===

If all else fails start broad and work toward narrowing.  See if
{{Ic|bwrap}} works with the program at all:

{{Cmd|$ bwrap \
  --dev-bind / / PROGRAM}}

If that works start to narrow:

{{Cmd|$ bwrap \
  --ro-bind /bin/ /bin/ \
  --dev-bind /dev/ /dev/ \
  --ro-bind /lib/ /lib/ \
  --ro-bind /sys/ /sys/ \
  --ro-bind /usr/ /usr/ \
  PROGRAM}}

Keep going till you have narrowed as much as possible.

== See also ==

* [[Bubblewrap/Examples]]
* [https://wiki.archlinux.org/title/Bubblewrap ArchWiki: Bubblewrap]
** [https://wiki.archlinux.org/title/Bubblewrap/Examples ArchWiki: Bubblewrap/Examples]
* [https://wiki.archlinux.org/title/Desktop_entries ArchWiki: Desktop entries (*.desktop files)]

[[Category:Desktop]]
[[Category:Security]]