openclaw-sec

---
name: openclaw-sec
description: AI Agent Security Suite - Real-time protection against prompt injection, command injection, SSRF, path traversal, secrets exposure, and content policy violations
version: 1.0.0
author: OpenClaw Security Team
metadata:
  category: security
  tags:
    - security
    - validation
    - ai-safety
    - prompt-injection
    - command-injection
    - ssrf
    - secrets-detection
  performance: 20-50ms validation time
  modules: 6 detection modules
---

# OpenClaw Security Suite

**Comprehensive AI Agent Protection** - Real-time security validation with 6 parallel detection modules, intelligent severity scoring, and automated action enforcement.

## Overview

OpenClaw Security Suite protects AI agent systems from security threats through:

- ✅ **6 Parallel Detection Modules** - Comprehensive threat coverage
- ⚡ **Sub-50ms Validation** - Real-time with async database writes
- 🎯 **Smart Severity Scoring** - Context-aware risk assessment
- 🔧 **Automated Actions** - Block, warn, or log based on severity
- 📊 **Analytics & Reputation** - Track patterns and user behavior
- 🪝 **Auto-Hooks** - Transparent protection via hooks

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    User Input / Tool Call                    │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
         ┌─────────────────────────────────┐
         │      Security Engine (Main)      │
         │    • Orchestrates all modules    │
         │    • Aggregates findings         │
         │    • Determines actions          │
         └────────────┬────────────────────┘
                      │
        ┌─────────────┴──────────────┐
        │   Parallel Detection (6)    │
        └─────────────┬───────────────┘
                      │
    ┌─────┬─────┬────┴────┬─────┬─────┐
    ▼     ▼     ▼         ▼     ▼     ▼
  Prompt Command URL    Path Secret Content
  Inject Inject  Valid  Valid Detect Scanner
    ↓     ↓      ↓      ↓     ↓      ↓
    └─────┴──────┴──────┴─────┴──────┘
                      │
                      ▼
         ┌────────────────────────┐
         │   Severity Scorer       │
         │ • Calculates risk level │
         │ • Weights by module     │
         └────────┬───────────────┘
                  │
                  ▼
         ┌────────────────────────┐
         │    Action Engine        │
         │ • Rate limiting         │
         │ • Reputation scoring    │
         │ • Action determination  │
         └────────┬───────────────┘
                  │
        ┌─────────┴─────────┐
        ▼                   ▼
   ┌─────────┐       ┌──────────────┐
   │ Return  │       │ Async Queue  │
   │ Result  │       │ • DB writes  │
   │ ~20-50ms│       │ • Logging    │
   └─────────┘       │ • Notify     │
                     └──────────────┘
```

## Commands

All commands are available via the `/openclaw-sec` skill or `openclaw-sec` CLI.

### Validation Commands

#### `/openclaw-sec validate-command <command>`

Validate a shell command for injection attempts.

```bash
openclaw-sec validate-command "ls -la"
openclaw-sec validate-command "rm -rf / && malicious"
```

**Options:**
- `-u, --user-id <id>` - User ID for tracking
- `-s, --session-id <id>` - Session ID for tracking

**Example Output:**
```
Validating command: rm -rf /

Severity: HIGH
Action: block
Findings: 2

Detections:
  1. command_injection - Dangerous command pattern detected
     Matched: rm -rf /

Recommendations:
  • Validate and sanitize any system commands
  • Use parameterized commands instead of string concatenation
