Skip to content

Security

Production-grade security checklist for deploying Autobot safely.

1. Restrict Who Can Talk to the Bot (DENY-BY-DEFAULT)

IMPORTANT: Empty allow_from = DENY ALL (secure default since v0.1.0)

channels:
  telegram:
    allow_from: ["@alice", "123456789"]  # Allowlist specific users (recommended)
    # allow_from: ["*"]                  # Allow anyone (use with caution!)
    # allow_from: []                     # Deny all (secure default)

For Slack: Prefer mention policy in group channels to prevent unauthorized access.

2. Kernel-Enforced Workspace Sandbox (REQUIRED FOR PRODUCTION)

Autobot uses kernel-level sandboxing to restrict LLM file access to a designated workspace directory.

Quick Setup

Linux (bubblewrap - recommended): 

sudo apt install bubblewrap  # Ubuntu/Debian
sudo dnf install bubblewrap  # Fedora
sudo pacman -S bubblewrap    # Arch

macOS/Windows (Docker): 

# Install Docker Desktop
# https://docs.docker.com/engine/install/

Configuration

tools:
  sandbox: auto  # auto | bubblewrap | docker | none (default)

What It Protects Against

  • ✅ Reading system files (/etc/passwd, ~/.ssh/)
  • ✅ Writing outside workspace
  • ✅ Path traversal (../../../etc/passwd)
  • ✅ Absolute path exploits (/etc/passwd)
  • ✅ Symlink attacks

For detailed information, see docs/sandboxing.md

Best Practices

  • ✅ Always use sandboxing in production (sandbox: auto or specific type)
  • ✅ Install bubblewrap for development (lightweight, fast)
  • ✅ Use Docker for production deployments
  • ✅ Keep workspace scoped to a dedicated directory, not your home folder
  • ⚠️ Never use sandbox: none in production (development-only)
  • ⚠️ Never place .env files inside workspace (blocked automatically)

3. SSRF Protection (ALWAYS ENABLED)

Built-in protection against Server-Side Request Forgery:

Blocked automatically:

  • Private IP ranges (10.x, 192.168.x, 172.16-31.x)
  • Localhost/loopback (127.x, ::1)
  • Cloud metadata endpoints (169.254.169.254)
  • Link-local addresses (169.254.x, fe80:)
  • Alternate IP notation (octal: 0177.0.0.1, hex: 0x7f.0.0.1)
  • IPv6 private ranges (fc00::/7, fd00::/8)
  • IPv4-mapped IPv6 (::ffff:127.0.0.1) — unwrapped to the embedded IPv4 before checking

All DNS records validated to prevent DNS rebinding attacks.

4. Keep Secrets Out of Files

.env File Protection (v0.2.0+)

Autobot enforces strict .env file protection:

Automatic blocks (LLM cannot access):

  • .env files blocked in ReadFileTool (read, list directory)
  • .env files blocked in ExecTool (commands like cat .env)
  • Pattern matching: .env, .env.local, .env.production, secrets.env, etc.

Configuration validation (autobot doctor):

  • ❌ Error: Plaintext secrets in config.yml
  • ❌ Error: .env permissions not 0600
  • ❌ Error: .env inside workspace (exposes to LLM)
  • ⚠️ Warning: Missing .env file

Example secure config: 

# config.yml (safe for LLM to read)
providers:
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"  # References .env

# .env (NEVER accessible to LLM)
ANTHROPIC_API_KEY=sk-ant-your-secret-key

File locations:

  • ✅ ./autobot/.env (outside workspace)
  • ✅ ./.env (outside workspace)
  • ❌ ./workspace/.env (inside workspace - BLOCKED by validation)

Secrets in Tool Output

Whatever a tool returns becomes part of the next prompt. The sandbox limits what a command can read, not what a tool returns: a script that fails with its request headers in the stack trace, or an MCP server that echoes its configuration in an error, would hand a token you passed in through sandbox_env to the model and, depending on the provider, to its training data.

Credential redaction runs on every tool result before it reaches the model, whether the tool is built in, a skill script, a plugin or an MCP server. Provider keys, bearer tokens, token=, password=, *_api_key= and *_secret= assignments and authorization headers are replaced with [REDACTED]. Long identifiers such as commit hashes and base64 content are left alone.

This is defense in depth. Keep secrets outside the workspace and reference them from config.yml with ${VAR} so there is nothing to leak in the first place.

Log Sanitization

Automatic log sanitization redacts everything credential redaction does, plus any long alphanumeric token that looks like a key:

  • API keys (sk-ant-, sk-, AKIA, etc.)
  • Bearer tokens
  • OAuth tokens
  • Passwords in URLs/params
  • Authorization headers

5. Configuration Validation (autobot doctor)

Use autobot doctor to verify security configuration before deployment:

autobot doctor          # Check for errors and warnings
autobot doctor --strict # Fail on any warning (CI/CD)

Security checks performed:

