Oz is a sandboxing system targeting everyday workstation applications.
It acts as a wrapper around application executables for completely transparent user operations. It achieves process containment through the use of [Linux Namespaces](http://man7.org/linux/man-pages/man7/namespaces.7.html), [Seccomp filters](http://man7.org/linux/man-pages/man2/seccomp.2.html), [Capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html), and X11 restriction using [Xpra](https://xpra.org/). It has built-in support with automatic configuration of bridge mode networking and also support working with contained network environment using the built in connection forwarding proxy.
Please note that Oz is currently under major development and still at a very alpha stage. **As of this writting some features, like seccomp filters, are not yet available in the public master branch**. It is not intended for use in multi-users systems. Use it at your own risk!
# Installing
Due to the alpha nature of this project there currently is no package for easy installation.
## Prerequisites
Currently Oz only works and is only tested for Debian (>= jessie).
As of this writing it does **not** work in Ubuntu. While it has been minimally tested under Fedora,
there doesn't exist an RPM equivalent to `dpkg-divert` which allows to conveniantly wrap executables of existing program.
For seccomp filters you need at least kernel version 3.5.
It is highly recommend that you run it in conjunction with [grsecurity](https://grsecurity.net/).
Firstly you must launch the daemon utility either with the init script or manually:
```
$ sudo oz-daemon
```
Once the daemon is started you can transparently launch any applications for which you have enabled the profile.
This means Oz sandboxing will be used whether you launch your browser from gnome-shell or from the command line.
If you wish to run an executable outside of the sandbox simply call it with the `unsafe` suffix:
```
$ /usr/bin/evince.unsafe
```
# Advanced Usage Information
## Oz client commands
The `oz` executable acts as a client for the daemon when called directly. It provides a number of commands to interact with sandboxes.
* `profiles`: lists available profiles
* `launch <name>`: launches a sandbox for the given profile name, pass the `--noexec` flag to prevent execution of the default program
* `list`: lists the running sandboxes
* `kill <id>`: kills the sandbox with the given numerical id
* `kill all`: kills all running sandboxes
* `shell <id>`: enters a shell in a given sandbox, mostly useful for debugging
* `logs [-f]`: prints out the logs, pass `-f` to follow the output
## Oz-daemon configurations
In nearly every case the default configurations should be used, but for debugging and development purposes some flags are configurable inside of the `/etc/oz/oz.conf` file. You can view the current configuration by running the following command:
profile_dir : /var/lib/oz/cells.d # Directory containing the sandbox profiles
shell_path : /bin/bash # Path of the shell using when entering a sandbox
prefix_path : /usr # Prefix path containing the oz executables
sandbox_path : /srv/oz # Path of the sandboxes base
bridge_mac : 6A:A8:2E:56:E8:9C # MAC Address of the bridge interface
divert_suffix : unsafe # Suffix using for dpkg-divert of application executables
nm_ignore_file : /etc/NetworkManager/conf.d/oz.conf # Path to the NetworkManager ignore config file, disables the warning if empty
use_full_dev : false # Give sandboxes full access to devices instead of a restricted set
allow_root_shell: false # Allow entering a sandbox shell as root
log_xpra : false # Log output of Xpra
environment_vars: [USER USERNAME LOGNAME LANG LANGUAGE _] # Default environment variables passed to sandboxes
```
## Profiles
Profiles files are simple JSON files located, by default, in `/var/lib/oz/cells.d`. They must include at minimum the path to the executable to be sandboxed using the `path` key. It may also define more executables to run under the same sandbox under the `paths` array; in which case a `name` key must also be specified. Some other base options are also available:
* `allow_files`: whether to allow binding of files passed as arguments inside the sandbox
### Xserver
This section defines the configuration of the Xserver (namely [xpra](https://www.xpra.org/)).
Possible options are:
* `enabled`: whether or not to use the Xserver
* `enable_tray`: whether or not to enable the Xpra tray diagnostic menu/tray (This requires the `[Top Icons](https://extensions.gnome.org/extension/495/topicons/)` gnome-shell extension!)
* `tray_icon`: the path to an icon file to use for the to tray menu
* `window_icon`: the path to an icon file to use for windows
* `audio_mode`: one of [none|speaker|full] selects the audio passthrough mode (defaults: none)
* `EnableNotifications`: enable passing of dbus notifications
### Network configs
The network can be configured in one of three different ways: host, bridge, and empty namespace, as defined in the `type` key.
* `empty`: the sandbox will live with an empty network namespace (ie: only `lo` interface)
* `bridge`: the sandbox will have its own network namespace and use *veth* to join a bridge named `oz0`
* `host`: the sandbox will share the network namespace with the host (usually not desirable)
#### Port Forwarding config
Oz allows you to forward ports on the loopback interface between the host and the sandbox.
This is useful so that you can expose some services (such as a socks proxy) to the sandbox without giving the sandbox any real network access.
You may define as many forwards, called `sockets` in the configuration, as you like.
Each socket configuration contains the following keys:
* `type`: One of `client`, or `server`, this defines whether to connect (*client*) or listen (*server*) on the host side
* `proto`: One of `tcp`, or `udp`, or `socket`
* `port`: The network port number to connect to
* `destination`: *Optional*, in client mode this is the address to connect to, in server mode this is the address to bind to. Defaults to *localhost*.
### Bind list
There exists two types of *bindlists*: a whitelist and a blacklist.
The whitelist allows you to bring files from the host into the sandbox; while the blacklist allows you to remove access to specific files or directories.
Both of these types support a few ways of resolving files:
* In the path by using the `${PATH}` prefix.
* In the home by using the `${HOME}` prefix.
* By replacing `${UID}` with the user numeric id.
* By replacing `${USER}` with the user login.
* By path globbing using the `*` wildcard.
The whitelist carries some extra caveats:
* If the original file does not exist and is inside the home, an empty directory will be created in its place if "can_create" is set.
* If the original file is a symlink it is resolved, but the target remains the same.
* An item can be marked as read only with the `readonly` boolean key.
* Files that are passed as arguments to the command are automatically added to the whitelist.
### Environment
One can specify which environment variables to pass by defining them in this list.
It is also possible to define static variables by also defining a `value` attribute in the list item.
### Example
You can find a list of existing profiles in the repository. Here is the porfile for running the `torbrowser-launcher`:
