104 lines
52 KiB
Markdown
104 lines
52 KiB
Markdown
|
---
|
||
|
|
obj: application
|
||
|
|
repo: https://github.com/containers/bubblewrap
|
||
|
|
arch-wiki: https://wiki.archlinux.org//title/Bubblewrap
|
||
|
|
rev: 2025-01-09
|
||
|
|
---
|
||
|
|
|
||
|
|
# Bubblewrap
|
||
|
|
Bubblewrap is a lightweight sandbox application used by Flatpak and other container tools. It has a small installation footprint and minimal resource requirements. Notable features include support for cgroup/IPC/mount/network/PID/user/UTS namespaces and seccomp filtering. Note that bubblewrap drops all capabilities within a sandbox and that child tasks cannot gain greater privileges than its parent.
|
||
|
|
|
||
|
|
## Configuration
|
||
|
|
Bubblewrap can be called directly from the command-line and/or within shell scripts as part of a complex wrapper.
|
||
|
|
|
||
|
|
A no-op bubblewrap invocation is as follows:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
bwrap --dev-bind / / bash
|
||
|
|
```
|
||
|
|
|
||
|
|
This will spawn a Bash process which should behave exactly as outside a sandbox in most cases. If a sandboxed program misbehaves, you may want to start from the above no-op invocation, and work your way towards a more secure configuration step-by-step.
|
||
|
|
|
||
|
|
### Desktop entries
|
||
|
|
Leverage Bubblewrap within desktop entries:
|
||
|
|
- Bind as read-write the entire host `/` directory to `/` in the sandbox
|
||
|
|
- Re-bind as read-only the `/var` and `/etc` directories in the sandbox
|
||
|
|
- Mount a new devtmpfs filesystem to `/dev` in the sandbox
|
||
|
|
- Create a tmpfs filesystem over the sandboxed `/run` directory
|
||
|
|
- Disable network access by creating new network namespace
|
||
|
|
|
||
|
|
```ini
|
||
|
|
[Desktop Entry]
|
||
|
|
Name=nano Editor
|
||
|
|
Exec=bwrap --bind / / --dev /dev --tmpfs /run --unshare-net st -e nano -o . %f
|
||
|
|
Type=Application
|
||
|
|
MimeType=text/plain;
|
||
|
|
```
|
||
|
|
|
||
|
|
> **Note**: `--dev /dev` is required to write to `/dev/pty`
|
||
|
|
|
||
|
|
## Options
|
||
|
|
Usage: `bwrap [optiosn] [command]`
|
||
|
|
|
||
|
|
| Option | Description |
|
||
|
|
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
|
|
| `--args FD` | Parse nul-separated arguments from the given file descriptor. This option can be used multiple times to parse options from multiple sources. |
|
||
|
|
| `--argv0 VALUE` | Set `argv[0]` to the value VALUE before running the program |
|
||
|
|
| `--unshare-user` | Create a new user namespace |
|
||
|
|
| `--unshare-user-try` | Create a new user namespace if possible else skip it |
|
||
|
|
| `--unshare-ipc` | Create a new ipc namespace |
|
||
|
|
| `--unshare-pid` | Create a new pid namespace |
|
||
|
|
| `--unshare-net` | Create a new network namespace |
|
||
|
|
| `--unshare-uts` | Create a new uts namespace |
|
||
|
|
| `--unshare-cgroup` | Create a new cgroup namespace |
|
||
|
|
| `--unshare-cgroup-try` | Create a new cgroup namespace if possible else skip it |
|
||
|
|
| `--unshare-all` | Unshare all possible namespaces. Currently equivalent with: `--unshare-user-try --unshare-ipc --unshare-pid --unshare-net --unshare-uts --unshare-cgroup-try` |
|
||
|
|
| `--share-net` | Retain the network namespace, overriding an earlier `--unshare-all` or `--unshare-net` |
|
||
|
|
| `--userns FD` | Use an existing user namespace instead of creating a new one. The namespace must fulfil the permission requirements for `setns()`, which generally means that it must be a descendant of the currently active user namespace, owned by the same user. |
|
||
|
|
| `--disable-userns` | Prevent the process in the sandbox from creating further user namespaces, so that it cannot rearrange the filesystem namespace or do other more complex namespace modification. |
|
||
|
|
| `--assert-userns-disabled` | Confirm that the process in the sandbox has been prevented from creating further user namespaces, but without taking any particular action to prevent that. For example, this can be combined with --userns to check that the given user namespace has already been set up to prevent the creation of further user namespaces. |
|
||
|
|
| `--pidns FD` | Use an existing pid namespace instead of creating one. This is often used with `--userns`, because the pid namespace must be owned by the same user namespace that bwrap uses. |
|
||
|
|
| `--uid UID` | Use a custom user id in the sandbox (requires `--unshare-user`) |
|
||
|
|
| `--gid GID` | Use a custom group id in the sandbox (requires `--unshare-user`) |
|
||
|
|
| `--hostname HOSTNAME` | Use a custom hostname in the sandbox (requires `--unshare-uts`) |
|
||
|
|
| `--chdir DIR` | Change directory to DIR |
|
||
|
|
| `--setenv VAR VALUE` | Set an environment variable |
|
||
|
|
| `--unsetenv VAR` | Unset an environment variable |
|
||
|
|
| `--clearenv` | Unset all environment variables, except for PWD and any that are subsequently set by `--setenv` |
|
||
|
|
| `--lock-file DEST` | Take a lock on DEST while the sandbox is running. This option can be used multiple times to take locks on multiple files. |
|
||
|
|
| `--sync-fd FD` | Keep this file descriptor open while the sandbox is running |
|
||
|
|
| `--perms OCTAL` | This option does nothing on its own, and must be followed by one of the options that it affects. It sets the permissions for the next operation to OCTAL. Subsequent operations are not affected: for example, `--perms 0700 --tmpfs /a --tmpfs /b` will mount `/a` with permissions `0700`, then return to the default permissions for `/b`. Note that `--perms` and `--size` can be combined: `--perms 0700 --size 10485760 --tmpfs /s` will apply permissions as well as a maximum size to the created tmpfs. |
|
||
|
|
| `--size BYTES` | This option does nothing on its own, and must be followed by `--tmpfs`. It sets the size in bytes for the next tmpfs. For example, `--size 10485760 --tmpfs /tmp` will create a tmpfs at `/tmp` of size 10MiB. Subsequent operations are not affected. |
|
||
|
|
| `--bind SRC DEST` | Bind mount the host path SRC on DEST |
|
||
|
|
| `--bind-try SRC DEST` | Equal to `--bind` but ignores non-existent SRC |
|
||
|
|
| `--dev-bind SRC DEST` | Bind mount the host path SRC on DEST, allowing device access |
|
||
|
|
| `--dev-bind-try SRC DEST` | Equal to `--dev-bind` but ignores non-existent SRC |
|
||
|
|
| `--ro-bind SRC DEST` | Bind mount the host path SRC readonly on DEST |
|
||
|
|
| `--ro-bind-try SRC DEST` | Equal to `--ro-bind` but ignores non-existent SRC |
|
||
|
|
| `--remount-ro DEST` | Remount the path DEST as readonly. It works only on the specified mount point, without changing any other mount point under the specified path |
|
||
|
|
| `--overlay-src SRC` | This option does nothing on its own, and must be followed by one of the other overlay options. It specifies a host path from which files should be read if they aren't present in a higher layer. |
|
||
|
|
| `--overlay RWSRC WORKDIR DEST`, `--tmp-overlay DEST`, `--ro-overlay DEST` | Use overlayfs to mount the host paths specified by `RWSRC` and all immediately preceding `--overlay-src` on `DEST`. `DEST` will contain the union of all the files in all the layers. With `--overlay` all writes will go to `RWSRC`. Reads will come preferentially from `RWSRC`, and then from any `--overlay-src` paths. `WORKDIR` must be an empty directory on the same filesystem as `RWSRC`, and is used internally by the kernel. With `--tmp-overlay` all writes will go to the tmpfs that hosts the sandbox root, in a location not accessible from either the host or the child process. Writes will therefore not be persisted across multiple runs. With `--ro-overlay` the filesystem will be mounted read-only. This option requires at least two `--overlay-src` to precede it. |
|
||
|
|
| `--proc DEST` | Mount procfs on DEST |
|
||
|
|
| `--dev DEST` | Mount new devtmpfs on DEST |
|
||
|
|
| `--tmpfs DEST` | Mount new tmpfs on DEST. If the previous option was `--perms`, it sets the mode of the tmpfs. Otherwise, the tmpfs has mode `0755`. If the previous option was `--size`, it sets the size in bytes of the tmpfs. Otherwise, the tmpfs has the default size. |
|
||
|
|
| `--mqueue DEST` | Mount new mqueue on DEST |
|
||
|
|
| `--dir DEST` | Create a directory at DEST. If the directory already exists, its permissions are unmodified, ignoring `--perms` (use `--chmod` if the permissions of an existing directory need to be changed). If the directory is newly created and the previous option was `--perms`, it sets the mode of the directory. Otherwise, newly-created directories have mode `0755`. |
|
||
|
|
| `--file FD DEST` | Copy from the file descriptor FD to DEST. If the previous option was `--perms`, it sets the mode of the new file. Otherwise, the file has mode `0666` (note that this is not the same as `--bind-data`). |
|
||
|
|
| `--bind-data FD DEST` | Copy from the file descriptor FD to a file which is bind-mounted on DEST. If the previous option was `--perms`, it sets the mode of the new file. Otherwise, the file has mode `0600` (note that this is not the same as `--file`). |
|
||
|
|
| `--ro-bind-data FD DEST` | Copy from the file descriptor FD to a file which is bind-mounted read-only on DEST. If the previous option was `--perms`, it sets the mode of the new file. Otherwise, the file has mode `0600` (note that this is not the same as `--file`). |
|
||
|
|
| `--symlink SRC DEST` | Create a symlink at DEST with target SRC. |
|
||
|
|
| `--chmod OCTAL PATH` | Set the permissions of PATH, which must already exist, to OCTAL. |
|
||
|
|
| `--seccomp FD` | Load and use seccomp rules from FD. The rules need to be in the form of a compiled cBPF program, as generated by seccomp_export_bpf. If this option is given more than once, only the last one is used. Use `--add-seccomp-fd` if multiple seccomp programs are needed. |
|
||
|
|
| `--add-seccomp-fd FD` | Load and use seccomp rules from FD. The rules need to be in the form of a compiled cBPF program, as generated by seccomp_export_bpf. This option can be repeated, in which case all the seccomp programs will be loaded in the order given (note that the kernel will evaluate them in reverse order, so the last program on the bwrap command-line is evaluated first). All of them, except possibly the last, must allow use of the PR_SET_SECCOMP prctl. This option cannot be combined with `--seccomp`. |
|
||
|
|
| `--exec-label LABEL` | Exec Label from the sandbox. On an SELinux system you can specify the SELinux context for the sandbox process(s). |
|
||
|
|
| `--file-label LABEL` | File label for temporary sandbox content. On an SELinux system you can specify the SELinux context for the sandbox content. |
|
||
|
|
| `--block-fd FD` | Block the sandbox on reading from FD until some data is available. |
|
||
|
|
| `--userns-block-fd FD` | Do not initialize the user namespace but wait on FD until it is ready. This allow external processes (like newuidmap/newgidmap) to setup the user namespace before it is used by the sandbox process. |
|
||
|
|
| `--info-fd FD` | Write information in JSON format about the sandbox to FD. |
|
||
|
|
| `--json-status-fd FD` | Multiple JSON documents are written to FD, one per line. |
|
||
|
|
| `--new-session` | Create a new terminal session for the sandbox (calls `setsid()`). This disconnects the sandbox from the controlling terminal which means the sandbox can't for instance inject input into the terminal. Note: In a general sandbox, if you don't use `--new-session`, it is recommended to use seccomp to disallow the `TIOCSTI` ioctl, otherwise the application can feed keyboard input to the terminal which can e.g. lead to out-of-sandbox command execution. |
|
||
|
|
| `--die-with-parent` | Ensures child process (COMMAND) dies when bwrap's parent dies. Kills (SIGKILL) all bwrap sandbox processes in sequence from parent to child including COMMAND process when bwrap or bwrap's parent dies. |
|
||
|
|
| `--as-pid-1` | Do not create a process with PID=1 in the sandbox to reap child processes. |
|
||
|
|
| `--cap-add CAP` | Add the specified capability CAP, e.g. `CAP_DAC_READ_SEARCH`, when running as privileged user. It accepts the special value `ALL` to add all the permitted caps. |
|
||
|
|
| `--cap-drop CAP` | Drop the specified capability when running as privileged user. It accepts the special value `ALL` to drop all the caps. By default no caps are left in the sandboxed process. The `--cap-add` and `--cap-drop` options are processed in the order they are specified on the command line. Please be careful to the order they are specified. |
|