⚠️ This project has moved to docker-moltbot. All future security updates will be in the new repo.

Comprehensive security reference for Clawdbot (now Moltbot). Based on the official security documentation.

Running an AI agent with shell access on your machine is… spicy. There is no "perfectly secure" setup. The goal is to be deliberate about who can talk to your bot, where the bot is allowed to act, and what the bot can touch.

• Quick Security Audit
• Known Vulnerabilities
  1. Prompt Injection
  2. Remote Shell Access
  3. Session Logs in Plaintext
  4. Plugins Run In-Process
  5. WhatsApp with Personal Number
  6. Node Execution (system.run)
  7. Browser Control Exposure
  8. Network Exposure
  9. Reverse Proxy Misconfiguration
  10. Credential Storage Locations
  11. Dynamic Skills as Trusted Code
• Threat Model Summary
• Deployment Scenarios
• Docker-Specific Hardening
• Incident Response

Run this regularly, especially after config changes:

# Inside the container:
docker compose exec clawdbot clawdbot security audit
docker compose exec clawdbot clawdbot security audit --deep
docker compose exec clawdbot clawdbot security audit --fix

The audit checks:

• Inbound access: DM policies, group policies, allowlists — can strangers trigger the bot?
• Tool blast radius: elevated tools + open rooms — could prompt injection escalate to shell/file/network?
• Network exposure: Gateway bind/auth, Tailscale Serve/Funnel
• Browser control exposure: remote nodes, relay ports, remote CDP endpoints
• Local disk hygiene: permissions, symlinks, config includes
• Plugins: extensions without explicit allowlists
• Model hygiene: warns about legacy/weak models

--fix applies safe guardrails automatically:

• Tightens groupPolicy="open" → groupPolicy="allowlist"
• Resets logging.redactSensitive="off" → "tools"
• Fixes permissions: ~/.clawdbot → 700, config → 600, credentials *.json → 600

Mitigation:

• Keep inbound DMs locked down (dmPolicy: pairing or allowlist)
• Prefer mention gating in groups; avoid "always-on" bots in public rooms
• Treat links, attachments, and pasted instructions as hostile by default
• Run sensitive tool execution in a sandbox; keep secrets out of the agent's reachable filesystem
• Limit high-risk tools (exec, browser, web_fetch, web_search) to trusted agents
• Use a read-only or tool-disabled reader agent to summarize untrusted content, then pass the summary to your main agent
• Keep secrets out of prompts; pass them via env/config on the gateway host
• Use strong models: Prefer the latest generation, best-tier model (e.g., Anthropic Opus 4.5) for tool-enabled agents. Avoid weaker/cheaper models for agents with tools or untrusted inboxes — they are significantly more susceptible to tool misuse and instruction hijacking

Mitigation:

• Configure AGENTS.md to explicitly block dangerous commands (rm -rf /, curl | sh, git push --force, etc.)
• Enable sandbox mode — when off, exec runs on the gateway host directly
• Set tools.exec.host to sandbox and configure exec approvals for host execution
• Restrict which tools are available per agent
• Use no-new-privileges Docker security option (included in this setup)
• Run the container as a non-root user (included in this setup)
• Consider Docker network isolation (internal: true) to prevent network pivoting

Mitigation:

• Treat disk access as the trust boundary
• Lock down permissions on ~/.clawdbot/ (run security audit --fix)
• For stronger agent isolation, run agents under separate OS users or separate hosts
• Use full disk encryption (LUKS) to protect against physical theft
• Set up encrypted backups:

  tar czf - ~/.clawdbot | gpg --symmetric --cipher-algo AES256 -o backup.tar.gz.gpg

• Consider logging.redactSensitive: "tools" to redact sensitive tool output from logs
• Monitor filesystem access with auditd:

  sudo auditctl -w /home/clawdbot/.clawdbot/ -p rwa -k clawdbot-config

Mitigation:

• Only install plugins from sources you trust
• Use explicit plugins.allow allowlists
• Review plugin code before enabling — inspect unpacked code on disk at ~/.clawdbot/extensions/<name>/
• Prefer pinned, exact versions (@scope/plugin@1.2.3)
• Restart the Gateway after plugin changes
• Review plugin config before enabling
• Audit installed plugins regularly

Mitigation:

• Set dmPolicy: allowlist with only your number:

  {
    "channels": {
      "whatsapp": {
        "selfChatMode": true,
        "dmPolicy": "allowlist",
        "allowFrom": ["+5511999999999"]
      }
    }
  }

• Switch to a dedicated number as soon as possible
• Set groupPolicy: allowlist to control which groups the bot responds in
• Avoid dmPolicy: open — it allows anyone to interact

Mitigation:

• On macOS: Settings → Exec approvals → set security to deny if you don't need remote execution
• Use ask mode to require manual approval for each execution
• Use allowlist mode to restrict which commands can run
• Remove node pairing for devices that don't need remote execution
• Treat node pairing tokens as critical secrets — rotate if compromised
• Audit paired nodes regularly: clawdbot pairing list

Mitigation:

