README.md

   1 # BubbleBox: Simple Application Sandboxing
   2
   3 ## Introduction
   4
   5 This is the documentation of [BubbleBox](https://www.ralfj.de/projects/bubblebox), a
   6 tool to easily sandbox Linux applications.
   7
   8 The primary use-case for BubbleBox is running applications that you do not trust enough
   9 to give them full access to your home directory, and in particular the secret keys stored there.
  10 BubbleBox is based on [bubblewrap] and [xdg-dbus-proxy] which do all of the heavy lifting.
  11
  12 The goals of this project are similar to [firejail], but I found firejail's configuration to be extremely hard to maintain and debug.
  13 BubbleBox is meant for people that are comfortable editing its Python source code to adjust it to their needs;
  14 if you are looking for something with a more out-of-the-box experience, try [bubblejail].
  15
  16 [firejail]: https://firejail.wordpress.com/
  17 [bubblejail]: https://github.com/igo95862/bubblejail
  18 [bubblewrap]: https://github.com/containers/bubblewrap
  19 [xdg-dbus-proxy]: https://github.com/flatpak/xdg-dbus-proxy
  20
  21 ## Usage
  22
  23 The typical way to use BubbleBox is to create a new "jail" script in the BubbleBox source folder.
  24 For instance, if you want a "gamejail" that you can use to run games, create a file `gamejail`
  25 in a BubbleBox checkout with contents like this:
  26
  27 ```python
  28 #!/bin/python3
  29 from bubblebox import *
  30
  31 bubblebox(
  32   profiles.DESKTOP("gamejail"),
  33   dbus_proxy_flags("--own=com.steampowered.*"),
  34
  35   home_access({
  36     ".steam": Access.Write,
  37   }),
  38 )
  39 ```
  40
  41 Then add a symlink to this file somewhere to your PATH, and now you can use `gamejail <application>`
  42 to run arbitrary games inside the BubbleBox.
  43
  44 ### Configuration directives
  45
  46 A BubbleBox sandbox is configured by passing a list of directives to the
  47 `bubblebox` functions that declare things the sandbox has access to. Everything
  48 else is blocked by default.
  49
  50 These directives are basically lists of bubblewrap and xdg-dbus-proxy flags,
  51 but BubbleBox provides some convenience functions
  52 to allow higher-level configuration and to share common patterns.
  53
  54 The `profiles.py` file contains some useful directives that are needed by most applications:
  55 - `profiles.DEFAULT` adds the basic flags to isolate the sandbox from the environment
  56   by unsharing all namespaces except for the network.
  57   This profile gives access to `/usr`, `/sys`, and `/etc` and also creates a
  58   stub file system inside the sandbox that is basically always required, such as
  59   an empty folder to serve as XDG_RUNTIME_DIR. It assumes a merged-usr setup,
  60   e.g. it will add `/bin` as a symlink to `/usr/bin`. It also gives read-only
  61   access to some files in the home directory that are often needed to make a
  62   basic shell work: `.bashrc`, `.bash_aliases`, `.profile` and the `bin`
  63   directory.
  64 - `profiles.DESKTOP("name")` is intended to make GUI applications work. It
  65   extends `DEFAULT` by providing access to DRI, X11, ALSA, Wayland, and
  66   PulseAudio. Furthermore, some GUI configuration files (`.XCompose`,
  67   fontconfig, and default mime-type associations) are made available to the
  68   sandbox. The `"name"` is used to create an XDG_RUNTIME_DIR that will be shared
  69   among all instances of this sandbox. This also sets up the D-Bus proxy and
  70   gives the application access to notifications, screen saver control, status
  71   icons, and the flatpak portals (however, actually using these portals is
  72   untested and would likely require further integration). Finally, it makes
  73   clicking on links inside the sandbox work properly if your default browser is
  74   Firefox.
  75
  76 I recommend looking at the sources in `default.py` to learn how to configure your
  77 own sandboxes. Here are the key directives to use:
  78 - `host_access` gives the sandbox read-only or read-write access to some part
  79   of the host file system. This is declared via nested Python dicts and supports
  80   glob expressions.
  81 - `home_access` works the same as `host_access` except all paths are relative
  82   to the home directory.
  83 - `bwrap_flags` allows passing flags directly to `bwrap`. This is rarely needed.
  84 - `dbus_proxy_flags` allows passing flags directly to `xdg-dbus-proxy`.
  85   This is the typical way to provide access to additional D-Bus names.
  86
  87 ## Source, License
  88
  89 You can find the sources in the
  90 [git repository](https://git.ralfj.de/bubblebox.git) (also available
  91 [on GitHub](https://github.com/RalfJung/bubblebox)). They are provided under the
  92 [GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) or (at your
  93 option) any later version of the GPL.  See the file `LICENSE-GPL2` for more
  94 details.
  95
  96 ## Contact
  97
  98 If you found a bug, or want to leave a comment, please
  99 [send me a mail](mailto:post-AT-ralfj-DOT-de).  I'm also happy about pull
 100 requests :)