72 lines
3.6 KiB
Markdown
72 lines
3.6 KiB
Markdown
# 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. |
|