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