Security Architecture

​

Deployment model

​

Trust boundaries

                      ┌──────────────────────── your perimeter ────────────────────────┐
  Agent               │  MCP server ──► Datris server ──► Vault (credentials)          │
  (Claude, Cursor,    │      ▲               │   │                                     │
   CLI, script)  ─────┼──────┘               │   └─► Config store · object store ·    │
  holds a scoped      │  x-api-key           │       destinations (your Postgres,       │
  API key only        │                      │       warehouse, vector store, ...)      │
                      │                      ▼                                          │
                      │              tap runner (isolated container)                    │
                      │              · no platform credentials inside                   │
                      │              · no route to internal services                    │
                      │              · reaches its source + the Datris API only         │
                      └────────────────────────────────────────────────────────────────┘

​

Where data can go

​

Identity and authorization

• Humans log in to the UI with a username and password (BCrypt, cost 12). The first boot creates an admin account with a random bootstrap password, printed once to the server log (docker compose logs datris | grep "Bootstrap login"); change it at first login. Sessions are opaque random tokens in an HttpOnly, SameSite=Strict cookie with an 8-hour TTL. Three roles — admin, editor, viewer. With OIDC_ENABLED=true, people can instead sign in with SSO through your identity provider (OpenID Connect authorization code flow with PKCE; ID tokens checked for signature, issuer, audience, expiry and nonce, RS256/ES256 only); they become ordinary Datris users with one of the three roles, and the built-in admin account can never be reached through SSO. See User Authentication and Single sign-on (OIDC).
• Programmatic clients — the CLI, MCP agents, scripts — each hold their own labeled API key, sent as x-api-key and validated against Vault. Every key carries an explicit list of capabilities (resource:action[:scope]); a call outside that list returns 403, and the MCP tool catalog an agent sees is filtered to match. Templates (read-only, rag-builder, reporting, ops) cover the common shapes. Keys are stored hashed, shown once, and revocable individually. See API Keys.
• Tap scripts never receive a platform key. Each run gets a short-lived, read-only token for the platform API that the tap wrapper attaches automatically.

​

Credentials

• HashiCorp Vault holds every secret — source and destination credentials, AI provider keys, the platform’s own service passwords. The platform never persists a secret to disk outside Vault, and API responses mask sensitive fields.
• Agents never hold a key. An agent references a secret by name (create_tap_secret, list_tap_secrets, get_tap_secret_fields returns key names only). The value is delivered to the tap at run time as environment variables inside the runner and to the destination writer inside the server. It never appears in an agent’s config, prompt, or tool result.
• Agents can only touch their own secrets. Secrets created through MCP are tagged as tap secrets; an agent cannot modify or delete a secret a person created in the UI.
• Secrets are masked in logs. Tap stderr is scrubbed before it is logged.

​

Agent governance

• Agent Policy decides, per action, whether an agent runs it unattended, waits for a person to approve it, or is refused. It is enforced by the platform on every client — the in-platform Assistant, Claude, Cursor, the CLI, any script — and an agent cannot edit the policy or decide an approval, whatever its key holds. An approval executes exactly what was proposed; if the resource changed in between, it is refused as stale. See Agent Policy.
• Audit log (with the audit log on, USE_AUDIT_LOG=true) records every platform write, best effort by default and without loss in strict mode — create, change, run, delete, login, key rotation, denied request — attributed to a login, an API key, or the Assistant acting on a user’s behalf. Agents can attach a one-line reason to any change and it is stored with the entry. Entries are queryable in the UI and over REST, exportable as CSV, and mirrored line-by-line to the server log (JSON under the production profile) so an existing log pipeline or SIEM receives the trail with no extra integration. See Audit Log.
• Provenance, with stamping on for a pipeline, stamps every landed row (XML sources excepted; a run that cannot be stamped fails in strict mode) with the run, config version, tap run, script commit, and declared source; get_provenance resolves a stamp back to its origin, and vector-search results carry the same fields per chunk so a RAG answer can cite where its context came from. See Provenance, Lineage & Discovery.
• Versioning. Every pipeline and tap definition change is snapshotted; restores are append-only. Tap scripts can be stored in a git repository you own. See Tap GitHub Storage.
• Recovery agent actions pass through the same policy gate; under propose mode everything it wants to do queues for approval. See Incidents.

