EKOSdocs
Docs / Operations Operate

Security

Threat model, controls and a hardening checklist.

Concern Control
Secrets in sources Built-in, non-disable-able redaction at every raw-content entry point; excluded files (.env, *.pem, id_rsa); [security] extends only
Irreversibility The ledger is append-only, so redaction is prevention. If something sensitive was indexed, the only removal is deleting the state directory and rebuilding
Agent access Read-only runtime; agents never touch source systems
Console sign-in OIDC; EKOS stores no passwords. Production mode refuses to start without OIDC, an owner and a session secret, and disables the development tokens. Local mode answers loopback only, with one-time sign-in codes
Console roles (RFC 0180) viewer, reviewer, operator, admin on a tenant or one project, plus platform owners; groups from the provider's group claim. Roles are compared in one place, and a test fails on any route that declares no required action. A project or tenant you have no role in answers 404, never 403
API tokens viewer or operator, shown once, stored as hashes; a token is refused review, admin and platform rights whatever it is bound to
Access inside a project (RFC 0181) A read scope (allow / deny by source, path pattern or object id; deny wins; what cannot be placed counts as denied) is enforced at the store, so every read path is filtered. A restricted reader gets graph, search, object pages and impact; the dashboard, run logs, configuration, semantics and conflicts are closed to them. Operators and admins cannot be limited
MCP through the console (RFC 0182) Each forwarded call is built from the tool name and arguments only (a client's _meta never reaches the server), checked against the caller's role and scope, and audited
Tenant isolation By directory and permission check inside one process and one OS user — not a sandbox. Each tenant's processes receive only the variables granted to it, and model keys only while Allow metered model calls is on
Credentials in the console Kept in the OS keychain (never returned by the API); a container has none, so they go in the deployment's environment. A database password can be entered only by a signed-in person, never with an API token
Network exposure Loopback by default; bearer token for TCP/HTTP MCP; explicit --http-allow-origin; TLS from a reverse proxy
Writes over MCP Only ekos_identity_review and ekos_architecture_review, each appending a review event that cites the reviewer's evidence, plus the gated ekos_clickhouse_query's audit event; ekos_session_note writes only an inbox file. A test pins the list
Human-only decisions Review decisions, sign-offs, conflict resolutions, business-semantics confirmations, LinkML imports, migration approvals, payment authorisations and session-claim reviews have no MCP tool; a guard test parses the MCP server's source to keep it so
Live databases Read-only sessions; a write probe must be refused; profiles never store a text value; ekos.toml holds the password variable's name only
Live queries ekos_clickhouse_query is off by default and executes a single validated SELECT
LLM providers Content sent to a provider leaves your machine — use ollama for fully local operation
Prompt injection Ledger text originated in your sources; treat it as data. Session-memory notes are returned inside an explicit untrusted envelope
Malformed MCP calls Unknown argument names are refused; numeric bounds are enforced; lines over 4 MB are rejected; a panicking tool call returns an error instead of taking the server down
MCP resource exhaustion At most 64 concurrent TCP connections; the HTTP transport queues at most 64 requests and answers 503 with Retry-After beyond that; traversals are capped and report truncated
Migration credentials Connections are aliases with a secret-env variable name; a DSN carrying a password is refused; loads read the source through a ClickHouse named collection, so no credential appears in a generated statement
Migration approvals Risk classes R0–R4 are computed, not declared; a requester cannot approve their own request; an approval covers only loads at or below its class and the exact artifacts it was granted on; there is no MCP approve
Cloud deployments Secrets in the cloud's secret store; one workload identity that may read them and write its backup prefix; no registry password; optional private exposure
Local sandboxes The EKOS Migrate PostgreSQL and ClickHouse sandboxes (docker-compose.migrate.yml) publish their ports on 127.0.0.1 only
Dependencies scripts/audit.sh runs cargo audit over every Cargo workspace plus a lockfile-freshness check; the audit.yml workflow runs it on push, on pull requests and weekly, so a new advisory against unchanged code is still caught

Not built: TLS inside the container, OAuth for MCP clients, rate limits, encrypted backups beyond the bucket's own encryption at rest.

Hardening checklist

  1. Run ekos as an unprivileged user; give a standalone MCP server read-only access to the state directory.
  2. Run the console in production mode behind TLS; grant the least role; give agents API tokens with read scopes where they need only part of a project.
  3. Use --token-file and TLS termination for any non-stdio transport outside the console.
  4. Keep provider keys and database passwords out of ekos.toml and version control.
  5. Review ignore-patterns and [security] before the first build on a new estate.
  6. For EKOS Migrate, keep default-environment away from production, give approvers distinct identities, and run ekos migrate load --dry-run before the real load.
  7. Protect backup archives as you would the volume: they are not encrypted.
  8. Run scripts/audit.sh before a release.
  9. Report vulnerabilities per SECURITY.md in the repository.