terok-clearance 0.7.0

Shield clearance and desktop notifications for terok

terok-clearance

Live allow/deny prompts for the terok-shield firewall — desktop notifications, varlink hub, verdict daemon.

When a hardened terok container hits a blocked outbound destination, the operator sees a desktop notification with Allow and Deny buttons; the chosen verdict is written into the running container's nftables ruleset.

What is the clearance system

The clearance system is the operator-in-the-loop decision path for terok's egress firewall. It is built from a hub and verdict pair that talk over a varlink Unix socket and surface decisions through the freedesktop Notifications D-Bus interface:

sequenceDiagram
    participant C as Container
    participant S as terok-shield<br/>(nftables)
    participant H as clearance-hub
    participant U as Operator (desktop)
    participant V as clearance-verdict

    C->>S: outbound packet to api.example.com
    S-->>C: REJECT (default-deny)
    S->>H: blocked-connection event<br/>(NFLOG → varlink)
    H->>U: desktop notification<br/>"Allow api.example.com?"
    U->>H: clicks "Allow"
    H->>V: ApplyVerdict(allow, dest)
    V->>S: terok-shield allow api.example.com
    S-->>S: nft add element …
    S-->>C: subsequent packets pass

The hub and the verdict server are composed in-process by the per-container supervisor that terok-sandbox's OCI hook spawns — one supervisor (and therefore one hub socket) per container. The hub fans events out to whichever operator UIs are subscribed (the plain-terminal terok-clearance tool, the embedded terok-tui screen, a DbusNotifier listening on the session bus). The verdict server is the only piece that calls into the container's network namespace, so it sits behind the hub's authz boundary and keeps the privileged surface small.

What it provides

• Async-first Python API — create_notifier(), Notifier protocol, DbusNotifier, CallbackNotifier, NullNotifier
• Varlink hub — ClearanceHub, ClearanceClient, EventSubscriber for in-process subscribers (used by the TUI to render live verdicts)
• Multi-socket subscriber — MultiSocketSubscriber multiplexes every per-container hub socket under $XDG_RUNTIME_DIR/terok/clearance/ so a single UI sees the union of every supervisor's event stream
• Embeddable verdict server — VerdictServer for the per-container supervisor to compose alongside the hub
• Graceful degradation — NullNotifier is returned when no D-Bus session bus is available, so headless hosts can still run the rest of the stack

Where it sits in the stack

terok-clearance is the user-in-the-loop side-rail of the terok ecosystem. Above it, terok's TUI subscribes to every per-container hub socket to display verdicts in-band; on a desktop session the same events fire freedesktop popups. Below it, the verdict server reaches into terok-shield to mutate the running ruleset. Lifecycle is owned by terok-sandbox's per-container supervisor, which composes the hub and verdict server in-process for every container it watches.

The package is genuinely usable on its own — the notification API and the protocol abstractions are stable enough to sit at the heart of any desktop-driven IPC use case.

Requirements

• Linux with a D-Bus session bus (any desktop environment with a notification daemon) — the package degrades cleanly to a no-op notifier when no bus is reachable
• Python 3.12+

Installation

pip install terok-clearance

For most users this dependency is pulled in transitively by terok-sandbox's setup phase. Install it directly only when embedding the API in your own tooling.

Quick start

Send a notification

import asyncio
from terok_clearance import create_notifier

async def main():
    notifier = await create_notifier(app_name="terok")
    action_received = asyncio.Event()

    def on_action(nid, key):
        print(f"{nid}: {key}")
        action_received.set()

    notifier.on_action(on_action)

    nid = await notifier.notify(
        "Clearance request",
        "Task alpha wants access to api.github.com:443",
        actions={"allow": "Allow", "deny": "Deny"},
    )

    await action_received.wait()
    await notifier.close()

asyncio.run(main())

CLI tool (development / testing)

terok-clearance-notify "Title" "Body" --actions allow:Allow deny:Deny --wait

License

Apache-2.0 — see LICENSES/Apache-2.0.txt.