Security Best Practices

Hardening your ZeroClaw deployment

Follow these security best practices to deploy ZeroClaw safely in production.

Principle: Defense in Depth

ZeroClaw implements multiple security layers:

1. Authentication - Pairing codes, API keys, allowlists
2. Authorization - Autonomy levels, approval prompts
3. Validation - Command filtering, path checking
4. Sandboxing - Process isolation, resource limits
5. Monitoring - Audit logs, anomaly detection

Authentication

API Keys

Never commit API keys to version control.

Best practices:

# Store in environment variables, not config files
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# Use secret management in production
# AWS Secrets Manager
aws secretsmanager get-secret-value --secret-id zeroclaw/anthropic-key

# HashiCorp Vault
vault kv get secret/zeroclaw/api-keys

Gateway Pairing

Always enable pairing for internet-exposed gateways:

[gateway]
require_pairing = true
pairing_code_length = 8
pairing_timeout_minutes = 5

Pairing workflow:

1. Start gateway

   zeroclaw gateway
   

   Generates one-time pairing code: AB12-CD34

2. Client pairs

   curl -X POST http://localhost:3000/pair \
     -d '{"code": "AB12-CD34"}'
   

   Returns session token.

3. Use token

   curl http://localhost:3000/api/chat \
     -H "Authorization: Bearer <token>"
   

Channel Allowlists

Restrict who can interact with the agent:

# Telegram
[channels.telegram]
allowed_user_ids = [123456789, 987654321]

# Discord
[channels.discord]
allowed_user_ids = ["123456789012345678"]

# Email
[channels.email]
allowed_senders = ["[e-mail]", "@company.com"]

# Slack
[channels.slack]
allowed_users = ["U123ABC", "U456DEF"]

Authorization

Autonomy Levels

Control tool execution permissions:

Supervised (Recommended)

Requires human approval for all tool calls.

[agent]
autonomy_level = "supervised"

Use when:

• Running untrusted code
• High-risk operations
• Learning agent behavior

Semi-autonomous

Auto-approves safe tools, prompts for risky ones.

[agent]
autonomy_level = "semi-autonomous"

[security]
auto_approve_tools = ["file_read", "memory_recall"]
require_approval_tools = ["shell", "file_write"]

Autonomous

Full automation, no approval needed.

[agent]
autonomy_level = "autonomous"

Only use in sandboxed environments with strict security policies.

Tool Allowlists

Disable unused tools:

[security]
shell_enabled = true
file_write_enabled = true
browser_enabled = false  # Disable if not needed

Validation

Command Filtering

Block dangerous shell commands:

[security]
blocked_commands = [
    # Destructive operations
    "rm -rf /",
    "mkfs",
    "dd if=",
    "format",
    
    # System modification
    "chmod 777",
    "chown root",
    
    # Network attacks
    "nmap",
    "tcpdump",
    
    # Crypto mining
    "xmrig",
    "cgminer"
]

Path Validation

Enforce workspace boundaries:

[security]
workspace_path = "/var/zeroclaw/workspace"

# Block access to sensitive directories
blocked_paths = [
    "/etc",
    "/sys",
    "/proc",
    "~/.ssh",
    "~/.aws"
]

Network Restrictions

Limit outbound connections:

[security]
allowed_domains = [
    "*.github.com",
    "api.anthropic.com",
    "api.openai.com"
]

blocked_ips = [
    "127.0.0.0/8",      # Localhost
    "10.0.0.0/8",       # Private
    "172.16.0.0/12",    # Private
    "192.168.0.0/16"    # Private
]

Sandboxing

Landlock (Linux)

Filesystem sandboxing with Landlock LSM:

# Build with Landlock support
cargo build --features sandbox-landlock

[security.sandboxing]
landlock_enabled = true
allowed_read_paths = ["/usr", "/lib", "$WORKSPACE"]
allowed_write_paths = ["$WORKSPACE", "/tmp"]

Process Limits

Prevent resource exhaustion:

