If you discover a security vulnerability in nanobot, please report it by:

1. DO NOT open a public GitHub issue
2. Create a private security advisory on GitHub or contact the repository maintainers (xubinrencs@gmail.com)
3. Include:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if any)

We aim to respond to security reports within 48 hours.

CRITICAL: Never commit API keys to version control.

# ✅ Good: Store in config file with restricted permissions
chmod 600 ~/.nanobot/config.json

# ❌ Bad: Hardcoding keys in code or committing them

Recommendations:

• Store API keys in ~/.nanobot/config.json with file permissions set to 0600
• Consider using environment variables for sensitive keys
• Use OS keyring/credential manager for production deployments
• Rotate API keys regularly
• Use separate API keys for development and production

IMPORTANT: Always configure allowFrom lists for production use.

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["123456789", "987654321"]
    },
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["1234567890"]
    }
  }
}

Security Notes:

• In v0.1.4.post3 and earlier, an empty allowFrom allowed all users. Since v0.1.4.post4, empty allowFrom denies all access by default — set ["*"] to explicitly allow everyone.
• Get your Telegram user ID from @userinfobot
• Use WhatsApp sender IDs as full phone numbers with country code and no leading +
• Review access logs regularly for unauthorized access attempts

The exec tool can execute shell commands. While dangerous command patterns are blocked, you should:

• ✅ Enable the bwrap sandbox ("tools.exec.sandbox": "bwrap") for kernel-level isolation (Linux only)
• ✅ Review all tool usage in agent logs
• ✅ Understand what commands the agent is running
• ✅ Use a dedicated user account with limited privileges
• ✅ Never run nanobot as root
• ❌ Don't disable security checks
• ❌ Don't run on systems with sensitive data without careful review

Exec sandbox (bwrap):

On Linux, set "tools.exec.sandbox": "bwrap" to wrap every shell command in a bubblewrap sandbox. This uses Linux kernel namespaces to restrict what the process can see:

• Workspace directory → read-write (agent works normally)
• Media directory → read-only (can read uploaded attachments)
• System directories (/usr, /bin, /lib) → read-only (commands still work)
• Config files and API keys (~/.nanobot/config.json) → hidden (masked by tmpfs)

Requires bwrap installed (apt install bubblewrap). Pre-installed in the official Docker image. Not available on macOS or Windows — bubblewrap depends on Linux kernel namespaces.

Enabling the sandbox also automatically activates restrictToWorkspace for file tools.

Blocked patterns:

• rm -rf / - Root filesystem deletion
• Fork bombs
• Filesystem formatting (mkfs.*)
• Raw disk writes
• Other destructive operations

File operations have path traversal protection, but:

• ✅ Enable restrictToWorkspace or the bwrap sandbox to confine file access
• ✅ Run nanobot with a dedicated user account
• ✅ Use filesystem permissions to protect sensitive directories
• ✅ Regularly audit file operations in logs
• ❌ Don't give unrestricted access to sensitive files

API Calls:

• All external API calls use HTTPS by default
• Timeouts are configured to prevent hanging requests
• The OpenAI-compatible API server must set api.api_key when binding to 0.0.0.0 or ::; otherwise startup fails to prevent unauthenticated network access
• Consider using a firewall to restrict outbound connections if needed

WhatsApp:

• Keep the neonize session database under ~/.nanobot/whatsapp-auth secure (mode 0700).
• Use nanobot channels login whatsapp --force to remove and recreate the local session database when rotating linked devices.

Critical: Keep dependencies updated!

# Check for vulnerable dependencies
pip install pip-audit
pip-audit

# Update to latest secure versions
pip install --upgrade nanobot-ai

Important Notes:

• Keep litellm updated to the latest version for security fixes
• Run pip-audit regularly, including optional channel dependencies such as nanobot-ai[whatsapp]
• Subscribe to security advisories for nanobot and its dependencies

For production use:

1. Isolate the Environment

   # Run in a container or VM
   docker run --rm -it python:3.11
   pip install nanobot-ai

2. Use a Dedicated User

   sudo useradd -m -s /bin/bash nanobot
   sudo -u nanobot nanobot gateway

3. Set Proper Permissions

   chmod 700 ~/.nanobot
   chmod 600 ~/.nanobot/config.json
   chmod 700 ~/.nanobot/whatsapp-auth

