openclaw/docs/security/security-shield.md

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.

# Check status
openclaw security status

# Enable manually (if disabled)
openclaw security enable

# Disable (not recommended)
openclaw security disable

Configuration

Edit ~/.openclaw/config.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

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

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

# 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

# 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

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

# 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

# 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

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

# 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

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:

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

# Check shield status
openclaw security status

# Enable if needed
openclaw security enable

# Restart gateway
openclaw gateway restart

See Also

• Rate Limiting
• Firewall Integration
• Alerting
• CLI Reference