[runtime]
max_memory_mb = 512
max_cpu_percent = 80
max_processes = 10
max_file_descriptors = 1024

Timeout Enforcement

Limit execution time:

[tools]
shell_timeout_seconds = 60
browser_timeout_seconds = 30
file_operation_timeout_seconds = 10

Monitoring

Audit Logging

Enable comprehensive audit logs:

[security.audit]
enabled = true
log_tool_calls = true
log_security_events = true
log_path = "~/.zeroclaw/audit.log"

Audit log format:

{
  "timestamp": "2026-03-03T12:00:00Z",
  "event_type": "tool_call",
  "tool": "shell",
  "args": {"command": "ls -la"},
  "result": "success",
  "user": "telegram:123456789",
  "session_id": "abc123"
}

Anomaly Detection

Monitor for unusual behavior:

[security.anomaly_detection]
enabled = true
max_failed_commands_per_hour = 10
max_sensitive_file_access_per_hour = 5
alert_on_blocked_command = true

Rate Limiting

Prevent abuse:

[security]
max_actions_per_hour = 100
max_actions_per_day = 1000
rate_limit_per_minute = 20

Network Security

TLS/HTTPS

Always use TLS for public endpoints:

[gateway]
tls_enabled = true
tls_cert_path = "/etc/zeroclaw/cert.pem"
tls_key_path = "/etc/zeroclaw/key.pem"

Generate self-signed cert for testing:

openssl req -x509 -newkey rsa:4096 -nodes \
  -keyout key.pem -out cert.pem -days 365

Reverse Proxy

Use nginx or Caddy in front of gateway:

server {
    listen 443 ssl http2;
    server_name zeroclaw.example.com;
    
    ssl_certificate /etc/letsencrypt/live/zeroclaw.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/zeroclaw.example.com/privkey.pem;
    
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Firewall Rules

Restrict access to gateway:

# Allow only from specific IPs
sudo ufw allow from 203.0.113.0/24 to any port 3000

# Deny all other inbound
sudo ufw deny 3000

Secret Management

Environment Variables

Never hardcode secrets:

# ❌ DON'T: Store in config
[providers.anthropic]
api_key = "sk-ant-..."

# ✅ DO: Use environment variables
export ANTHROPIC_API_KEY="sk-ant-..."

Secret Rotation

Rotate API keys regularly:

1. Generate new key

   Create new key in provider dashboard

2. Update environment

   export ANTHROPIC_API_KEY="sk-ant-new-..."
   
3. Restart service

   zeroclaw service restart
   
4. Verify

   zeroclaw status
   
5. Revoke old key

   Delete old key from provider dashboard

Incident Response

When security incidents occur:

1. Isolate

   Stop the affected service:

   zeroclaw service stop
   
2. Investigate

   Review audit logs:

   cat ~/.zeroclaw/audit.log | grep "blocked\|failed"
   
3. Remediate

   • Revoke compromised credentials
   • Update security policies
   • Patch vulnerabilities
4. Restore

   Restart with updated configuration:

   zeroclaw doctor
   zeroclaw service start
   
5. Document

   Record incident in security log

Compliance

Data Retention

Configure retention policies:

[memory]
retention_days = 90
auto_delete_old_entries = true

[security.audit]
log_retention_days = 365

PII Handling

Redact sensitive information:

[security]
redact_pii = true
pii_patterns = [
    "\\b\\d{3}-\\d{2}-\\d{4}\\b",  # SSN
    "\\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}\\b"  # Email
]

Security Checklist

Before deploying to production:

• API keys in environment variables, not config files
• Gateway pairing enabled
• Channel allowlists configured
• Autonomy level set to supervised or semi-autonomous
• Dangerous commands blocked
• Workspace path restricted
• TLS/HTTPS enabled for public endpoints
• Rate limiting configured
• Audit logging enabled
• Resource limits set
• Firewall rules applied
• Regular backups configured
• Incident response plan documented

Related

• Security Concepts
• Running Agents
• Monitoring
• Configuration Reference