• Treat browser control like operator access — restrict to tailnet-only
• Pair nodes deliberately; avoid public exposure of CDP endpoints
• Don't expose relay ports to the public internet
• Use dedicated browser profiles without saved passwords/sessions for bot access
• The security audit checks for browser control exposure — run it regularly
• Avoid controlUi.dangerouslyDisableDeviceAuth (severe security downgrade)
• Prefer HTTPS (Tailscale Serve) or localhost-only for the Control UI

Mitigation:

• This Docker setup binds to 127.0.0.1 by default ✅
• Never bind to 0.0.0.0 on a public server
• Use ufw deny 18789/tcp to block the gateway port externally
• Use SSH tunnels for remote access:

  ssh -L 18789:localhost:18789 user@your-server

• Use Tailscale for zero-trust remote access (no open ports)
• Set a strong GATEWAY_AUTH_TOKEN (at least 24 random characters)
• On cloud VPS: enable firewall, Fail2Ban, SSH key-only auth

Mitigation:

• Configure gateway.trustedProxies explicitly:

  gateway:
    trustedProxies:
      - "127.0.0.1"
    auth:
      mode: password
      password: ${CLAWDBOT_GATEWAY_PASSWORD}

• Ensure your proxy overwrites (not appends to) incoming X-Forwarded-For headers
• When trustedProxies is set, the Gateway uses X-Forwarded-For for real client IP detection
• Without trustedProxies, proxy headers from unknown addresses are rejected when auth is disabled
• Always set gateway auth when using a reverse proxy

Credential map:

Mitigation:

• Run clawdbot security audit --fix to auto-fix permissions
• Ensure ~/.clawdbot/ is 700, config files are 600
• Pass secrets via environment variables, never hardcode in config files
• Use .env file with chmod 600 (this Docker setup does this automatically)
• Back up credentials encrypted (GPG/age)
• Rotate tokens immediately if compromise is suspected

Mitigation:

• Treat skill folders as trusted code — restrict who can modify them
• Lock down workspace filesystem permissions
• Monitor skill file changes with auditd or filesystem watches
• Review any new or modified SKILL.md files before they take effect
• Don't allow the bot to modify its own skill files in untrusted contexts
• Use read_only: true in Docker where possible

Your AI assistant can:

• ⚡ Execute arbitrary shell commands
• 📁 Read/write files on the host
• 🌐 Access network services
• 📱 Send messages to anyone (if given WhatsApp/Telegram/etc. access)
• 🖥️ Control web browsers
• 📲 Execute commands on paired devices (nodes)

People who message you can:

• 🎭 Try to trick the AI into unsafe actions (prompt injection)
• 🕵️ Social engineer access to your data
• 🔍 Probe for infrastructure details

Core principle: Access control before intelligence

Most failures are not fancy exploits — they're "someone messaged the bot and the bot did what they asked." Design so that even successful manipulation has limited blast radius.

You have physical access. Machine is behind your router.

Threat model: Other LAN devices, physical access, network malware.

Minimum security:

✅ Gateway bind: loopback (default)
✅ DM policy: pairing (default)
✅ Logging enabled
✅ Config permissions: chmod 600
✅ Docker container isolation

Recommended extras:

• Block port 18789 on router (no port forwarding)
• Enable automatic security updates
• Use Tailscale for remote access

Public IP. Under constant automated attack.

Threat model: SSH brute-force, port scanners, API token theft, prompt injection from web.

🚨 Required (do ALL):

1. Firewall (UFW): sudo ufw deny 18789/tcp
2. SSH key-only auth (disable password login)
3. Fail2Ban: sudo apt install fail2ban
4. Automatic security updates
5. Tailscale for remote access (recommended over open SSH)

# docker-compose.yml additions:
services:
  clawdbot:
    security_opt:
      - no-new-privileges:true
      - apparmor:docker-default
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    read_only: true
    tmpfs:
      - /tmp:size=512M,noexec,nosuid

If you suspect compromise (someone got into a room, a token leaked, a plugin did something unexpected):

• Disable elevated tools or stop the Gateway
• Lock down inbound surfaces (DM policy, group allowlists, mention gating)

• Rotate gateway.auth token/password
• Rotate hooks.token if used
• Revoke suspicious node pairings
• Rotate model provider credentials (Anthropic/OpenAI/etc. API keys)
• Rotate channel tokens (Telegram, Discord, Slack)

• Review session logs: ~/.clawdbot/agents/*/sessions/*.jsonl
• Check clawdbot security audit --deep
• Review installed plugins
• Check for unauthorized file modifications

• Rebuild container from clean image
• Restore config from encrypted backup
• Re-pair only trusted devices/users

# Inside container:
# Check config permissions
stat -c '%a' ~/.clawdbot/clawdbot.json
# Should be: 600

# Check DM policy
grep -o '"dmPolicy":"[^"]*"' ~/.clawdbot/clawdbot.json
# Should be: "dmPolicy":"pairing"

# Check logging
grep -o '"level":"[^"]*"' ~/.clawdbot/clawdbot.json
# Should be: "level":"info"

# On the host (VPS):
sudo ufw status
grep "PasswordAuthentication" /etc/ssh/sshd_config
sudo fail2ban-client status sshd
ss -tlnp | grep -E '18789|22'

• Official Security Docs
• Configuration Reference
• Pairing Guide
• Plugin System
• Session Management