​

Isolation of agent-written code

​

Transport and storage

• TLS terminates at a reverse proxy you place in front of the server (nginx, Caddy, Traefik). Do not expose port 8080 directly. Container-to-container traffic inside the Compose network is plaintext; the host network is the trust boundary.
• External databases. With DATRIS_ENV=production the server refuses to start if a JDBC URL points at an external Postgres host without sslmode=require or stricter.
• At rest. Datris does not enforce encryption at rest on Postgres, MongoDB, MinIO, or Kafka; enable it per store for production.
• Multi-tenancy, when enabled, isolates tenants at the database level — separate Postgres databases and separate object-store buckets.

​

Air-gapped operation

​

No telemetry

git clone https://github.com/datris/datris-platform-oss.git && cd datris-platform-oss

# No analytics, error-reporting or beacon library or vendor anywhere in the code.
# Prints nothing.
grep -rniE "telemetry|posthog|sentry|segment\.(io|com)|mixpanel|amplitude|google-analytics|googletagmanager|datadoghq|newrelic|bugsnag|rollbar\.com|hotjar" \
  --exclude-dir=node_modules --exclude-dir=.venv --include='*.scala' --include='*.ts' --include='*.py' --include='*.sh' --include='*.html' . \
  | grep -vE '/tests?/|\.spec\.ts'

# Every datris.ai address the code calls. Prints exactly two lines.
grep -rnE "[\"']https://([a-z0-9-]+\.)?datris\.ai/[^\"' ]*[\"']" \
  --exclude-dir=node_modules --exclude-dir=.venv --include='*.scala' --include='*.ts' --include='*.py' --include='*.sh' . \
  | grep -vE '/tests?/|\.spec\.ts|docs\.datris\.ai'

​

Vulnerability handling

​

What Datris does not do

• No built-in MFA. MFA comes from your identity provider through OIDC single sign-on (OIDC_ENABLED=true, see Single sign-on (OIDC)): people who sign in with SSO get whatever MFA, password rules and lockout the provider enforces. Local accounts, including the admin recovery account, still have a minimum password length only and no complexity rules or lockout.
• No SAML, and no group-to-role mapping from the identity provider yet: an SSO user’s role is set on the Users screen (or OIDC_DEFAULT_ROLE for new people).
• No built-in rate limiting or WAF — put one in front of production deployments.
• No enforced encryption at rest — enable it per store.
• CORS allowed origins default to * for development — set cors.allowedOrigins to your real origins in production.
• No SOC 2 report. In a self-hosted deployment no customer data reaches Datris.ai, so most trust-services criteria fall on your environment; the controls that do apply to the vendor — secure development and vulnerability handling — are described above.

​

Operator checklist for production

1. Run Vault in non-dev mode with sealed root tokens.
2. Put a TLS-terminating reverse proxy in front of the server; do not expose 8080.
3. Switch on the governance controls: DATRIS_GOVERNED=1 on a new install, or USE_USER_AUTH=true and USE_API_KEYS=true (with the agent policy and audit log in step 5) in .env; change the admin bootstrap password immediately; issue one scoped key per agent.
4. Turn on SSO (OIDC_ENABLED=true with your identity provider’s issuer and client) so people sign in with their company account and its MFA; keep the admin password for recovery. See Single sign-on (OIDC).
5. Turn on USE_AGENT_POLICY=true and start from Use recommended; turn on USE_AUDIT_LOG=true and ship the log line to your aggregator. datris doctor shows governance.controls as ok once all four are on.
6. Keep the isolated tap runner on (the Compose default).
7. Set DATRIS_ENV=production, sslmode=require on external Postgres, and cors.allowedOrigins.
8. Enable encryption at rest on the stores; rotate API keys periodically.
9. Run the doctor self-check before every upgrade.