```

---

#### `/openclaw-sec check-url <url>`

Validate a URL for SSRF and security issues.

```bash
openclaw-sec check-url "https://example.com"
openclaw-sec check-url "http://169.254.169.254/metadata"
openclaw-sec check-url "file:///etc/passwd"
```

**Options:**
- `-u, --user-id <id>` - User ID
- `-s, --session-id <id>` - Session ID

**Detects:**
- Internal/private IP addresses (RFC 1918, link-local)
- Cloud metadata endpoints (AWS, Azure, GCP)
- Localhost and loopback addresses
- File protocol URIs
- Credential exposure in URLs

---

#### `/openclaw-sec validate-path <path>`

Validate a file path for traversal attacks.

```bash
openclaw-sec validate-path "/tmp/safe-file.txt"
openclaw-sec validate-path "../../../etc/passwd"
openclaw-sec validate-path "/proc/self/environ"
```

**Options:**
- `-u, --user-id <id>` - User ID
- `-s, --session-id <id>` - Session ID

**Detects:**
- Directory traversal patterns (`../`, `..\\`)
- Absolute path to sensitive files (`/etc/passwd`, `/proc/*`)
- Null byte injection
- Unicode/encoding tricks
- Windows UNC paths

---

#### `/openclaw-sec scan-content <text|file>`

Scan content for secrets, obfuscation, and policy violations.

```bash
openclaw-sec scan-content "Normal text here"
openclaw-sec scan-content --file ./document.txt
openclaw-sec scan-content "API_KEY=sk-abc123def456"
```

**Options:**
- `-f, --file` - Treat argument as file path
- `-u, --user-id <id>` - User ID
- `-s, --session-id <id>` - Session ID

**Detects:**
- API keys and tokens (OpenAI, AWS, GitHub, etc.)
- Database credentials
- SSH private keys
- JWT tokens
- Base64/hex obfuscation
- Excessive special characters
- Policy violations

---

#### `/openclaw-sec check-all <text>`

Run comprehensive security scan with all modules.

```bash
openclaw-sec check-all "Your input text here"
```

**Options:**
- `-u, --user-id <id>` - User ID
- `-s, --session-id <id>` - Session ID

**Example Output:**
```
Running comprehensive security scan...
──────────────────────────────────────

📊 Scan Results
Severity: MEDIUM
Action: warn
Fingerprint: a1b2c3d4e5f6g7h8
Total Findings: 3

🔍 Detections by Module:

  prompt_injection (2 findings)
    1. instruction_override
       Severity: MEDIUM
       Description: Attempt to override system instructions

  url_validator (1 findings)
    1. ssrf_private_ip
       Severity: HIGH
       Description: Internal IP address detected
```

---

### Monitoring Commands

#### `/openclaw-sec events`

View recent security events.

```bash
openclaw-sec events
openclaw-sec events --limit 50
openclaw-sec events --user-id "[email protected]"
openclaw-sec events --severity HIGH
```

**Options:**
- `-l, --limit <number>` - Number of events (default: 20)
- `-u, --user-id <id>` - Filter by user
- `-s, --severity <level>` - Filter by severity

**Output:**
```
📋 Security Events

Timestamp            Severity   Action       User ID          Module
────────────────────────────────────────────────────────────────────
2026-02-01 10:30:22  HIGH       block        [email protected]   command_validator
2026-02-01 10:29:15  MEDIUM     warn         [email protected]     url_validator
2026-02-01 10:28:03  LOW        log          [email protected]  prompt_injection
```

---

#### `/openclaw-sec stats`

Show security statistics.

```bash
openclaw-sec stats
```

**Output:**
```
📊 Security Statistics

Database Tables:
  • security_events
  • rate_limits
  • user_reputation
  • attack_patterns
  • notifications_log
```

---

#### `/openclaw-sec analyze`

Analyze security patterns and trends.

```bash
openclaw-sec analyze
openclaw-sec analyze --user-id "[email protected]"
```

**Options:**
- `-u, --user-id <id>` - Analyze specific user

**Output:**
```
🔬 Security Analysis

User Reputation:
  Trust Score: 87.5
  Total Requests: 1,234
  Blocked Attempts: 5
  Allowlisted: No
  Blocklisted: No
```

---

#### `/openclaw-sec reputation <user-id>`

View user reputation and trust score.

```bash
openclaw-sec reputation "[email protected]"
```

**Output:**
```
👤 User Reputation

User ID: [email protected]
Trust Score: 92.3
Total Requests: 5,678
Blocked Attempts: 12
✓ Allowlisted
Last Violation: 2026-01-15 14:22:00
```

---

#### `/openclaw-sec watch`

Watch for security events in real-time (placeholder).

```bash
openclaw-sec watch
```

---

### Configuration Commands

#### `/openclaw-sec config`

Show current configuration.

```bash
openclaw-sec config
```

**Output:**
```
⚙️  Configuration

Config File: .openclaw-sec.yaml

Status: Enabled
Sensitivity: medium
Database: .openclaw-sec.db

Modules:
  ✓ prompt_injection
  ✓ command_validator
  ✓ url_validator
  ✓ path_validator
  ✓ secret_detector
  ✓ content_scanner

Actions:
  SAFE: allow
  LOW: log
  MEDIUM: warn
  HIGH: block
  CRITICAL: block_notify
```

---

#### `/openclaw-sec config-set <key> <value>`

Update configuration value (placeholder).

```bash
openclaw-sec config-set sensitivity strict
```

---

### Testing Commands

#### `/openclaw-sec test`

Test security configuration with predefined test cases.

```bash
openclaw-sec test
```

**Output:**
```
🧪 Testing Security Configuration

✓ PASS Safe input
  Expected: SAFE
  Got: SAFE
  Action: allow

✗ FAIL Command injection
  Expected: HIGH
  Got: MEDIUM
  Action: warn

📊 Test Results:
  Passed: 3
  Failed: 1
```

---

#### `/openclaw-sec report`

Generate security report (placeholder).

```bash
openclaw-sec report
openclaw-sec report --format json
openclaw-sec report --output report.txt
```

**Options:**
- `-f, --format <type>` - Report format (text, json)
- `-o, --output <file>` - Output file

---

### Database Commands

#### `/openclaw-sec db-vacuum`

Optimize database with VACUUM.

```bash
openclaw-sec db-vacuum
```

**Output:**
```
Optimizing database...
✓ Database optimized
```

---

## Configuration

Configuration file: `.openclaw-sec.yaml`

### Example Configuration

```yaml
openclaw_security:
  # Master enable/disable
  enabled: true

  # Global sensitivity level
  # Options: paranoid | strict | medium | permissive
  sensitivity: medium

  # Owner user IDs (bypass all checks)
  owner_ids:
    - "[email protected]"
    - "[email protected]"

  # Module configuration
  modules:
    prompt_injection:
      enabled: true
      sensitivity: strict  # Override global sensitivity

    command_valida

... (truncated)