openclaw/docs/enterprise/security-hardening.md

# Security Hardening Guide

This guide covers security configuration for enterprise deployments.

## Authentication

### Gateway Authentication

Always enable authentication for production deployments:

```yaml
# config.yaml
gateway:
  auth:
    mode: token  # or "password"
    token: ${GATEWAY_TOKEN}  # Use environment variable
```

**Token vs Password:**
- **Token:** Preferred for API clients and automation
- **Password:** Suitable for interactive users

Generate a secure token:

```bash
openssl rand -base64 32
```

### Device Pairing

For remote access, use device pairing with cryptographic identity:

```yaml
gateway:
  auth:
    mode: token
    token: ${GATEWAY_TOKEN}
```

Paired devices receive a device token after approval, eliminating the need to share the gateway token.

### Tailscale Authentication

For zero-trust networking with Tailscale:

```yaml
gateway:
  auth:
    mode: tailscale
    allowTailscale: true
```

## Role-Based Access Control (RBAC)

Enable RBAC to restrict user permissions:

```yaml
rbac:
  enabled: true
  defaultRole: user  # Fallback for unassigned users

  roles:
    # Custom role for DevOps team
    devops:
      name: "DevOps Engineer"
      permissions:
        - exec           # Basic command execution
        - exec.elevated  # Sudo/admin commands
        - exec.approve   # Can approve exec requests
      agents:
        - main
        - deploy

    # Restricted role for support
    support:
      name: "Support Agent"
      permissions:
        - exec
      tools:
        deny:
          - bash
          - write

  assignments:
    "admin@company.com": admin
    "devops@company.com": devops
    "support@company.com": support
```

### Permission Levels

| Permission | Description |
|------------|-------------|
| `exec` | Execute basic commands |
| `exec.elevated` | Execute sudo/admin commands |
| `exec.approve` | Approve exec requests from agents |
| `admin` | Full access (grants all permissions) |
| `read-only` | View-only access, no tool execution |

### Tool Restrictions

Restrict specific tools per role:

```yaml
roles:
  limited:
    name: "Limited User"
    permissions: [exec]
    tools:
      allow:
        - read
        - search
        - glob
      deny:
        - bash
        - write
        - edit
```

## Audit Logging

All security-relevant events are logged to `~/.clawdbot/audit.jsonl`:

```yaml
# Audit logging is enabled by default
# Configure retention in gateway settings
gateway:
  audit:
    enabled: true
    retentionDays: 30  # Keep logs for 30 days
```

### Audited Events

| Event Type | Description |
|------------|-------------|
| `auth.login` | Successful authentication |
| `auth.failure` | Failed authentication attempt |
| `pairing.request` | Device pairing request |
| `pairing.approve` | Device pairing approved |
| `pairing.reject` | Device pairing rejected |
| `exec.request` | Command execution requested |
| `exec.approve` | Command execution approved |
| `exec.reject` | Command execution rejected |
| `rbac.denied` | RBAC permission denied |
| `config.change` | Configuration modified |

### Audit Log Format

Each entry is a JSON line:

```json
{
  "ts": "2024-01-15T10:30:00.000Z",
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "auth.login",
  "actor": {
    "type": "device",
    "id": "device-abc123",
    "remoteIp": "192.168.1.100"
  },
  "outcome": "success",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "metadata": {
    "method": "device-token"
  }
}
```

### Querying Audit Logs

```bash
# Find all failed auth attempts
cat ~/.clawdbot/audit.jsonl | jq 'select(.type == "auth.failure")'

# Find RBAC denials for a user
cat ~/.clawdbot/audit.jsonl | jq 'select(.type == "rbac.denied" and .actor.id == "user@company.com")'

# Count events by type
cat ~/.clawdbot/audit.jsonl | jq -s 'group_by(.type) | map({type: .[0].type, count: length})'
```

## Rate Limiting

