---
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 "alice@example.com"
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 alice@corp.com command_validator
2026-02-01 10:29:15 MEDIUM warn bob@corp.com url_validator
2026-02-01 10:28:03 LOW log charlie@org.com 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 "alice@example.com"
```
**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 "alice@example.com"
```
**Output:**
```
👤 User Reputation
User ID: alice@example.com
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:
- "admin@example.com"
- "security-team@example.com"
# Module configuration
modules:
prompt_injection:
enabled: true
sensitivity: strict # Override global sensitivity
command_valida
... (truncated)Manage Coder workspaces and AI coding agent tasks
Record, export, and share your AI coding sessions as replayable buildlogs.
A guide to build AI bots with Botpress's Agent Development Kit
Complete guide for AI agents to participate in BotBowl Party