Plugin Trust & Isolation

← Security

• Twilio webhook validation — all Twilio routes (/transcribe, /respond, /sms, /reader, /read, /say, /play, /conference) validate the X-Twilio-Signature header using your TWILIO_AUTH_TOKEN (prax/blueprints/twilio_auth.py). If the token is not set (e.g. Discord-only or local dev), validation is skipped with a one-time warning — fail-open. Known gap (2026-09): it signs request.url, and behind the documented HTTPS ngrok tunnel Flask sees http://… (no forwarded-scheme handling), so with the token set every genuine Twilio request is rejected; see configuration.md → Twilio. The TeamWork webhook and the rest of /teamwork/*, /plugins/* and /api/users/* are checked by prax/blueprints/inbound_auth.py only when PRAX_API_KEY is set (X-API-Key or Authorization: Bearer, constant-time compare, 401 otherwise); unset — the default — they carry no inbound validation and the network perimeter is the only control (see configuration.md → TeamWork).
• 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 (safe_join). The Library layer does the same since 2026-09: _require_slug in prax/services/library_service.py accepts only a single path component for every model- or request-supplied space/notebook/slug (wiki notes, raw, outputs, archive; library_tasks and progress_service reuse it) and _assert_in_library checks the resolved path against the library root before any I/O. workspace_root()’s legacy fallback in prax/services/workspace_service.py fullmatches the id to one component and safe_joins it, and ensure_workspace refuses (_check_workspace_root_containment) a root whose realpath is outside WORKSPACE_DIR or inside another workspace’s git repository.
• Sandbox access — there is no per-process sandbox auth key. Local mode drives the container through the Docker socket (docker exec); remote mode uses the operator-set SANDBOX_DAEMON_TOKEN bearer (optional mTLS via SANDBOX_CLIENT_CERT/_KEY). The sandbox’s own ports (CDP :9223, noVNC :6080, clipboard :6090) are unauthenticated and published on 127.0.0.1 only by prax-sandbox’s compose.
• 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 — the manual-login browser flow (prax/services/browser_service.py) starts x11vnc on the Prax host with -listen 127.0.0.1 -nopw, so it is loopback-only and reachable remotely through an SSH tunnel (ssh -NL 5901:localhost:5901 your-server). No compose file publishes a VNC port; the sandbox desktop is noVNC on 127.0.0.1:6080 (prax-sandbox’s compose).
• 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 separate host subprocesses whose environment is stripped of API keys and whose memory is separate from the parent’s. The OS process boundary is the primary security guarantee, not Python-level tricks.

Known gap (2026-09): the environment is the only thing stripped. prax/plugins/bridge.py spawns python -m prax.plugins.host with env=_SAFE_ENV (PATH, HOME, LANG, PYTHONPATH) but no cwd=, no user change and no filesystem or network restriction. The child therefore inherits Prax’s working directory and PYTHONPATH, and because Pydantic settings load .env from the working directory, from prax.settings import settings inside the child returns every credential the parent holds. Read the table below with that in mind: it describes what the environment no longer contains, not what the child can obtain.

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, PYTHONPATH\nNo API keys in env\n(but cwd + .env inherited)"]
    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)

Two of the layers below exist in code but are not installed anywhere; two are live.

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) when the loader imports it (prax/plugins/loader.py inspects the signature). 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.

Known gap (2026-09): the pre-activation sandbox test (prax/plugins/sandbox.py, sandbox_test_plugin) calls mod.register() with no argument, so a contract-conformant register(caps) plugin fails it with TypeError — plugin_write then removes the file and plugin_activate/hot_swap refuse to activate. Plugins written to the published register(caps) contract can be loaded by load_all() but not created or activated through those tools.

BUILTIN and WORKSPACE plugins remain fully in-process with no overhead — subprocess isolation applies only to IMPORTED plugins from external repos. Known gap (2026-09): WORKSPACE plugins (<workspace>/plugins/custom/) are imported in-process by load_all() with no security scan, no sandbox test and no acknowledgement (those run only in plugin_write / hot_swap / import_plugin_repo), and get_approved_secret auto-approves every secret for the tier (prax/plugins/capabilities.py). Anything that can write into the workspace — the sandbox container has /workspace read-write — can therefore get in-process code execution in Prax at the next load (a user’s first turn per process, or the unauthenticated POST /plugins/<name>/acknowledge route, which calls load_all()). See sandbox-execution-boundary.md.

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")