EKOSdocs
Docs / Architecture Learn

Security Model

Redaction before storage, read-only serving, gated tools and trust boundaries.

Secrets and PII are never stored

Because the ledger is append-only, there is no way to delete something already committed. So this is a prevention control (RFC 0043):

  • A built-in baseline redacts known secret shapes — AWS, GitHub, Slack, Google and Stripe tokens, private keys, JWTs, generic key/password assignments — from all observed content.
  • Files such as .env, *.pem and id_rsa are excluded entirely.
  • It runs at every raw-content entry point: the Observer path, the direct-read paths in recover, and the live database readers (pg-live, ora-live, the ClickHouse catalog), which redact what they read themselves.
  • A file read again later for a model or the ledger (symbol source for LLM descriptions, crate doc comments, view definitions) goes through one helper, read_redacted: an excluded file is never opened, everything else is redacted. git blame commit subjects recorded as rationale are redacted too.
  • [security] can only extend the baseline (extra patterns and globs), never disable it.

Live databases

  • A database password stays in an environment variable (or, in the console, the server's keychain); ekos.toml holds only the variable's name.
  • Catalogs are read inside read-only sessions (for Oracle, SET TRANSACTION READ ONLY), and a write probe must be refused; a user that could write is reported.
  • Profiles keep counts and bounds of numbers and dates, never text values; a text column is never a MIN/MAX argument.
  • Estate documentation shows column profiles as counts only, and uses text only from sources with a known licence.

Read-only serving

The runtime never modifies state, and the type system enforces it: the store API is split into KnowledgeReader and a KnowledgeStore that adds the writes, and the runtime holds only a reader. Agents reach knowledge only through MCP. A test (only_listed_functions_can_write_the_ledger) pins the few MCP functions that can write: the two review tools and the ClickHouse audit.

Exposure

  • TCP and HTTP transports should bind loopback or a trusted network and use a bearer token.
  • ekos_clickhouse_query is the single path by which an agent reaches a live system: off by default, one validated SELECT only, audited. Live catalog reads happen at ekos build, never on an agent's request.

Trust of stored text

Text in the ledger came from your sources and may itself contain instructions. Agents should treat retrieved evidence as data, not instructions.

Integrity

Content-addressed artifacts, checksummed segments, and per-write provenance make tampering and drift detectable.

Permissions

Who may do what in the web console, and what each reader may see of a project, is enforced in two places in the code: see Permissions for the exact lines and the tests that cover them.