SECURITY.md

Rama main · réplica de lectura del repositorio original.

# Security Policy

## Reporting a Vulnerability

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

1. **DO NOT** open a public GitHub issue
2. Create a private security advisory through the repository's configured security contact
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.

## Security Best Practices

### 1. API Key Management

**CRITICAL**: Never commit API keys to version control.

```bash
# ✅ Best: Use environment variable references in config (never writes the key to disk)
# In ~/.pawbot/config.json:
#   "apiKey": "${ANTHROPIC_API_KEY}"
# Then supply the key at runtime via env var or Docker secret.

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

# ❌ Bad: Hardcoding keys in code or committing them
```

**Recommendations:**
- **Prefer environment variable references** (`${VAR}`) in config — the config file stores the `${VAR}` placeholder, and the plaintext value only exists in memory at runtime. See the [README security boundary](README.md#security-and-data-boundary) for details.
- When plaintext keys are stored in `~/.pawbot/config.json`, set file permissions to `0600` (`chmod 600`)
- Consider using an OS keyring/credential manager for production deployments
- Rotate API keys regularly
- Use separate API keys for development and production

### 2. Channel Access Control

**IMPORTANT**: Always configure `allowFrom` lists for production use.

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

### 3. Shell Command Execution

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 pawbot 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](https://github.com/containers/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 (`~/.pawbot/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.

**Shell network isolation:**

By default, sandboxed shell commands retain normal network access. On Linux you can explicitly
deny network access for the `exec` Tool by combining Bubblewrap with:

```json
{
  "tools": {
    "exec": {
      "sandbox": "bwrap",
      "networkPolicy": "deny"
    }
  }
}
```

This adds Bubblewrap's `--unshare-net` isolation. `networkPolicy: "deny"` deliberately fails
closed when `bwrap` is unavailable, including on Windows and macOS; Pawbot does not claim a
kernel-level network boundary where it cannot enforce one. This policy applies to shell commands,
not to the configured model provider or dedicated web Tools.

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

### 4. File System Access

File operations have path traversal protection, but:

- ✅ Enable `restrictToWorkspace` or the bwrap sandbox to confine file access
- ✅ Run pawbot 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

### 5. Network Security

**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 `~/.pawbot/whatsapp-auth` secure (mode 0700).
- Use `pawbot channels login whatsapp --force` to remove and recreate the local session database when rotating linked devices.

### 6. Dependency Security

**Critical**: Keep dependencies updated!

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

# Update to latest secure versions
pip install --upgrade pawbot-ai
```

**Important Notes:**
- Keep `litellm` updated to the latest version for security fixes
- Run `pip-audit` regularly after enabling the channels used in production; their manifest-declared dependencies are installed into the same environment
- Subscribe to security advisories for pawbot and its dependencies

### 7. Production Deployment

For production use:

1. **Isolate the Environment**
   ```bash
   # Run in a container or VM
   docker run --rm -it python:3.11
   pip install pawbot-ai
   ```

2. **Use a Dedicated User**
   ```bash
   sudo useradd -m -s /bin/bash pawbot
   sudo -u pawbot pawbot gateway
   ```

3. **Set Proper Permissions**
   ```bash
   chmod 700 ~/.pawbot
   chmod 600 ~/.pawbot/config.json
   chmod 700 ~/.pawbot/whatsapp-auth
   ```

4. **Enable Logging**
   ```bash
   # Configure log monitoring
   tail -f ~/.pawbot/logs/pawbot.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**
   ```bash
   # Check for updates weekly
   pip install --upgrade pawbot-ai
   ```

### 8. Development vs Production

**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

### 9. Data Privacy

- **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 `~/.pawbot` directory
- **API keys are in plain text** - use OS keyring for production

### 10. Incident Response

If you suspect a security breach:

1. **Immediately revoke compromised API keys**
2. **Review logs for unauthorized access**
   ```bash
   grep "Access denied" ~/.pawbot/logs/pawbot.log
   ```
3. **Check for unexpected file modifications**
4. **Rotate all credentials**
5. **Update to latest version**
6. **Report the incident** through the project's private security contact

## Security Features

### Built-in Security Controls

✅ **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

## Known Limitations

⚠️ **Current Security Limitations:**

1. **No distributed rate limiting** - Optional process-local request guards are
   available through `PAWBOT_MAX_CONCURRENT_REQUESTS`,
   `PAWBOT_MAX_CONCURRENT_PER_SENDER`, `PAWBOT_PROVIDER_MAX_INFLIGHT`, and
   `PAWBOT_PROVIDER_RPM`. Multi-instance deployments still need an external
   gateway or quota service.
2. **Plain Text Config** - API keys can still be stored in `config.json`; prefer
   `${VAR}` environment references or an OS keyring for production.
3. **Local session state** - Sessions, checkpoints, traces, and recordings are
   local files; there is no shared durable session store across instances.
4. **Limited Command Filtering** - Pattern filtering is not a security boundary.
   Enable the bwrap sandbox for kernel-level isolation on Linux; use
   `networkPolicy: "deny"` when shell network isolation is required.
5. **Local audit surface** - Trace and Record & Replay provide local diagnostic
   evidence, not a centralized tamper-resistant compliance audit system.

## Security Checklist

Before deploying pawbot:

- [ ] 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

## Updates

**Last Updated**: 2026-07-21

For the latest security updates and announcements, check:
- Private security advisories: use the repository's configured security reporting mechanism.
- Release notes: see the repository's release page and [`CHANGELOG.md`](CHANGELOG.md).

## License

See LICENSE file for details.