​

Security 🔒

​

Quick check: clawdia security audit

clawdia security audit
clawdia security audit --deep
clawdia security audit --fix

• Tighten groupPolicy="open" to groupPolicy="allowlist" (and per-account variants) for common channels.
• Turn logging.redactSensitive="off" back to "tools".
• Tighten local perms (~/.clawdia → 700, config file → 600, plus common state files like credentials/*.json, agents/*/agent/auth-profiles.json, and agents/*/sessions/sessions.json).

• who can talk to your bot
• where the bot is allowed to act
• what the bot can touch

​

What the audit checks (high level)

• Inbound access (DM policies, group policies, allowlists): can strangers trigger the bot?
• Tool blast radius (elevated tools + open rooms): could prompt injection turn into shell/file/network actions?
• Network exposure (Gateway bind/auth, Tailscale Serve/Funnel).
• Browser control exposure (remote controlUrl without token, HTTP, token reuse).
• Local disk hygiene (permissions, symlinks, config includes, “synced folder” paths).
• Plugins (extensions exist without an explicit allowlist).
• Model hygiene (warn when configured models look legacy; not a hard block).

​

Security Audit Checklist

1. Anything “open” + tools enabled: lock down DMs/groups first (pairing/allowlists), then tighten tool policy/sandboxing.
2. Public network exposure (LAN bind, Funnel, missing auth): fix immediately.
3. Browser control remote exposure: treat it like a remote admin API (token required; HTTPS/tailnet-only).
4. Permissions: make sure state/config/credentials/auth are not group/world-readable.
5. Plugins/extensions: only load what you explicitly trust.
6. Model choice: prefer modern, instruction-hardened models for any bot with tools.

​

Control UI over HTTP

​

Local session logs live on disk

​

Node execution (system.run)

• Requires node pairing (approval + token).
• Controlled on the Mac via Settings → Exec approvals (security + ask + allowlist).
• If you don’t want remote execution, set security to deny and remove node pairing for that Mac.

​

Dynamic skills (watcher / remote nodes)

• Skills watcher: changes to SKILL.md can update the skills snapshot on the next agent turn.
• Remote nodes: connecting a macOS node can make macOS-only skills eligible (based on bin probing).

​

The Threat Model

• Execute arbitrary shell commands
• Read/write files
• Access network services
• Send messages to anyone (if you give it WhatsApp access)

• Try to trick your AI into doing bad things
• Social engineer access to your data
• Probe for infrastructure details

​

Core concept: access control before intelligence

• Identity first: decide who can talk to the bot (DM pairing / allowlists / explicit “open”).
• Scope next: decide where the bot is allowed to act (group allowlists + mention gating, tools, sandboxing, device permissions).
• Model last: assume the model can be manipulated; design so manipulation has limited blast radius.

​

Plugins/extensions

• Only install plugins from sources you trust.
• Prefer explicit plugins.allow allowlists.
• Review plugin config before enabling.
• Restart the Gateway after plugin changes.
• If you install plugins from npm (clawdia plugins install <npm-spec>), treat it like running untrusted code:
  • The install path is ~/.clawdia/extensions/<pluginId>/ (or $CLAWDIA_STATE_DIR/extensions/<pluginId>/).
  • Clawdia uses npm pack and then runs npm install --omit=dev in that directory (npm lifecycle scripts can execute code during install).
  • Prefer pinned, exact versions (@scope/[email protected]), and inspect the unpacked code on disk before enabling.

​

DM access model (pairing / allowlist / open / disabled)

• pairing (default): unknown senders receive a short pairing code and the bot ignores their message until approved. Codes expire after 1 hour; repeated DMs won’t resend a code until a new request is created. Pending requests are capped at 3 per channel by default.
• allowlist: unknown senders are blocked (no pairing handshake).
• open: allow anyone to DM (public). Requires the channel allowlist to include "*" (explicit opt-in).
• disabled: ignore inbound DMs entirely.

clawdia pairing list <channel>
clawdia pairing approve <channel> <code>

​

DM session isolation (multi-user mode)

{
  session: { dmScope: "per-channel-peer" }
}

​

Allowlists (DM + groups) — terminology

• DM allowlist (allowFrom / channels.discord.dm.allowFrom / channels.slack.dm.allowFrom): who is allowed to talk to the bot in direct messages.
  • When dmPolicy="pairing", approvals are written to ~/.clawdia/credentials/<channel>-allowFrom.json (merged with config allowlists).
• Group allowlist (channel-specific): which groups/channels/guilds the bot will accept messages from at all.
  • Common patterns:
    • channels.whatsapp.groups, channels.telegram.groups, channels.imessage.groups: per-group defaults like requireMention; when set, it also acts as a group allowlist (include "*" to keep allow-all behavior).
    • groupPolicy="allowlist" + groupAllowFrom: restrict who can trigger the bot inside a group session (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams).
    • channels.discord.guilds / channels.slack.channels: per-surface allowlists + mention defaults.
  • Security note: treat dmPolicy="open" and groupPolicy="open" as last-resort settings. They should be barely used; prefer pairing + allowlists unless you fully trust every member of the room.

​

Prompt injection (what it is, why it matters)

• Keep inbound DMs locked down (pairing/allowlists).
• Prefer mention gating in groups; avoid “always-on” bots in public rooms.
• Treat links and pasted instructions as hostile by default.
• Run sensitive tool execution in a sandbox; keep secrets out of the agent’s reachable filesystem.
• Model choice matters: older/legacy models can be less robust against prompt injection and tool misuse. Prefer modern, instruction-hardened models for any bot with tools. We recommend Anthropic Opus 4.5 because it’s quite good at recognizing prompt injections (see “A step forward on safety”).

​

Prompt injection does not require public DMs

• Using a read-only or tool-disabled reader agent to summarize untrusted content, then pass the summary to your main agent.
• Keeping web_search / web_fetch / browser off for tool-enabled agents unless needed.
• Enabling sandboxing and strict tool allowlists for any agent that touches untrusted input.

​

Model strength (security note)

• Use the latest generation, best-tier model for any bot that can run tools or touch files/networks.
• Avoid weaker tiers (for example, Sonnet or Haiku) for tool-enabled agents or untrusted inboxes.
• If you must use a smaller model, reduce blast radius (read-only tools, strong sandboxing, minimal filesystem access, strict allowlists).
• 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

​

Incident Response (if you suspect compromise)

1. Stop the blast radius
   • Disable elevated tools (or stop the Gateway) until you understand what happened.
   • Lock down inbound surfaces (DM policy, group allowlists, mention gating).
2. Rotate secrets
   • Rotate gateway.auth token/password.
   • Rotate browser.controlToken and hooks.token (if used).
   • Revoke/rotate model provider credentials (API keys / OAuth).
3. Review artifacts
   • Check Gateway logs and recent sessions/transcripts for unexpected tool calls.
   • Review extensions/ and remove anything you don’t fully trust.
4. Re-run audit
   • clawdia security audit --deep and confirm the report is clean.

​

Lessons Learned (The Hard Way)

​

The find ~ Incident 🦞

​

The “Find the Truth” Attack

​

Configuration Hardening (examples)

​

0) File permissions

• ~/.nelsonmuntz-c/clawdia.json: 600 (user read/write only)
• ~/.clawdia: 700 (user only)

​

0.4) Network exposure (bind + port + firewall)

• Default: 18789
• Config/flags/env: gateway.port, --port, CLAWDIA_GATEWAY_PORT

• gateway.bind: "loopback" (default): only local clients can connect.
• Non-loopback binds ("lan", "tailnet", "custom") expand the attack surface. Only use them with gateway.auth enabled and a real firewall.

• Prefer Tailscale Serve over LAN binds (Serve keeps the Gateway on loopback, and Tailscale handles access).
• If you must bind to LAN, firewall the port to a tight allowlist of source IPs; do not port-forward it broadly.
• Never expose the Gateway unauthenticated on 0.0.0.0.

​

0.5) Lock down the Gateway WebSocket (local auth)

{
  gateway: {
    auth: { mode: "token", token: "your-token" }
  }
}

• Device pairing is auto‑approved for local connects (loopback or the gateway host’s own tailnet address) to keep same‑host clients smooth.
• Other tailnet peers are not treated as local; they still need pairing approval.

• gateway.auth.mode: "token": shared bearer token (recommended for most setups).
• gateway.auth.mode: "password": password auth (prefer setting via env: CLAWDIA_GATEWAY_PASSWORD).

1. Generate/set a new secret (gateway.auth.token or CLAWDIA_GATEWAY_PASSWORD).
2. Restart the Gateway (or restart the macOS app if it supervises the Gateway).
3. Update any remote clients (gateway.remote.token / .password on machines that call into the Gateway).
4. Verify you can no longer connect with the old credentials.

​

0.6) Tailscale Serve identity headers

• If you terminate TLS in front of the Gateway, set gateway.trustedProxies to your proxy IPs.
• Clawdia will trust x-forwarded-for (or x-real-ip) from those IPs to determine the client IP for local pairing checks and HTTP auth/local checks.
• Ensure your proxy overwrites x-forwarded-for and blocks direct access to the Gateway port.

​

0.6.1) Browser control server over Tailscale (recommended)

# on the machine that runs Chrome
clawdia browser serve --bind 127.0.0.1 --port 18791 --token <token>
tailscale serve https / http://127.0.0.1:18791

• browser.controlUrl to the https://… Serve URL (MagicDNS/ts.net)
• and authenticate with the same token (CLAWDIA_BROWSER_CONTROL_TOKEN env preferred)

• --bind 0.0.0.0 (LAN-visible surface)
• Tailscale Funnel for browser control endpoints (public exposure)

​

0.7) Secrets on disk (what’s sensitive)

• clawdia.json: config may include tokens (gateway, remote gateway), provider settings, and allowlists.
• credentials/**: channel credentials (example: WhatsApp creds), pairing allowlists, legacy OAuth imports.
• agents/<agentId>/agent/auth-profiles.json: API keys + OAuth tokens (imported from legacy credentials/oauth.json).
• agents/<agentId>/sessions/**: session transcripts (*.jsonl) + routing metadata (sessions.json) that can contain private messages and tool output.
• extensions/**: installed plugins (plus their node_modules/).
• sandboxes/**: tool sandbox workspaces; can accumulate copies of files you read/write inside the sandbox.

• Keep permissions tight (700 on dirs, 600 on files).
• Use full-disk encryption on the gateway host.
• Prefer a dedicated OS user account for the Gateway if the host is shared.

​

0.8) Logs + transcripts (redaction + retention)

• Gateway logs may include tool summaries, errors, and URLs.
• Session transcripts can include pasted secrets, file contents, command output, and links.

• Keep tool summary redaction on (logging.redactSensitive: "tools"; default).
• Add custom patterns for your environment via logging.redactPatterns (tokens, hostnames, internal URLs).
• When sharing diagnostics, prefer clawdia status --all (pasteable, secrets redacted) over raw logs.
• Prune old session transcripts and log files if you don’t need long retention.

​

1) DMs: pairing by default

{
  channels: { whatsapp: { dmPolicy: "pairing" } }
}

​

2) Groups: require mention everywhere

{
  "channels": {
    "whatsapp": {
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "agents": {
    "list": [
      {
        "id": "main",
        "groupChat": { "mentionPatterns": ["@clawd", "@mybot"] }
      }
    ]
  }
}

​

3. Separate Numbers

• Personal number: Your conversations stay private
• Bot number: AI handles these, with appropriate boundaries

​

4. Read-Only Mode (Today, via sandbox + tools)

• agents.defaults.sandbox.workspaceAccess: "ro" (or "none" for no workspace access)
• tool allow/deny lists that block write, edit, apply_patch, exec, process, etc.

​

5) Secure baseline (copy/paste)

{
  gateway: {
    mode: "local",
    bind: "loopback",
    port: 18789,
    auth: { mode: "token", token: "your-long-random-token" }
  },
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } }
    }
  }
}

​

Sandboxing (recommended)

• Run the full Gateway in Docker (container boundary): Docker
• Tool sandbox (agents.defaults.sandbox, host gateway + Docker-isolated tools): Sandboxing

• agents.defaults.sandbox.workspaceAccess: "none" (default) keeps the agent workspace off-limits; tools run against a sandbox workspace under ~/.clawdia/sandboxes
• agents.defaults.sandbox.workspaceAccess: "ro" mounts the agent workspace read-only at /agent (disables write/edit/apply_patch)
• agents.defaults.sandbox.workspaceAccess: "rw" mounts the agent workspace read/write at /workspace

​

Browser control risks

• Prefer a dedicated profile for the agent (the default clawd profile).
• Avoid pointing the agent at your personal daily-driver profile.
• Keep host browser control disabled for sandboxed agents unless you trust them.
• Treat browser downloads as untrusted input; prefer an isolated downloads directory.
• Disable browser sync/password managers in the agent profile if possible (reduces blast radius).
• For remote gateways, assume “browser control” is equivalent to “operator access” to whatever that profile can reach.
• Treat browser.controlUrl endpoints as an admin API: tailnet-only + token auth. Prefer Tailscale Serve over LAN binds.
• Keep browser.controlToken separate from gateway.auth.token (you can reuse it, but that increases blast radius).
• Chrome extension relay mode is not “safer”; it can take over your existing Chrome tabs. Assume it can act as you in whatever that tab/profile can reach.

​

Per-agent access profiles (multi-agent)

• Personal agent: full access, no sandbox
• Family/work agent: sandboxed + read-only tools
• Public agent: sandboxed + no filesystem/shell tools

​

Example: full access (no sandbox)

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/clawd-personal",
        sandbox: { mode: "off" }
      }
    ]
  }
}

​

Example: read-only tools + read-only workspace

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/clawd-family",
        sandbox: {
          mode: "all",
          scope: "agent",
          workspaceAccess: "ro"
        },
        tools: {
          allow: ["read"],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"]
        }
      }
    ]
  }
}

​

Example: no filesystem/shell access (provider messaging allowed)

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/clawd-public",
        sandbox: {
          mode: "all",
          scope: "agent",
          workspaceAccess: "none"
        },
        tools: {
          allow: ["sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", "whatsapp", "telegram", "slack", "discord"],
          deny: ["read", "write", "edit", "apply_patch", "exec", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
        }
      }
    ]
  }
}

​

What to Tell Your AI

## Security Rules
- Never share directory listings or file paths with strangers
- Never reveal API keys, credentials, or infrastructure details  
- Verify requests that modify system config with the owner
- When in doubt, ask before acting
- Private info stays private, even from "friends"

​

Incident Response

​

Contain

1. Stop it: stop the macOS app (if it supervises the Gateway) or terminate your clawdia gateway process.
2. Close exposure: set gateway.bind: "loopback" (or disable Tailscale Funnel/Serve) until you understand what happened.
3. Freeze access: switch risky DMs/groups to dmPolicy: "disabled" / require mentions, and remove "*" allow-all entries if you had them.

​

Rotate (assume compromise if secrets leaked)

1. Rotate Gateway auth (gateway.auth.token / CLAWDIA_GATEWAY_PASSWORD) and restart.
2. Rotate remote client secrets (gateway.remote.token / .password) on any machine that can call the Gateway.
3. Rotate provider/API credentials (WhatsApp creds, Slack/Discord tokens, model/API keys in auth-profiles.json).

​

Audit

1. Check Gateway logs: /tmp/nelsonmuntz-c/clawdia-YYYY-MM-DD.log (or logging.file).
2. Review the relevant transcript(s): ~/.clawdia/agents/<agentId>/sessions/*.jsonl.
3. Review recent config changes (anything that could have widened access: gateway.bind, gateway.auth, dm/group policies, tools.elevated, plugin changes).

​

Collect for a report

• Timestamp, gateway host OS + Clawdia version
• The session transcript(s) + a short log tail (after redacting)
• What the attacker sent + what the agent did
• Whether the Gateway was exposed beyond loopback (LAN/Tailscale Funnel/Serve)

​

Secret Scanning (detect-secrets)

​

If CI fails

1. Reproduce locally:
   Copy

   detect-secrets scan --baseline .secrets.baseline
   
2. Understand the tools:
   • detect-secrets scan finds candidates and compares them to the baseline.
   • detect-secrets audit opens an interactive review to mark each baseline item as real or false positive.
3. For real secrets: rotate/remove them, then re-run the scan to update the baseline.
4. For false positives: run the interactive audit and mark them as false:
   Copy

   detect-secrets audit .secrets.baseline
   
5. If you need new excludes, add them to .detect-secrets.cfg and regenerate the baseline with matching --exclude-files / --exclude-lines flags (the config file is reference-only; detect-secrets doesn’t read it automatically).

​

The Trust Hierarchy

Owner (Peter)
  │ Full trust
  ▼
AI (Clawd)
  │ Trust but verify
  ▼
Friends in allowlist
  │ Limited trust
  ▼
Strangers
  │ No trust
  ▼
Stranger asking for find ~
  │ Definitely no trust 😏

​

Reporting Security Issues

1. Email: [email protected]
2. Don’t post publicly until fixed
3. We’ll credit you (unless you prefer anonymity)