romtuck/openclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(security): add comprehensive security documentation

Browse Source
This commit is contained in:
Ulrich Diedrichsen 2026-01-30 11:08:47 +01:00
parent a7c5fd342d
commit 9125b3e09f
2 changed files with 807 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

388
docs/security/alerting.md Normal file
View File

@ -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<YOUR_BOT_TOKEN>/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)

419
docs/security/security-shield.md Normal file
View File

@ -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 <trusted-ip> --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)