Skip to main content

Plugin trust model

User-installed plugins (loaders, tool plugins, domains) run in-process with full Python privileges — they can read your data dir, make outbound network calls, and load arbitrary code.

Default policy​

CHAOSCYPHER_ALLOW_USER_PLUGINS=1 — user plugins are loaded.

To disable user plugins entirely:

CHAOSCYPHER_ALLOW_USER_PLUGINS=0 docker compose up -d

What plugins can do​

  • Read/write {data-dir}/.
  • Make HTTP requests.
  • Import any installed Python package.
  • Use the configured LLM providers via Chaos Cypher's wrappers (so they pay the rate limits the operator paid for).

Where plugins live​

  • {data-dir}/plugins/loaders/ — source loaders (run at *_loader.py files)
  • {data-dir}/plugins/tools/ — tool plugins (run at *_plugin.py files)
  • {data-dir}/plugins/domains/ — domain definitions (.jsonld data files)
  • {data-dir}/plugins/cleaners/ — data cleaners (run at *.py files)
  • {data-dir}/plugins/archive_handlers/ — archive handlers (run at *.py files)

Python files are executed at startup via importlib.util.spec_from_file_location() — any top-level code runs immediately.

Audit trail​

Every user plugin file loaded is logged at WARNING level with its absolute path and SHA-256 digest. Grep your logs for user_plugin_loaded to see what ran.

Trust posture for self-hosters​

You are the only operator. Treat plugins like Python packages: read the code before running it, prefer signed/well-known sources, and disable the loader if you've been handed a .zip from somewhere you don't trust.

For a more aggressive isolation story, see the self-hosted threat model.

Operator checklist for shared deployments​

If you're running Chaos Cypher in a multi-user or untrusted environment:

  • Run the Chaos Cypher service as a dedicated unprivileged user.
  • Set CHAOSCYPHER_ALLOW_USER_PLUGINS=0 in the service environment.
  • Install trusted plugins via pip entry points instead (chaoscypher.plugins.* groups); entry-point plugins are subject to the same process privileges but at least route through your package manager and CI.