Security Configuration

​

Security Model

1. Deny-by-default: Unpaired devices are rejected
2. Device pairing: One-time codes with TTL
3. Workspace scoping: File access limited to workspace directory
4. Rate limiting: DoS prevention
5. Command authorization: Per-action access control

​

Basic Configuration

[security]
deny_by_default = true

​

deny_by_default Setting

[security]
deny_by_default = true   # Production mode (recommended)

[security]
deny_by_default = false  # Development mode (no pairing required)

​

Production Mode (deny_by_default = true)

• All devices must pair before executing commands
• Unpaired devices receive: Device 'xyz' not paired. Pair first.
• System actor (system) bypasses pairing for internal operations

​

Development Mode (deny_by_default = false)

• No pairing required (convenience for testing)
• All devices granted access (workspace-only still enforced)
• Use only in trusted environments

​

Pairing Configuration

[security]
deny_by_default = true
pairing_required = true    # Require pairing before access
workspace_only = true      # Restrict file access to workspace
persist_pairing = true     # Survive restarts
persist_path = "data/security.db"  # SQLite pairing database

​

Pairing Flow

1. Generate code: User runs pair command
   > pair
   Pairing code: A3F9K2
   Expires in 5 minutes.
   
2. Verify code: Device submits code via verify <code>
   > verify A3F9K2
   ✓ Device paired: cli-abc123
   
3. Device authorized: Device can now execute commands

​

Pairing Code Properties

• 6-character alphanumeric (e.g., A3F9K2)
• One-time use: Code invalidated after verification
• TTL: Expires after 5 minutes (configurable)
• Cryptographically random: No guessable patterns

​

Persistence Options

[security]
persist_pairing = true
persist_path = "data/security.db"

• Device ID
• Paired timestamp
• Label (optional)
• Last seen timestamp

[security]
persist_pairing = false

​

Workspace Scoping

[security]
workspace_only = true  # Recommended for edge devices

• Read/Write operations must be within workspace directory
• Attempting /etc/passwd access: Denied: path outside workspace
• Symlinks are resolved and validated

• File operations allowed system-wide (use with caution)
• Still subject to OS-level permissions

​

Workspace Path

cd /opt/oneclaw
./oneclaw-core  # Workspace = /opt/oneclaw

​

Rate Limiting

RateLimiter::new(max_per_minute)

• CLI channel: 60 requests/minute (1 per second)
• TCP channel: 300 requests/minute (5 per second)
• MQTT channel: 1000 requests/minute (16 per second)

​

How Rate Limiting Works

1. Each request increments counter
2. Counter resets every 60 seconds (sliding window)
3. Requests over limit are rejected: Rate limit exceeded

​

Command Authorization

​

Action Kinds

​

Authorization Flow

Action {
  actor: "cli-abc123",      // Device ID
  kind: ActionKind::Read,   // What they want
  resource: "sensors.db",   // What they want to access
}

1. Pairing check: Is device paired? (skip for PairDevice)
2. Action-specific check: Path validation, etc.
3. Return permit: { granted: true, reason: "..." }

​

Device Management

​

List Paired Devices

devices

Paired Devices:
  cli-abc123  (paired 2h ago)
  telegram-xyz (paired 1d ago)

​

Remove Device

unpair cli-a

✓ Removed device: cli-abc123

​

Prefix Matching

• unpair cli-a matches cli-abc123
• Ambiguous prefixes rejected: Ambiguous: 'cli' matches 2 devices

​

Example Configurations

​

Production Edge Device (Raspberry Pi)

[security]
deny_by_default = true         # Deny unpaired devices
pairing_required = true        # Require pairing
workspace_only = true          # Restrict to /opt/oneclaw
persist_pairing = true         # Survive restarts
persist_path = "data/security.db"  # SQLite persistence

​

Development / Testing

[security]
deny_by_default = false        # No pairing required
pairing_required = false       # Skip pairing
workspace_only = true          # Still restrict filesystem
persist_pairing = false        # In-memory only

​

High-Security Industrial IoT

[security]
deny_by_default = true         # Deny by default
pairing_required = true        # Require pairing
workspace_only = true          # Restrict to workspace
persist_pairing = true         # Persistent pairing
persist_path = "/var/lib/oneclaw/security.db"  # System-wide DB

​

Temporary Edge Device (No Persistence)

[security]
deny_by_default = true         # Deny unpaired devices
pairing_required = true        # Require pairing
workspace_only = true          # Restrict to workspace
persist_pairing = false        # In-memory only (lost on restart)

​

Security Best Practices

​

For Production Edge Devices

1. Always enable deny_by_default = true
2. Enable persist_pairing = true to avoid re-pairing after restarts
3. Use workspace_only = true to limit file access
4. Store persist_path on persistent storage (not tmpfs)
5. Pair devices on secure network (local access, not over internet)

​

For Development

1. Use deny_by_default = false for convenience
2. Keep workspace_only = true even in dev mode
3. Use persist_pairing = false to auto-reset between sessions

​

Device Pairing Security

1. Pairing codes expire after 5 minutes
2. One-time use: Cannot reuse verified codes
3. Generate on trusted interface (e.g., CLI, not MQTT)
4. Verify over secure channel (e.g., local console, not public chat)

​

API Key Security

Debug: api_key: "sk-a...xyz"  // Masked: first 4 + last 3 chars

• File permissions: chmod 600 config/default.toml
• Not committed to git: Add to .gitignore
• Use env vars for CI/CD: ANTHROPIC_API_KEY=...

​

Troubleshooting

​

”Device not paired”

pair              # Generate code
verify ABC123     # Device submits code

​

“Path outside workspace”

read /etc/passwd  # Denied: path outside workspace

read sensors.db   # OK: relative to workspace

​

Lost pairing after restart

[security]
persist_pairing = true
persist_path = "data/security.db"

​

Pairing code expired

pair  # New code with fresh 5-minute TTL

​

Security Threat Model

• Untrusted local networks (home WiFi, etc.)
• Accidental misconfiguration (wrong command target)
• Basic DoS attacks (rate limiting)

• Nation-state adversaries
• Physical access attacks (device compromise)
• Zero-day exploits in Rust/dependencies

• Network firewall (restrict ingress to trusted IPs)
• VPN/WireGuard for remote access
• TLS termination for TCP channels