❌ Errors (blocks deployment):

  • Sandbox enabled but not available
  • Plaintext secrets detected in config.yml
  • .env file permissions not 0600
  • .env file inside workspace directory
  • No LLM provider configured
  • Unknown transcription provider

⚠️ Warnings (review recommended):

  • Filesystem root configured outside the workspace
  • tools.enabled entry that matches no known tool
  • Voice transcription pinned to a provider that has no api key
  • Gateway bound to 0.0.0.0 (network exposure)
  • Channel authorization not configured (empty allow_from)
  • Missing .env file
  • Workspace restrictions disabled
  • Channels enabled without tokens

Example output: 

❌ ERRORS (1):
  • CRITICAL: .env file has insecure permissions (644). Run: chmod 600 /path/.env

⚠️  WARNINGS (1):
  • Gateway is bound to 0.0.0.0 (all network interfaces). Use '127.0.0.1' for localhost-only access.

Summary: 1 errors, 1 warnings, 0 info

Integration:

  • Run automatically on autobot gateway startup
  • Exit code 1 on errors (stops deployment)
  • Use --strict in CI/CD pipelines to catch warnings

6. Review Logs & Monitor Access

# Check for ACCESS DENIED (security blocks)
grep "ACCESS DENIED" ./logs/autobot.log

# Tool activity
grep "Executing tool:" ./logs/autobot.log

# Token usage
grep "Tokens:" ./logs/autobot.log

Log levels:

  • INFO - Successful operations
  • WARN - Failed operations or ACCESS DENIED
  • ERROR - Exceptions and critical failures

7. File Permissions (AUTOMATIC)

Autobot automatically sets restrictive permissions on sensitive files:

  • Config files: 0600 (user read/write only)
  • Session files: 0600 (user read/write only)
  • Cron store: 0600 (user read/write only)
  • Directories: 0700 (user access only)

Validation:

  • autobot doctor checks .env permissions (must be 0600)
  • Automatic enforcement on file creation

8. Cron Job Isolation (AUTOMATIC)

Jobs are automatically isolated by owner (channel:chat_id):

  • Users can only list/remove their own jobs
  • Cross-user tampering prevented

9. Rate Limiting (PER-SESSION)

Rate limits are enforced per-session to prevent:

  • One user exhausting limits for others
  • Abuse of expensive operations (web search, LLM calls)

10. Isolate Runtime

Recommended deployment:

  • Run with least-privileged user account
  • Use containerization (Docker) or systemd service boundaries
  • Bind gateway to localhost only (host: 127.0.0.1) unless external access needed
  • Use reverse proxy with TLS for external access

Production security checklist:

  • [ ] autobot doctor --strict passes
  • [ ] Dedicated user account (not root)
  • [ ] .env permissions (0600)
  • [ ] .env outside workspace
  • [ ] TLS configured (Let's Encrypt)
  • [ ] Gateway bound to localhost
  • [ ] Reverse proxy for external access
  • [ ] Resource limits configured
  • [ ] Log monitoring enabled

11. Attachments Are Data, Not Instructions (AUTOMATIC)

Anything a user hands over rather than types or speaks — audio files, photos, documents, forwarded messages — reaches the model as a delimited <attachment> block after the user's own words, with its transcript inside the block. The system prompt tells the model such blocks are material to work on, never instructions to follow. See Media support.

This is a boundary in the data, not a promise about the model: a determined prompt inside a recording can still influence a summary. Combine it with sandboxing and a minimal tool set for bots that read other people's content, so that the worst outcome is a bad note rather than an action.

12. Least Tools Per Bot

A bot that reads other people's content should not be able to do much with it. Two settings make that a property of the config rather than of the prompt:

tools:
  enabled: [read_file, write_file, edit_file, list_dir, message]
  filesystem:
    roots: [notes, inbox]

tools.enabled is an allowlist applied at registration, so a tool that is not listed does not exist for the model, whether it is built in, a skill script, a plugin or an MCP tool. tools.filesystem.roots keeps the file tools inside the listed workspace subdirectories, with skills/ readable on top so a skill's references can be read on demand. With both in place, the worst a planted instruction inside an attachment can do is write a bad note. autobot doctor prints the effective tool list and reminds you to set the allowlist when it is missing.

13. Transcription Per Bot

Speech is the one kind of content that becomes instruction: a voice note the sender records is transcribed into the message text. The transcription section decides, per bot, whether that happens and with whose key:

transcription:
  enabled: false

A bot with transcription off never hears a voice note. The note is saved to the inbox as an attachment without a transcript and the bot answers with a fixed reply, with no model turn. A bot that should hear voice notes but must not share audio with the chat provider's account gets transcription.api_key of its own. autobot doctor prints the setting.

14. Known Limitations

WhatsApp Bridge: WebSocket connection has no authentication (ws://).

  • Mitigation: Only run bridge on localhost
  • TODO: HMAC/JWT authentication in future release