The gateway includes built-in rate limiting to prevent abuse:

```yaml
gateway:
  rateLimit:
    enabled: true
    windowMs: 60000      # 1 minute window
    maxRequests: 100     # Max requests per window
    maxConnections: 50   # Max concurrent WebSocket connections
```

### Pairing Rate Limits

Pairing attempts are rate-limited to prevent brute-force attacks:
- Maximum 10 attempts per minute per channel
- Automatic backoff on repeated failures

## TLS Configuration

### With Reverse Proxy (Recommended)

Terminate TLS at your reverse proxy (nginx, Caddy, Traefik):

```nginx
server {
    listen 443 ssl http2;
    server_name gateway.company.com;

    ssl_certificate /etc/ssl/certs/gateway.crt;
    ssl_certificate_key /etc/ssl/private/gateway.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;

    # HSTS
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    location / {
        proxy_pass http://localhost:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

### Trusted Proxies

When behind a proxy, configure trusted proxy addresses:

```yaml
gateway:
  trustedProxies:
    - "127.0.0.1"
    - "10.0.0.0/8"
    - "172.16.0.0/12"
```

This ensures client IP addresses are correctly extracted from `X-Forwarded-For` headers.

## Command Execution Security

### Exec Approvals

Require human approval for dangerous commands:

```yaml
approvals:
  exec:
    enabled: true
    requireApproval:
      - elevated  # Require approval for sudo commands
      - destructive  # Require approval for rm, delete, etc.
    timeoutMs: 120000  # 2 minute timeout
```

### Sandbox Mode

Run commands in a restricted sandbox:

```yaml
tools:
  policy: sandbox  # Restrict file system access
```

### Command Blocklist

Block dangerous command patterns:

```yaml
tools:
  exec:
    blocklist:
      - "rm -rf /"
      - ":(){ :|:& };:"  # Fork bomb
      - "dd if=/dev/zero"
```

## Secrets Management

### Environment Variables

Store secrets in environment variables, not config files:

```yaml
# config.yaml - reference environment variables
gateway:
  auth:
    token: ${GATEWAY_TOKEN}

models:
  anthropic:
    apiKey: ${ANTHROPIC_API_KEY}
```

### Credential Storage

Channel credentials are stored with restricted permissions:
- Location: `~/.clawdbot/credentials/`
- Permissions: `0600` (owner read/write only)

Run security checks:

```bash
clawdbot doctor --check credentials
```

## Network Security

### Bind Address

Restrict which interfaces accept connections:

```yaml
gateway:
  # Localhost only (most secure)
  bind: "127.0.0.1"

  # All interfaces (for remote access)
  bind: "0.0.0.0"
```

### Firewall Rules

Minimal required firewall rules:

```bash
# Allow gateway port from trusted networks
iptables -A INPUT -p tcp --dport 18789 -s 10.0.0.0/8 -j ACCEPT
iptables -A INPUT -p tcp --dport 18789 -j DROP

# Allow outbound HTTPS for APIs
iptables -A OUTPUT -p tcp --dport 443 -j ACCEPT
```

## Security Checklist

### Pre-Production

- [ ] Enable gateway authentication (`gateway.auth.mode`)
- [ ] Configure RBAC with least-privilege roles
- [ ] Set up TLS termination
- [ ] Configure trusted proxies
- [ ] Enable audit logging
- [ ] Review rate limiting settings
- [ ] Remove default/test credentials

### Ongoing

- [ ] Rotate gateway tokens quarterly
- [ ] Review audit logs for anomalies
- [ ] Update to latest Clawdbot version
- [ ] Review RBAC assignments when team changes
- [ ] Test backup and recovery procedures

## Next Steps

- [Enterprise Deployment](/enterprise/deployment) - Deployment patterns
- [Observability](/enterprise/observability) - Monitoring and alerting
- [Gateway Security Reference](/gateway/security) - Detailed security documentation