4. Enable Logging

   # Configure log monitoring
   tail -f ~/.nanobot/logs/nanobot.log

5. Use Rate Limiting

   • Configure rate limits on your API providers
   • Monitor usage for anomalies
   • Set spending limits on LLM APIs

6. Regular Updates

   # Check for updates weekly
   pip install --upgrade nanobot-ai

Development:

• Use separate API keys
• Test with non-sensitive data
• Enable verbose logging
• Use a test Telegram bot

Production:

• Use dedicated API keys with spending limits
• Restrict file system access
• Enable audit logging
• Regular security reviews
• Monitor for unusual activity

• Logs may contain sensitive information - secure log files appropriately
• LLM providers see your prompts - review their privacy policies
• Chat history is stored locally - protect the ~/.nanobot directory
• API keys are in plain text - use OS keyring for production

If you suspect a security breach:

1. Immediately revoke compromised API keys
2. Review logs for unauthorized access

   grep "Access denied" ~/.nanobot/logs/nanobot.log

3. Check for unexpected file modifications
4. Rotate all credentials
5. Update to latest version
6. Report the incident to maintainers

The Hosted Worker is an internal Web workload, not a public general-purpose OpenAI endpoint:

• Build it from Dockerfile.hosted, run it as the included non-root user, and set tools.distribution to hosted. The distribution audit must find no Channel SDKs or local shell/filesystem/web/cron/subagent tools.
• Set a unique SAGASMITH_WORKER_SERVICE_TOKEN of at least 32 bytes and keep it scoped to the Web-to-Worker audience. Never pass browser, activity-callback, or unrelated service tokens to a domain MCP.
• Supply authority only in the separately authenticated trusted_context. Player/model text must not choose requester, resource owner, acting Host/character, campaign, revision, audience, allowed operation, expiry, or workspace identity.
• Configure targetService, authorizationAudience, systemIds, and a signing secret per target MCP. Modern calls use short-lived sagasmith.auth-context/v2 delegations; legacy is an explicit rollback adapter, not a session-based authorization boundary.
• Give every persisted workspace a stable, unique Host-issued --workspace-id. Bound it with TTL, byte, and count limits. The worker removes only terminated, marker-owned directories; unknown directories, active workspaces, symlinks, and invalid markers must remain untouched.
• Scrape /metrics/mcp only on the internal network. Its low-cardinality counters intentionally omit users, campaigns, runs, tool names, and arguments. Protect logs and tracing backends because prompts and baggage can still be sensitive.

See the root English or Chinese README and docs/sagasmith-host-adapters.md for the complete request, delegation, media, Tasks, upgrade, and rollback contracts.

✅ Input Validation

• Path traversal protection on file operations
• Dangerous command pattern detection
• Input length limits on HTTP requests

✅ Authentication

• Allow-list based access control — in v0.1.4.post3 and earlier empty allowFrom allowed all; since v0.1.4.post4 it denies all (["*"] explicitly allows all)
• Failed authentication attempt logging

✅ Resource Protection

• Command execution timeouts (60s default)
• Output truncation (10KB limit)
• HTTP request timeouts (10-30s)

✅ Secure Communication

• HTTPS for all external API calls
• TLS for Telegram API
• WhatsApp session secrets stay in the local session database

⚠️ Current Security Limitations:

1. No Rate Limiting - Users can send unlimited messages (add your own if needed)
2. Plain Text Config - API keys stored in plain text (use keyring for production)
3. No Session Management - No automatic session expiry
4. Limited Command Filtering - Only blocks obvious dangerous patterns (enable the bwrap sandbox for kernel-level isolation on Linux)
5. No Audit Trail - Limited security event logging (enhance as needed)

Before deploying nanobot:

• API keys stored securely (not in code)
• Config file permissions set to 0600
• allowFrom lists configured for all channels
• Running as non-root user
• Exec sandbox enabled ("tools.exec.sandbox": "bwrap") on Linux deployments
• File system permissions properly restricted
• Dependencies updated to latest secure versions
• Logs monitored for security events
• Rate limits configured on API providers
• Backup and disaster recovery plan in place
• Security review of custom skills/tools

Last Updated: 2026-04-05

For the latest security updates and announcements, check:

• GitHub Security Advisories: https://github.com/HKUDS/nanobot/security/advisories
• Release Notes: https://github.com/HKUDS/nanobot/releases

See LICENSE file for details.