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
- Run
ekosas an unprivileged user; give a standalone MCP server read-only access to the state directory. - 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.
- Use
--token-fileand TLS termination for any non-stdio transport outside the console. - Keep provider keys and database passwords out of
ekos.tomland version control. - Review
ignore-patternsand[security]before the firstbuildon a new estate. - For EKOS Migrate, keep
default-environmentaway from production, give approvers distinct identities, and runekos migrate load --dry-runbefore the real load. - Protect backup archives as you would the volume: they are not encrypted.
- Run
scripts/audit.shbefore a release. - Report vulnerabilities per
SECURITY.mdin the repository.