diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index 34fa1b93870..1c33aeebae6 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -5,16 +5,15 @@ read_when: title: "Security" --- -# Security - -**Personal assistant trust model:** this guidance assumes one trusted operator boundary per gateway (single-user/personal assistant model). -OpenClaw is **not** a hostile multi-tenant security boundary for multiple adversarial users sharing one agent/gateway. -If you need mixed-trust or adversarial-user operation, split trust boundaries (separate gateway + credentials, ideally separate OS users/hosts). + **Personal assistant trust model.** This guidance assumes one trusted + operator boundary per gateway (single-user, personal-assistant model). + OpenClaw is **not** a hostile multi-tenant security boundary for multiple + adversarial users sharing one agent or gateway. If you need mixed-trust or + adversarial-user operation, split trust boundaries (separate gateway + + credentials, ideally separate OS users or hosts). -**On this page:** [Trust model](#scope-first-personal-assistant-security-model) | [Quick audit](#quick-check-openclaw-security-audit) | [Hardened baseline](#hardened-baseline-in-60-seconds) | [DM access model](#dm-access-model-pairing-allowlist-open-disabled) | [Configuration hardening](#configuration-hardening-examples) | [Incident response](#incident-response) - ## Scope first: personal assistant security model OpenClaw security guidance assumes a **personal assistant** deployment: one trusted operator boundary, potentially many agents. @@ -115,15 +114,27 @@ Use this as the quick model when triaging risk: ## Not vulnerabilities by design -These patterns are commonly reported and are usually closed as no-action unless a real boundary bypass is shown: + + These patterns get reported often and are usually closed as no-action unless + a real boundary bypass is demonstrated: -- Prompt-injection-only chains without a policy/auth/sandbox bypass. -- Claims that assume hostile multi-tenant operation on one shared host/config. -- Claims that classify normal operator read-path access (for example `sessions.list`/`sessions.preview`/`chat.history`) as IDOR in a shared-gateway setup. -- Localhost-only deployment findings (for example HSTS on loopback-only gateway). -- Discord inbound webhook signature findings for inbound paths that do not exist in this repo. -- Reports that treat node pairing metadata as a hidden second per-command approval layer for `system.run`, when the real execution boundary is still the gateway's global node command policy plus the node's own exec approvals. -- "Missing per-user authorization" findings that treat `sessionKey` as an auth token. +- Prompt-injection-only chains without a policy, auth, or sandbox bypass. +- Claims that assume hostile multi-tenant operation on one shared host or + config. +- Claims that classify normal operator read-path access (for example + `sessions.list` / `sessions.preview` / `chat.history`) as IDOR in a + shared-gateway setup. +- Localhost-only deployment findings (for example HSTS on a loopback-only + gateway). +- Discord inbound webhook signature findings for inbound paths that do not + exist in this repo. +- Reports that treat node pairing metadata as a hidden second per-command + approval layer for `system.run`, when the real execution boundary is still + the gateway's global node command policy plus the node's own exec + approvals. +- "Missing per-user authorization" findings that treat `sessionKey` as an + auth token. + ## Hardened baseline in 60 seconds @@ -313,7 +324,7 @@ production. -## Reverse Proxy Configuration +## Reverse proxy configuration If you run the Gateway behind a reverse proxy (nginx, Caddy, Traefik, etc.), configure `gateway.trustedProxies` for proper forwarded-client IP handling. @@ -405,7 +416,7 @@ OpenClaw can refresh the skills list mid-session: Treat skill folders as **trusted code** and restrict who can modify them. -## The Threat Model +## The threat model Your AI assistant can: @@ -481,9 +492,7 @@ Plugins run **in-process** with the Gateway. Treat them as trusted code: Details: [Plugins](/tools/plugin) - - -## DM access model (pairing / allowlist / open / disabled) +## DM access model: pairing, allowlist, open, disabled All current DM-capable channels support a DM policy (`dmPolicy` or `*.dm.policy`) that gates inbound DMs **before** the message is processed: @@ -526,7 +535,7 @@ Treat the snippet above as **secure DM mode**: If you run multiple accounts on the same channel, use `per-account-channel-peer` instead. If the same person contacts you on multiple channels, use `session.identityLinks` to collapse those DM sessions into one canonical identity. See [Session Management](/concepts/session) and [Configuration](/gateway/configuration). -## Allowlists (DM + groups) - terminology +## Allowlists for DMs and groups OpenClaw has two separate “who can trigger me?” layers: @@ -656,9 +665,7 @@ Recommendations: - When running small models, **enable sandboxing for all sessions** and **disable web_search/web_fetch/browser** unless inputs are tightly controlled. - For chat-only personal assistants with trusted input and no tools, smaller models are usually fine. - - -## Reasoning & verbose output in groups +## Reasoning and verbose output in groups `/reasoning`, `/verbose`, and `/trace` can expose internal reasoning, tool output, or plugin diagnostics that @@ -671,7 +678,7 @@ Guidance: - If you enable them, do so only in trusted DMs or tightly controlled rooms. - Remember: verbose and trace output can include tool args, URLs, plugin diagnostics, and data the model saw. -## Configuration Hardening (examples) +## Configuration hardening examples ### File permissions @@ -1224,7 +1231,7 @@ Common use cases: } ``` -## Incident Response +## Incident response If your AI does something bad: @@ -1254,7 +1261,7 @@ If your AI does something bad: - What the attacker sent + what the agent did - Whether the Gateway was exposed beyond loopback (LAN/Tailscale Funnel/Serve) -## Secret Scanning (detect-secrets) +## Secret scanning with detect-secrets CI runs the `detect-secrets` pre-commit hook in the `secrets` job. Pushes to `main` always run an all-files scan. Pull requests use a changed-file @@ -1287,7 +1294,7 @@ otherwise. If it fails, there are new candidates not yet in the baseline. Commit the updated `.secrets.baseline` once it reflects the intended state. -## Reporting Security Issues +## Reporting security issues Found a vulnerability in OpenClaw? Please report responsibly: