sandbox everything!
Go to file
hippoz 19c1c51aae
fix LICENSE
2022-06-06 20:47:11 +03:00
LICENSE fix LICENSE 2022-06-06 20:47:11 +03:00
README.md refactor code and add a readme 2022-06-06 20:45:02 +03:00
lockings refactor code and add a readme 2022-06-06 20:45:02 +03:00

README.md

lockings

lockings is a simple sandbox manager written in Python that uses bubblewrap and 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:

{
    "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:

{
    "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
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.