Plugin Trust & Isolation

← Security

• Twilio webhook validation — all webhook routes (/transcribe, /respond, /sms, /reader, /read, /say, /play, /conference) validate the X-Twilio-Signature header using your TWILIO_AUTH_TOKEN. If the token is not set (e.g. Discord-only or local dev), validation is skipped with a one-time warning.
• Path traversal protection — workspace file operations (save_file, read_file, archive_file, etc.) and self-improvement file operations validate that resolved paths stay within the expected root directory. Attempts to escape via ../ or absolute paths are blocked.
• Sandbox auth — each app process generates a random per-process auth key (secrets.token_urlsafe(32)) for sandbox container communication. Never committed to source.
• Docker socket — the app container needs /var/run/docker.sock mounted for sandbox management. This grants host Docker access; only run in trusted environments.
• VNC — when enabled, VNC ports are mapped to the host’s 127.0.0.1 only (not exposed on 0.0.0.0). Remote access requires an SSH tunnel to the host: ssh -NL 5901:localhost:5901 your-server.
• Secret key validation — the app warns on startup if FLASK_SECRET_KEY is set to a weak placeholder like change-me.

Plugin security

Plugins imported from external repos pass through multiple security gates before and during execution:

Subprocess isolation

IMPORTED plugins execute in isolated subprocesses — separate OS processes with no access to API keys, secrets, or the parent’s memory. The OS process boundary is the primary security guarantee, not Python-level tricks.

Architecture

flowchart LR
    subgraph Parent["Parent Process"]
        MT["MonitoredTool\n• call budget (10/msg)\n• governance (HIGH risk)\n• bridge.invoke()"]
        BR["Bridge\n• spawn subprocess\n• service caps callbacks\n• timeout → SIGKILL\n• PluginCapabilities (real)\n  – API keys ✓\n  – prax.settings ✓\n  – network access ✓"]
    end
    subgraph Sub["Plugin Subprocess"]
        HP["host.py\n• import plugin module\n• call tool.invoke()\n• CapsProxy\n  – http_get(url)\n  – build_llm()\n  – save_file()\n  – get_config()"]
        ENV["Env: PATH, HOME, LANG only\nNo API keys. No secrets.\nNo Docker socket."]
    end
    Parent <-->|"JSON-lines\non stdin/stdout"| Sub

When a plugin calls caps.http_get(url), the proxy in the subprocess serializes the call as a JSON-RPC message, sends it to the parent over stdout, and blocks. The parent — which holds the real API keys — makes the HTTP request and sends the result back. The plugin experiences a normal synchronous method call but never touches a credential.

What’s isolated

Capabilities proxy

Plugins access Prax services through a PluginCapabilities proxy. Every method is forwarded to the parent via JSON-RPC — the plugin never directly holds credentials or network connections:

Framework-enforced limits

These limits are enforced in the parent process (in MonitoredTool), outside the subprocess — the plugin cannot increase its own budget or disable enforcement:

Subprocess lifecycle

Defence-in-depth (in-process layers)

The following in-process guards remain active as a secondary defense. They are no longer the primary security boundary — the subprocess is — but they catch bugs in the bridge and provide redundancy:

Migration for plugin authors

If your plugin’s register() function accepts a parameter, it receives a PluginCapabilities instance (or a proxy that behaves identically in the subprocess). Use caps.http_get() instead of requests.get(), caps.build_llm() instead of importing the LLM factory, and caps.get_config("workspace_dir") instead of settings.workspace_dir. Zero-arg register() still works for backward-compatible built-in plugins.

BUILTIN and WORKSPACE plugins remain fully in-process with no overhead — subprocess isolation applies only to IMPORTED plugins from external repos.

Plugin trust tiers

Every plugin is tagged with a trust tier based on its origin:

Trust tiers are stored in registry.json and surfaced in plugin_list and plugin_status. Unknown plugins default to imported (least trust). Defined as PluginTrust enum in prax/plugins/registry.py.

Plugin lifecycle audit trail

All plugin lifecycle events are recorded as typed trace entries, searchable via search_trace:

Example queries:

search_trace(uid, "txt2presentation", type_filter="plugin_activate")
search_trace(uid, "security", type_filter="plugin_security_warn")