---
alwaysApply: true
description: Security rules and restrictions for nanobot to prevent unauthorized access and dangerous operations
---

# Nanobot Security Rules

## CRITICAL: What Nanobot CANNOT Do

### 1. System-Level Restrictions

**NEVER allow nanobot to:**
- Execute destructive system commands (`rm -rf /`, `format`, `mkfs`, `dd`, `shutdown`, `reboot`, `poweroff`)
- Access files outside the configured workspace when `restrict_to_workspace` is enabled
- Modify system configuration files (`/etc/*`, `/root/.ssh/*`, `/root/.bashrc`, `/root/.zshrc`)
- Access or modify files in `~/.nanobot/config.json` or other nanobot configuration files
- Execute commands that could compromise system security (privilege escalation, network scanning, etc.)
- Access sensitive directories like `/etc/passwd`, `/etc/shadow`, `/proc/sys/*`, `/sys/*`
- Modify or delete files in `/usr/bin`, `/usr/local/bin`, `/bin`, `/sbin`, or other system directories
- Install or uninstall system packages without explicit user permission
- Modify firewall rules or network configuration
- Access or modify Docker containers or images without explicit permission

### 2. Network Security Restrictions

**NEVER allow nanobot to:**
- Make outbound network connections to unauthorized endpoints
- Expose internal services to external networks
- Bypass authentication on network services
- Access localhost-only services from external networks
- Modify network routing or firewall rules

### 3. Authentication & Access Control

**MUST enforce:**
- All channels MUST have `allowFrom` lists configured in production
- Empty `allowFrom` lists allow ALL users (security risk in production)
- Authentication failures MUST be logged
- API keys MUST be stored securely (not in code, use `~/.nanobot/config.json` with `chmod 600`)
- Never commit API keys or tokens to version control

### 4. File System Security

**Restrictions:**
- When `restrict_to_workspace` is enabled, all file operations MUST stay within the workspace directory
- Path traversal attempts (`../`, `..\\`) MUST be blocked
- File operations on sensitive paths MUST be blocked:
  - `~/.nanobot/config.json` (read-only for configuration, never modify)
  - `~/.ssh/*` (SSH keys)
  - `/etc/*` (system configuration)
  - `/root/.bashrc`, `/root/.zshrc` (shell configuration)
  - System binaries in `/usr/bin`, `/bin`, `/sbin`

### 5. Command Execution Security

**Blocked command patterns (already implemented in [shell.py](mdc:nanobot/agent/tools/shell.py)):**
- `rm -rf`, `rm -r`, `rm -f` (recursive deletion)
- `format`, `mkfs.*` (disk formatting)
- `dd if=` (raw disk writes)
- `shutdown`, `reboot`, `poweroff` (system power control)
- Fork bombs (`:(){ :|:& };:`)
- Commands writing to `/dev/sd*` (raw disk access)

**Additional restrictions to enforce:**
- Commands that modify system packages (`apt install`, `pip install --break-system-packages` without explicit permission)
- Commands that modify system services (`systemctl`, `service`)
- Commands accessing `/proc/sys/*` or `/sys/*` (kernel parameters)
- Commands that could leak sensitive information (`cat /etc/passwd`, `env`, `history`)

### 6. Data Privacy & Confidentiality

**NEVER allow nanobot to:**
- Expose API keys, tokens, or credentials in logs or responses
- Share sensitive user data with external services without explicit permission
- Store sensitive data in plain text (use encryption or secure storage)
- Log sensitive information (passwords, API keys, personal data)

## Security Configuration Requirements

### Production Deployment Checklist

Before deploying nanobot in production, verify:

1. **API Key Security**
   ```bash
   chmod 600 ~/.nanobot/config.json
   ```
   - API keys stored in config file (not hardcoded)
   - Config file permissions set to `0600`
   - Consider using environment variables or OS keyring for sensitive keys

2. **Channel Access Control**
   ```json
   {
     "channels": {
       "telegram": {
         "enabled": true,
         "token": "YOUR_TOKEN",
         "allowFrom": ["123456789"]  // MUST be configured in production
       }
     }
   }
   ```
   - All channels have `allowFrom` lists configured
   - Empty `allowFrom` = ALLOW ALL (security risk)

