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

```bash
# 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
```json
{
  "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
```json
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+1234567890", "+0987654321"]
    }
  }
}
```

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

#### Email Example
```json
{
  "channels": {
    "email": {
      "enabled": true,
      "allowFrom": ["user@example.com", "admin@example.com"]
    }
  }
}
```

### 3. Enable Workspace Restrictions

Restrict file operations to a specific directory:

```json
{
  "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!**

```bash
# 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:

```json
{
  "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:

```bash
# 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:

```json
{
  "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:

```bash
# 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

```bash
# Python dependencies
pip install pip-audit
pip-audit

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

#### Review Logs

```bash
# 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:

```bash
# 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**
   ```bash
   # Update config.json with new keys
   nano ~/.nanobot/config.json
   ```

2. **Review logs for unauthorized access**
   ```bash
   grep "Access denied" ~/.nanobot/logs/nanobot.log
   ```

3. **Check for unexpected file modifications**
   ```bash
   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**
   ```bash
   pip install --upgrade nanobot-ai
   ```

6. **Report the incident**
   - Email: xubinrencs@gmail.com
   - Include: Description, steps to reproduce, potential impact

## Additional Resources

- [SECURITY.md](SECURITY.md) - Full security policy and best practices
- [SETUP_GUIDE.md](SETUP_GUIDE.md) - Setup and configuration guide
- [README.md](README.md) - General documentation

## Questions?

If you have security concerns or questions:
- Review [SECURITY.md](SECURITY.md)
- Check nanobot logs for errors
- Contact maintainers: xubinrencs@gmail.com