# lockings

lockings is a simple sandbox manager written in Python that uses [bubblewrap](https://github.com/containers/bubblewrap) and [xdg-dbus-proxy](https://github.com/flatpak/xdg-dbus-proxy). It allows the creation of sandboxes using a JSON file, with a simple permission system. It generates "launcher" shell scripts which launch the sandboxed program, thus increasing customizability.

## quick start

Clone the repository on your machine and run the `lockings` script. Keep reading below to learn how to use it.

Lockings itself has no dependencies aside from Python, however, the launcher scripts generated by it require `bubblewrap`, and, if using the dbus-proxy permission, `xdg-dbus-proxy` as well.

## configuration

Configuration is done through a JSON file located at `~/.config/lockings/config.json`. If you'd like, you can use a different path by passing it as an argument (`lockings ~/some/path/config.json`).

The default configuration looks like this:
```json
{
    "sandboxes_path": "/home/user/.sandboxes",
    "scripts_path": "/home/user/.local/bin",
    "sandboxes": []
}
```

The `sandboxes_path` is the directory where the sandboxed "jail" home folders will be created. Each program will see its own "artificial" home folder.

The `scripts_path` is the directory where the automatically generated shell scripts will be dropped by lockings. These shell scripts launch the sandboxed program - lockings itself never actually launches anything.

The `sandboxes` property is an array of an object that follows the following structure:
```
{
    "name": "name of the sandbox",
    "bin": "the binary of the program which you want to sandbox",
    "permissions": [ list of permissions, check out the "permissions" section below for more info ]
}
```

Here is an example configuration which has a sandbox for Mozilla Firefox:
```json
{
    "sandboxes_path": "/home/user/.sandboxes",
    "scripts_path": "/home/user/.local/bin",
    "sandboxes": [
        {
            "name": "firefox",
            "bin": "firefox",
            "permissions": [
                "net",
                "x11",
                "sys",
                "dbus-proxy"
            ]
        }
    ]
}
```

## permissions

Currently, the following permissions are implemented:
| Permission | Description |
| --- | --- |
| net | Network permission |
| x11 | Exposes the x11 socket. Please note that [x11 is a weak point for sandboxing, and thus wayland is recommended](https://wiki.archlinux.org/title/Bubblewrap#Sandboxing_X11) |
| sys | Exposes some subdirectories in `/sys` and `/dev/dri`. Especially useful for hardware accelerated programs. |
| microphone | Exposes the microphone in `/dev/snd` |
| share:[permission]:[host path]:[sandbox path] | Binds [host path] from the host to [sandbox path] in the sandbox. If [permission] is `r`, it will be bound as read-only. Useful for sharing files with the sandbox |
| dbus-proxy | Enables `xdg-dbus-proxy` and exposes the bus to the host. **This permission is required for all subsequent dbus-proxy- permissions.** |
| dbus-proxy-talk | Set the talk policy for the given name. Read the `xdg-dbus-proxy` manpage for more information. |
| dbus-proxy-own | Set the own policy for the given name. Read the `xdg-dbus-proxy` manpage for more information. |
| dbus-proxy-see | Set the see policy for the given name. Read the `xdg-dbus-proxy` manpage for more information. |
| dbus-proxy-call | Set the call policy for the given name. Read the `xdg-dbus-proxy` manpage for more information. |
| dbus-proxy-broadcast | Set the broadcast policy for the given name. Read the `xdg-dbus-proxy` manpage for more information. |