3. **Workspace Restrictions**
   ```json
   {
     "agents": {
       "defaults": {
         "restrictToWorkspace": true  // Recommended for production
       }
     }
   }
   ```
   - Enable `restrictToWorkspace` to limit file operations
   - Set workspace to a dedicated directory with proper permissions

4. **User Account**
   - Run nanobot as a dedicated non-root user
   - Use `sudo useradd -m -s /bin/bash nanobot`
   - Never run as root user

5. **File Permissions**
   ```bash
   chmod 700 ~/.nanobot
   chmod 600 ~/.nanobot/config.json
   chmod 700 ~/.nanobot/whatsapp-auth  # if using WhatsApp
   ```

6. **Network Security**
   - WhatsApp bridge binds to `127.0.0.1:3001` (localhost only)
   - Set `bridgeToken` in config for shared-secret authentication
   - Use firewall to restrict outbound connections if needed

## Security Monitoring

### Log Monitoring

Monitor logs for security events:
```bash
# Check for access denials
grep "Access denied" ~/.nanobot/logs/nanobot.log

# Check for blocked commands
grep "blocked by safety guard" ~/.nanobot/logs/nanobot.log

# Review all tool executions
grep "ExecTool:" ~/.nanobot/logs/nanobot.log
```

### Regular Security Audits

1. Review all tool usage in agent logs
2. Check for unexpected file modifications
3. Monitor API key usage for anomalies
4. Review channel access logs
5. Update dependencies regularly (`pip-audit`, `npm audit`)

## Incident Response

If security breach is suspected:

1. **Immediately revoke compromised API keys**
2. **Review logs for unauthorized access**
3. **Check for unexpected file modifications**
4. **Rotate all credentials**
5. **Update to latest version**
6. **Report to maintainers** (xubinrencs@gmail.com)

## Code Security Guidelines

When modifying nanobot code:

1. **Never remove security checks** from [shell.py](mdc:nanobot/agent/tools/shell.py)
2. **Always validate user input** before processing
3. **Enforce path restrictions** in filesystem tools ([filesystem.py](mdc:nanobot/agent/tools/filesystem.py))
4. **Check `allowFrom` lists** in channel handlers ([base.py](mdc:nanobot/channels/base.py))
5. **Log security events** (access denials, blocked commands)
6. **Never expose sensitive data** in error messages or logs
7. **Use parameterized queries** if adding database functionality
8. **Validate file paths** to prevent path traversal attacks
9. **Sanitize command inputs** before execution
10. **Rate limit** API calls to prevent abuse

## Tool-Specific Security Rules

### ExecTool Security
- Commands MUST be validated against deny patterns
- Timeout MUST be enforced (default 60s, configurable)
- Output MUST be truncated (10KB limit)
- Working directory MUST be restricted when `restrict_to_workspace` is enabled

### Filesystem Tools Security
- Path resolution MUST check against `allowed_dir` when set
- Path traversal (`../`, `..\\`) MUST be blocked
- File operations MUST respect workspace restrictions
- Sensitive file paths MUST be blocked (config files, SSH keys, system files)

### Web Tools Security
- HTTP requests MUST have timeouts (10-30s)
- URLs MUST be validated before fetching
- Content MUST be truncated (50KB limit for web_fetch)
- External API calls MUST use HTTPS

### Channel Security
- `is_allowed()` MUST be called before processing messages
- Access denials MUST be logged
- Empty `allowFrom` lists MUST be documented as "allow all"
- Authentication tokens MUST be stored securely

## References

- Security documentation: [SECURITY.md](mdc:SECURITY.md)
- Shell tool implementation: [nanobot/agent/tools/shell.py](mdc:nanobot/agent/tools/shell.py)
- Filesystem tools: [nanobot/agent/tools/filesystem.py](mdc:nanobot/agent/tools/filesystem.py)
- Channel base class: [nanobot/channels/base.py](mdc:nanobot/channels/base.py)
- Configuration schema: [nanobot/config/schema.py](mdc:nanobot/config/schema.py)
