nanobot/SECURITY_CONFIGURATION.md

Nanobot Security Configuration Guide

This guide provides step-by-step instructions for securing your nanobot installation.

Quick Security Setup

1. Secure Configuration File

# Set proper permissions on config file
chmod 600 ~/.nanobot/config.json

# Set proper permissions on nanobot directory
chmod 700 ~/.nanobot

2. Configure Channel Access Control

CRITICAL: Empty allowFrom lists allow ALL users. Always configure this in production!

Telegram Example

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

To find your Telegram user ID:

1. Message @userinfobot on Telegram
2. Copy your user ID
3. Add it to the allowFrom list

WhatsApp Example

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+1234567890", "+0987654321"]
    }
  }
}

Use full phone numbers with country code (e.g., +1 for US).

Email Example

{
  "channels": {
    "email": {
      "enabled": true,
      "allowFrom": ["user@example.com", "admin@example.com"]
    }
  }
}

3. Enable Workspace Restrictions

Restrict file operations to a specific directory:

{
  "agents": {
    "defaults": {
      "restrictToWorkspace": true
    }
  }
}

This ensures nanobot can only access files within ~/.nanobot/workspace.

4. Run as Non-Root User

NEVER run nanobot as root!

# Create dedicated user
sudo useradd -m -s /bin/bash nanobot

# Switch to nanobot user
sudo -u nanobot bash

# Run nanobot
python3 -m nanobot.cli.commands agent -m "hello"

5. Configure Command Timeouts

Limit command execution time:

{
  "agents": {
    "defaults": {
      "execConfig": {
        "timeout": 30
      }
    }
  }
}

Default is 60 seconds. Reduce for stricter security.

Advanced Security Configuration

1. Custom Command Blocking

You can add custom blocked command patterns by modifying the ExecTool initialization, but this requires code changes. The default patterns block:

• rm -rf, rm -r, rm -f
• format, mkfs.*
• dd if=
• shutdown, reboot, poweroff
• Fork bombs

2. Network Security

Restrict Outbound Connections

Use a firewall to restrict what nanobot can access:

# Example: Only allow HTTPS to specific domains
sudo ufw allow out 443/tcp
sudo ufw deny out 80/tcp  # Block HTTP

WhatsApp Bridge Security

The WhatsApp bridge binds to 127.0.0.1:3001 (localhost only) by default. For additional security:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "bridgeToken": "your-secret-token-here"
    }
  }
}

Set a bridgeToken to enable shared-secret authentication between Python and Node.js components.

3. Log Monitoring

Set up log monitoring to detect security issues:

# Monitor access denials
tail -f ~/.nanobot/logs/nanobot.log | grep "Access denied"

# Monitor blocked commands
tail -f ~/.nanobot/logs/nanobot.log | grep "blocked by safety guard"

# Monitor all tool executions
tail -f ~/.nanobot/logs/nanobot.log | grep "ExecTool:"

4. Regular Security Audits

Check Dependencies

# Python dependencies
pip install pip-audit
pip-audit

# Node.js dependencies (for WhatsApp bridge)
cd bridge
npm audit
npm audit fix

Review Logs

# Check for suspicious activity
grep -i "error\|denied\|blocked" ~/.nanobot/logs/nanobot.log | tail -100

# Check file operations
grep "write_file\|edit_file" ~/.nanobot/logs/nanobot.log | tail -100

5. API Key Rotation

Rotate API keys regularly:

1. Generate new API keys from your provider
2. Update ~/.nanobot/config.json
3. Restart nanobot
4. Revoke old keys after confirming new ones work

6. Environment Isolation

Run nanobot in a container or VM for better isolation:

# Using Docker (if Dockerfile exists)
docker build -t nanobot .
docker run --rm -it \
  -v ~/.nanobot:/root/.nanobot \
  -v ~/.nanobot/workspace:/root/.nanobot/workspace \
  nanobot

Security Checklist

Before deploying nanobot in production:

• Config file permissions set to 0600
• Nanobot directory permissions set to 700
• All channels have allowFrom lists configured
• Running as non-root user
• restrictToWorkspace enabled
• Command timeout configured
• API keys stored securely (not in code)
• Logs monitored for security events
• Dependencies updated and audited
• Firewall rules configured (if needed)
• Backup and disaster recovery plan in place

What Nanobot Cannot Do (Built-in Protections)

Nanobot has built-in protections that prevent:

1. Destructive Commands: rm -rf /, format, mkfs, dd, shutdown, etc.
2. Path Traversal: ../ and ..\\ are blocked when workspace restrictions are enabled
3. System File Access: When restricted, cannot access files outside workspace
4. Unlimited Execution: Commands timeout after configured limit (default 60s)
5. Unlimited Output: Command output truncated at 10KB
6. Unauthorized Access: Channels check allowFrom lists before processing messages

Incident Response

If you suspect a security breach:

1. Immediately revoke compromised API keys

   # Update config.json with new keys
   nano ~/.nanobot/config.json
   

2. Review logs for unauthorized access

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

3. Check for unexpected file modifications

   find ~/.nanobot/workspace -type f -mtime -1 -ls
   

4. Rotate all credentials

   • Update API keys
   • Update channel tokens
   • Update bridge tokens (if using WhatsApp)

5. Update to latest version

   pip install --upgrade nanobot-ai
   

6. Report the incident

   • Email: xubinrencs@gmail.com
   • Include: Description, steps to reproduce, potential impact

Additional Resources

• SECURITY.md - Full security policy and best practices
• SETUP_GUIDE.md - Setup and configuration guide
• README.md - General documentation

Questions?

If you have security concerns or questions:

• Review SECURITY.md
• Check nanobot logs for errors
• Contact maintainers: xubinrencs@gmail.com