233 lines
6.7 KiB
Markdown
233 lines
6.7 KiB
Markdown
# OpenClaw Hardening Guide
|
|
|
|
Based on the AI SAFE2 framework. Focuses on proven, working security measures.
|
|
|
|
## ⚠️ IMPORTANT: OpenClaw Security Reality
|
|
|
|
**OpenClaw already has strong security defaults built-in:**
|
|
- Secure authentication required by default
|
|
- Strong account/workspace isolation
|
|
- CSRF protections for state-changing requests
|
|
- Secrets encrypted at rest
|
|
- Private-by-default networking (localhost binding)
|
|
- Secure OAuth flows (state/PKCE)
|
|
|
|
**This guide helps you verify and enhance what's already there.**
|
|
|
|
## Prerequisites
|
|
|
|
- SSH access to server running OpenClaw (or local tmux session)
|
|
- Basic command line knowledge
|
|
|
|
## Step 1: Verify Network Security (2 min)
|
|
|
|
```bash
|
|
# Check current binding
|
|
netstat -an | grep -E "8080|18789|8888" | grep LISTEN
|
|
|
|
# SECURE if you see:
|
|
# tcp4 0 0 127.0.0.1.18789 *.* LISTEN
|
|
# tcp6 0 0 ::1.18789 *.* LISTEN
|
|
|
|
# EXPOSED if you see:
|
|
# tcp4 0 0 0.0.0.0.18789 *.* LISTEN ← BAD!
|
|
|
|
# If exposed, restart bound to localhost only:
|
|
pkill -f "openclaw gateway"
|
|
openclaw gateway --bind 127.0.0.1 --port 18789
|
|
|
|
# Access via SSH tunnel from laptop:
|
|
ssh -L 18789:127.0.0.1:18789 user@server
|
|
```
|
|
|
|
**Note:** OpenClaw's default `gateway.bind: "loopback"` config already binds to localhost. Most installations are secure by default.
|
|
|
|
## Step 2: Lock File Permissions (1 min)
|
|
|
|
```bash
|
|
chmod 700 ~/.openclaw
|
|
chmod 600 ~/.openclaw/openclaw.json
|
|
chmod 600 ~/.openclaw/*.log 2>/dev/null || true
|
|
chmod 600 ~/.openclaw/.env 2>/dev/null || true
|
|
chmod 700 ~/.openclaw/credentials 2>/dev/null || true
|
|
```
|
|
|
|
**Verify:**
|
|
```bash
|
|
ls -la ~/.openclaw/ | head -5
|
|
# Should show: drwx------ for .openclaw
|
|
# Should show: -rw------- for openclaw.json
|
|
```
|
|
|
|
## Step 3: Run Security Audit (2 min)
|
|
|
|
⚠️ **SKIP manual config edits for tool restrictions.** OpenClaw's config schema doesn't support the following fields:
|
|
- ❌ `logging.redactSensitive`
|
|
- ❌ `logging.enabled`
|
|
- ❌ `agents.defaults.tools`
|
|
- ❌ `agents.defaults.sandbox`
|
|
|
|
These fields will cause config validation errors. OpenClaw has built-in security controls that work differently.
|
|
|
|
**Instead, run the built-in security tools:**
|
|
|
|
```bash
|
|
# Validate config
|
|
openclaw doctor --fix
|
|
|
|
# Run deep security audit
|
|
openclaw security audit --deep
|
|
```
|
|
|
|
**Target result:** `0 critical · 0-3 warn · 1 info`
|
|
|
|
**Common warnings (non-critical):**
|
|
- `gateway.trusted_proxies_missing` - OK if localhost-only
|
|
- `channels.discord.dm.scope_main_multiuser` - Optional session isolation
|
|
- `fs.credentials_dir.perms_readable` - Fixed by Step 2
|
|
|
|
## Step 4: Rotate Secrets (3 min)
|
|
|
|
**Use OpenClaw's built-in authentication commands (safe, no shell modification):**
|
|
|
|
1. Generate new API keys from each provider console
|
|
2. Update via OpenClaw's secure method:
|
|
|
|
```bash
|
|
# Interactive authentication (recommended)
|
|
openclaw models auth paste-token
|
|
|
|
# Or use environment variables (set these in your terminal session)
|
|
export ZAI_API_KEY="sk-..."
|
|
export ANTHROPIC_API_KEY="sk-..."
|
|
```
|
|
|
|
3. Delete old keys from provider console
|
|
|
|
**⚠️ IMPORTANT:** Do NOT modify shell startup files (`~/.bashrc`, `~/.zshrc`) directly. Instead:
|
|
- Use OpenClaw's `openclaw models auth` command for permanent storage
|
|
- Or set environment variables in your current terminal session only
|
|
|
|
**Verify auth status:**
|
|
```bash
|
|
openclaw models status
|
|
# Check "Auth overview" section
|
|
# Look for OAuth expiration dates
|
|
```
|
|
|
|
## Step 5: Git-Track Config for Rollback (2 min)
|
|
|
|
```bash
|
|
cd ~/.openclaw
|
|
|
|
# Initialize git if not already done
|
|
git init 2>/dev/null || true
|
|
|
|
# Create .gitignore
|
|
printf 'agents/*/sessions/\nagents/*/agent/*.jsonl\n*.log\n' > .gitignore
|
|
|
|
# Commit current config
|
|
git add .gitignore openclaw.json agents/*/agent/auth-profiles.json agents/*/agent/models.json
|
|
git commit -m "security: baseline hardened config"
|
|
|
|
# View commit history for rollback
|
|
git log --oneline
|
|
```
|
|
|
|
**To rollback:**
|
|
```bash
|
|
cd ~/.openclaw
|
|
git log --oneline # Find commit hash
|
|
git checkout <commit-hash> -- openclaw.json
|
|
openclaw doctor --fix # Validate after rollback
|
|
```
|
|
|
|
## Step 6: Optional Backups
|
|
|
|
**⚠️ MANUAL SETUP REQUIRED:** This skill does NOT automatically set up cron jobs or modify system schedules for security reasons.
|
|
|
|
If you want automated backups, manually create a backup script and schedule it yourself:
|
|
|
|
1. Create backup script manually: `~/backup-openclaw.sh`
|
|
2. Make it executable: `chmod +x ~/backup-openclaw.sh`
|
|
3. **Manually** add to crontab using `crontab -e`
|
|
|
|
**Example backup script content** (create this yourself):
|
|
```bash
|
|
#!/bin/bash
|
|
DATE=$(date +%Y%m%d)
|
|
mkdir -p ~/backups
|
|
tar -czf ~/backups/openclaw-$DATE.tar.gz ~/.openclaw/openclaw.json ~/.openclaw/agents/
|
|
find ~/backups/ -name "openclaw-*.tar.gz" -mtime +30 -delete
|
|
```
|
|
|
|
**This skill will NOT create or schedule this for you.** You must do this manually if desired.
|
|
|
|
## Optional: Isolate Discord DM Sessions
|
|
|
|
If you have multiple users DMing your bot, add to `openclaw.json`:
|
|
|
|
```json
|
|
{
|
|
"session": {
|
|
"dmScope": "per-channel-peer"
|
|
}
|
|
}
|
|
```
|
|
|
|
This prevents context leakage between different DM senders.
|
|
|
|
## Verification Checklist
|
|
|
|
After hardening, verify with:
|
|
|
|
```bash
|
|
# 1. Network security
|
|
netstat -an | grep 18789 | grep LISTEN
|
|
# Should show: 127.0.0.1 or ::1 (NOT 0.0.0.0)
|
|
|
|
# 2. File permissions
|
|
ls -la ~/.openclaw/ | head -5
|
|
# Should show: drwx------ for directory
|
|
|
|
# 3. Security audit
|
|
openclaw security audit --deep
|
|
# Target: 0 critical · 0-2 warn · 1 info
|
|
|
|
# 4. Config validity
|
|
openclaw doctor --fix
|
|
# Should complete without errors
|
|
|
|
# 5. Gateway health
|
|
openclaw health
|
|
# Should show: Discord: ok, Agents: main
|
|
```
|
|
|
|
## Safety Rules
|
|
|
|
1. **Human approval** for external comms (email, social media, purchases)
|
|
2. **Dedicated bot accounts** — never use personal credentials
|
|
3. **Separate machine** — don't run OpenClaw on your personal laptop with sensitive files
|
|
4. **Rotate keys** every 90 days minimum, immediately after any suspected compromise
|
|
|
|
## What OpenClaw Already Provides
|
|
|
|
You don't need to manually configure these - they're built-in:
|
|
|
|
✅ Secure authentication required by default
|
|
✅ Strong account/workspace isolation across all actions
|
|
✅ CSRF protections for state-changing requests
|
|
✅ Strict origin checks to block cross-site attacks
|
|
✅ WebSocket origin validation to prevent hijacking
|
|
✅ Rate limiting and abuse prevention on sensitive endpoints
|
|
✅ Secrets encrypted at rest
|
|
✅ Secrets transmitted securely and never logged
|
|
✅ Short-lived/rotating access credentials where applicable
|
|
✅ Private-by-default networking
|
|
✅ Tight allowlists for any browser-accessible control surfaces
|
|
✅ Secure OAuth flows (state/PKCE) for supported providers
|
|
✅ Security-focused HTTP headers (CSP, clickjacking, etc.)
|
|
✅ Least-privilege runtime (non-root) for services
|
|
|
|
**Your job:** Verify these are working, lock down file permissions, and maintain good operational security practices.
|