From 9125b3e09f3dca27ca10f03cb5a5d14fe5da2e8b Mon Sep 17 00:00:00 2001 From: Ulrich Diedrichsen Date: Fri, 30 Jan 2026 11:08:47 +0100 Subject: [PATCH] docs(security): add comprehensive security documentation --- docs/security/alerting.md | 388 ++++++++++++++++++++++++++++ docs/security/security-shield.md | 419 +++++++++++++++++++++++++++++++ 2 files changed, 807 insertions(+) create mode 100644 docs/security/alerting.md create mode 100644 docs/security/security-shield.md diff --git a/docs/security/alerting.md b/docs/security/alerting.md new file mode 100644 index 000000000..07087a985 --- /dev/null +++ b/docs/security/alerting.md @@ -0,0 +1,388 @@ +# Security Alerting + +Get real-time notifications when security events occur. + +## Overview + +The OpenClaw security alerting system sends notifications through multiple channels when critical security events are detected: + +- Intrusion attempts (brute force, SSRF, port scanning) +- IP address blocks +- Failed authentication spikes +- Critical security events + +## Supported Channels + +- **Telegram** (recommended) - Instant push notifications +- **Webhook** - Generic HTTP POST to any endpoint +- **Slack** (planned) +- **Email** (planned) + +## Telegram Setup + +### 1. Create a Telegram Bot + +1. Open Telegram and message [@BotFather](https://t.me/BotFather) +2. Send `/newbot` and follow the prompts +3. Save the **bot token** (format: `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`) + +### 2. Get Your Chat ID + +**Option A: Use @userinfobot** +1. Message [@userinfobot](https://t.me/userinfobot) +2. It will reply with your user ID (chat ID) + +**Option B: Manual method** +1. Send a message to your bot +2. Visit: `https://api.telegram.org/bot/getUpdates` +3. Look for `"chat":{"id":123456789}` in the JSON response + +### 3. Configure OpenClaw + +Set environment variables: + +```bash +export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11" +export TELEGRAM_CHAT_ID="123456789" +``` + +Or configure directly in `~/.openclaw/config.json`: + +```json +{ + "security": { + "alerting": { + "enabled": true, + "channels": { + "telegram": { + "enabled": true, + "botToken": "${TELEGRAM_BOT_TOKEN}", + "chatId": "${TELEGRAM_CHAT_ID}" + } + } + } + } +} +``` + +### 4. Restart Gateway + +```bash +openclaw gateway restart +``` + +### 5. Test Alerts + +```bash +# Trigger a test by blocking an IP +openclaw blocklist add 192.0.2.1 --reason "test alert" + +# You should receive a Telegram notification +``` + +## Alert Types + +### 1. Intrusion Detected + +Sent when an attack pattern is identified. + +**Example Message:** +``` +🚨 CRITICAL: Intrusion Detected + +Brute force attack detected from IP 192.168.1.100 + +Details: +• pattern: brute_force +• ip: 192.168.1.100 +• attempts: 10 +• threshold: 10 + +2026-01-30 10:30:45 PM +``` + +**Triggers:** +- Brute force (10 failed auth in 10 min) +- SSRF bypass (3 attempts in 5 min) +- Path traversal (5 attempts in 5 min) +- Port scanning (20 connections in 10 sec) + +### 2. IP Blocked + +Sent when an IP is auto-blocked. + +**Example Message:** +``` +⚠️ WARN: IP Address Blocked + +IP 192.168.1.100 has been blocked + +Details: +• reason: brute_force +• expiresAt: 2026-01-31 10:30:45 PM +• source: auto + +2026-01-30 10:30:45 PM +``` + +### 3. Critical Security Event + +Sent for any security event with severity=critical. + +**Example Message:** +``` +🚨 CRITICAL: Critical Security Event + +auth_failed on gateway_auth + +Details: +• ip: 192.168.1.100 +• action: auth_failed +• outcome: deny +• reason: token_mismatch + +2026-01-30 10:30:45 PM +``` + +## Configuration + +### Alert Triggers + +Configure which events trigger alerts: + +```json +{ + "security": { + "alerting": { + "enabled": true, + "triggers": { + "criticalEvents": { + "enabled": true, + "throttleMs": 300000 + }, + "ipBlocked": { + "enabled": true, + "throttleMs": 3600000 + }, + "failedAuthSpike": { + "enabled": true, + "threshold": 20, + "windowMs": 600000, + "throttleMs": 600000 + } + } + } + } +} +``` + +### Throttling + +Prevents alert spam by limiting frequency: + +- **criticalEvents**: Max 1 alert per 5 minutes +- **ipBlocked**: Max 1 alert per hour (per IP) +- **failedAuthSpike**: Max 1 alert per 10 minutes +- **intrusionDetected**: Max 1 alert per 5 minutes + +**Example:** If 3 brute force attacks are detected within 5 minutes, only 1 alert is sent. + +### Disable Specific Alerts + +```json +{ + "security": { + "alerting": { + "enabled": true, + "triggers": { + "criticalEvents": { + "enabled": false + }, + "ipBlocked": { + "enabled": true + } + } + } + } +} +``` + +## Webhook Channel + +Send alerts to any HTTP endpoint. + +### Configuration + +```json +{ + "security": { + "alerting": { + "enabled": true, + "channels": { + "webhook": { + "enabled": true, + "url": "https://hooks.example.com/security" + } + } + } + } +} +``` + +### Webhook Payload + +Alerts are sent as JSON POST requests: + +```json +{ + "id": "abc123...", + "severity": "critical", + "title": "Intrusion Detected", + "message": "Brute force attack detected from IP 192.168.1.100", + "timestamp": "2026-01-30T22:30:45.123Z", + "details": { + "pattern": "brute_force", + "ip": "192.168.1.100", + "attempts": 10, + "threshold": 10 + }, + "trigger": "intrusion_detected" +} +``` + +### Headers + +Add custom headers: + +```json +{ + "security": { + "alerting": { + "channels": { + "webhook": { + "enabled": true, + "url": "https://hooks.example.com/security", + "headers": { + "Authorization": "Bearer ${WEBHOOK_TOKEN}", + "X-Custom-Header": "value" + } + } + } + } + } +} +``` + +## Multiple Channels + +Enable multiple alert channels simultaneously: + +```json +{ + "security": { + "alerting": { + "enabled": true, + "channels": { + "telegram": { + "enabled": true, + "botToken": "${TELEGRAM_BOT_TOKEN}", + "chatId": "${TELEGRAM_CHAT_ID}" + }, + "webhook": { + "enabled": true, + "url": "https://hooks.example.com/security" + } + } + } + } +} +``` + +Alerts will be sent to **all enabled channels**. + +## Troubleshooting + +### Not Receiving Telegram Alerts + +**Check configuration:** +```bash +openclaw security status +``` + +**Verify bot token:** +```bash +curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe" +``` + +**Verify chat ID:** +```bash +curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" +``` + +**Check security logs:** +```bash +openclaw security logs --follow +``` + +Look for lines containing `"alert"` or `"telegram"`. + +### Alerts Are Throttled + +**Symptom:** Not receiving all alerts + +This is expected behavior. Alerts are throttled to prevent spam. + +**Adjust throttle settings:** +```json +{ + "security": { + "alerting": { + "triggers": { + "criticalEvents": { + "throttleMs": 60000 + } + } + } + } +} +``` + +### Webhook Timeouts + +**Symptom:** Webhook alerts fail or delay + +**Solutions:** +- Ensure webhook endpoint responds quickly (<5 seconds) +- Check network connectivity +- Verify webhook URL is correct +- Review webhook endpoint logs + +## Best Practices + +### Telegram + +✅ Use a dedicated bot for OpenClaw +✅ Keep bot token secret (use environment variables) +✅ Test alerts after setup +✅ Use a group chat for team notifications + +### Webhook + +✅ Use HTTPS endpoints only +✅ Implement webhook signature verification +✅ Handle retries gracefully +✅ Monitor webhook endpoint availability + +### General + +✅ Enable alerting in production +✅ Configure at least one alert channel +✅ Test alerts during setup +✅ Review alert frequency (adjust throttling if needed) +✅ Monitor alert delivery (check logs) + +## See Also + +- [Security Shield](/security/security-shield) +- [Security Logs](/security/security-shield#security-event-logging) +- [CLI Reference](/cli/security) diff --git a/docs/security/security-shield.md b/docs/security/security-shield.md new file mode 100644 index 000000000..45a946c4b --- /dev/null +++ b/docs/security/security-shield.md @@ -0,0 +1,419 @@ +# Security Shield + +The OpenClaw Security Shield is a comprehensive defense system that protects your gateway from unauthorized access, brute force attacks, and malicious activity. + +## Overview + +The Security Shield provides layered protection: + +- **Rate Limiting** - Prevents brute force attacks and DoS +- **Intrusion Detection** - Identifies attack patterns automatically +- **IP Blocklist/Allowlist** - Blocks malicious IPs, allows trusted networks +- **Firewall Integration** - Syncs blocks with system firewall (Linux) +- **Security Event Logging** - Audit trail of all security events +- **Real-time Alerting** - Telegram notifications for critical events + +## Quick Start + +### Enable Security Shield + +The security shield is **enabled by default** for new installations. + +```bash +# Check status +openclaw security status + +# Enable manually (if disabled) +openclaw security enable + +# Disable (not recommended) +openclaw security disable +``` + +### Configuration + +Edit `~/.openclaw/config.json`: + +```json +{ + "security": { + "shield": { + "enabled": true, + "rateLimiting": { + "enabled": true + }, + "intrusionDetection": { + "enabled": true + }, + "ipManagement": { + "autoBlock": { + "enabled": true + } + } + } + } +} +``` + +## Rate Limiting + +Prevents brute force and DoS attacks by limiting request rates. + +### Default Limits + +**Per-IP Limits:** +- Auth attempts: 5 per 5 minutes +- Connections: 10 concurrent +- Requests: 100 per minute + +**Per-Device Limits:** +- Auth attempts: 10 per 15 minutes +- Requests: 500 per minute + +**Per-Sender Limits (Pairing):** +- Pairing requests: 3 per hour + +**Webhook Limits:** +- Per token: 200 requests per minute +- Per path: 50 requests per minute + +### Custom Rate Limits + +```json +{ + "security": { + "shield": { + "rateLimiting": { + "enabled": true, + "perIp": { + "authAttempts": { "max": 5, "windowMs": 300000 }, + "connections": { "max": 10, "windowMs": 60000 }, + "requests": { "max": 100, "windowMs": 60000 } + }, + "perDevice": { + "authAttempts": { "max": 10, "windowMs": 900000 } + } + } + } + } +} +``` + +## Intrusion Detection + +Automatically detects and blocks attack patterns. + +### Attack Patterns + +**Brute Force Attack:** +- Threshold: 10 failed auth attempts +- Time window: 10 minutes +- Action: Block IP for 24 hours + +**SSRF Bypass:** +- Threshold: 3 attempts +- Time window: 5 minutes +- Action: Block IP for 24 hours + +**Path Traversal:** +- Threshold: 5 attempts +- Time window: 5 minutes +- Action: Block IP for 24 hours + +**Port Scanning:** +- Threshold: 20 rapid connections +- Time window: 10 seconds +- Action: Block IP for 24 hours + +### Custom Thresholds + +```json +{ + "security": { + "shield": { + "intrusionDetection": { + "enabled": true, + "patterns": { + "bruteForce": { "threshold": 10, "windowMs": 600000 }, + "ssrfBypass": { "threshold": 3, "windowMs": 300000 }, + "pathTraversal": { "threshold": 5, "windowMs": 300000 }, + "portScanning": { "threshold": 20, "windowMs": 10000 } + } + } + } + } +} +``` + +## IP Blocklist & Allowlist + +Manage IP-based access control. + +### Blocklist Commands + +```bash +# List blocked IPs +openclaw blocklist list + +# Block an IP +openclaw blocklist add 192.168.1.100 --reason "manual block" --duration 24h + +# Unblock an IP +openclaw blocklist remove 192.168.1.100 +``` + +### Allowlist Commands + +```bash +# List allowed IPs +openclaw allowlist list + +# Allow an IP or CIDR range +openclaw allowlist add 10.0.0.0/8 --reason "internal network" +openclaw allowlist add 192.168.1.50 --reason "trusted server" + +# Remove from allowlist +openclaw allowlist remove 10.0.0.0/8 +``` + +### Auto-Allowlist + +**Tailscale networks** (100.64.0.0/10) are automatically allowlisted when Tailscale mode is enabled. + +**Localhost** (127.0.0.1, ::1) is always allowed. + +### Precedence + +Allowlist **overrides** blocklist. If an IP is in both lists, it will be allowed. + +## Firewall Integration + +Syncs IP blocks with system firewall (Linux only). + +### Supported Backends + +- **iptables** - Creates dedicated `OPENCLAW_BLOCKLIST` chain +- **ufw** - Uses numbered rules with comments + +### Configuration + +```json +{ + "security": { + "shield": { + "ipManagement": { + "firewall": { + "enabled": true, + "backend": "iptables" + } + } + } + } +} +``` + +### Requirements + +**Permissions:** Requires `sudo` or `CAP_NET_ADMIN` capability. + +**Automatic fallback:** If firewall commands fail, the security shield continues to function (application-level blocking only). + +### Manual Verification + +```bash +# Check iptables rules +sudo iptables -L OPENCLAW_BLOCKLIST -n + +# Check ufw rules +sudo ufw status numbered +``` + +## Security Event Logging + +All security events are logged for audit trail. + +### Log Files + +Location: `/tmp/openclaw/security-YYYY-MM-DD.jsonl` + +Format: JSON Lines (one event per line) + +Rotation: Daily (new file each day) + +### View Logs + +```bash +# View last 50 events +openclaw security logs + +# View last 100 events +openclaw security logs --lines 100 + +# Follow logs in real-time +openclaw security logs --follow + +# Filter by severity +openclaw security logs --severity critical +openclaw security logs --severity warn +``` + +### Event Structure + +```json +{ + "timestamp": "2026-01-30T22:15:30.123Z", + "eventId": "abc123...", + "severity": "warn", + "category": "authentication", + "ip": "192.168.1.100", + "action": "auth_failed", + "outcome": "deny", + "details": { + "reason": "token_mismatch" + } +} +``` + +### Event Categories + +- `authentication` - Auth attempts, token validation +- `authorization` - Access control decisions +- `rate_limit` - Rate limit violations +- `intrusion_attempt` - Detected attack patterns +- `network_access` - Connection attempts +- `pairing` - Pairing requests + +## Security Audit + +Run comprehensive security audit: + +```bash +# Quick audit +openclaw security audit + +# Deep audit (includes gateway probe) +openclaw security audit --deep + +# Apply automatic fixes +openclaw security audit --fix + +# JSON output +openclaw security audit --json +``` + +### Audit Checks + +- Gateway binding configuration +- Authentication token strength +- File permissions (config, state, credentials) +- Channel security settings (allowlist/pairing) +- Exposed sensitive data +- Legacy configuration issues + +## Best Practices + +### Deployment Checklist + +✅ Enable security shield (default) +✅ Use strong gateway auth token +✅ Bind gateway to loopback or tailnet (not LAN/internet) +✅ Enable firewall integration (Linux) +✅ Configure Telegram alerts +✅ Review allowlist for trusted IPs +✅ Run `openclaw security audit --deep` + +### Production Recommendations + +**Network Binding:** +- Use `gateway.bind: "loopback"` for local-only access +- Use `gateway.bind: "tailnet"` for Tailscale-only access +- Avoid `gateway.bind: "lan"` or `"auto"` in production + +**Authentication:** +- Use token mode (default) with strong random tokens +- Rotate tokens periodically +- Never commit tokens to version control + +**Monitoring:** +- Enable Telegram alerts for critical events +- Review security logs weekly +- Monitor blocked IPs for patterns + +**Firewall:** +- Enable firewall integration on Linux +- Verify firewall rules after deployment +- Test access from both allowed and blocked IPs + +### Common Pitfalls + +❌ Exposing gateway to LAN without auth +❌ Using weak or default tokens +❌ Disabling security shield +❌ Ignoring intrusion detection alerts +❌ Not monitoring security logs + +## Troubleshooting + +### High Rate of Blocks + +**Symptom:** Legitimate users getting blocked + +**Solution:** +1. Check rate limits - may be too restrictive +2. Add trusted IPs to allowlist +3. Review security logs to identify cause + +```bash +openclaw security logs --severity warn +openclaw allowlist add --reason "trusted user" +``` + +### Firewall Integration Not Working + +**Symptom:** IPs not blocked at firewall level + +**Possible Causes:** +- Missing sudo permissions +- Backend not installed (iptables/ufw) +- Wrong backend configured + +**Solution:** +```bash +# Check backend availability +which iptables +which ufw + +# Verify permissions +sudo iptables -L OPENCLAW_BLOCKLIST -n + +# Check security logs +openclaw security logs | grep firewall +``` + +### Missing Security Logs + +**Symptom:** No log files in `/tmp/openclaw/` + +**Possible Causes:** +- Security shield disabled +- No security events occurred +- Insufficient permissions + +**Solution:** +```bash +# Check shield status +openclaw security status + +# Enable if needed +openclaw security enable + +# Restart gateway +openclaw gateway restart +``` + +## See Also + +- [Rate Limiting](/security/rate-limiting) +- [Firewall Integration](/security/firewall) +- [Alerting](/security/alerting) +- [CLI Reference](/cli/security)