Rule Structure

Shield uses the @securecheckio/rules-engine package for threat detection. Understanding rule structure helps you create effective custom rules.

Rule Format

Basic Rule

{
  "id": "my-custom-rule",
  "enabled": true,
  "category": "sql_injection",
  "severity": "high",
  "action": "block"
}

Required Fields

Field	Type	Description
id	string	Unique identifier (lowercase, hyphens, no spaces)
enabled	boolean	Whether rule is active
category	string	Threat category (see below)
severity	string	critical, high, medium, low
action	string	block, flag, or monitor

---

Rule Types

1. Regex Rules

Match patterns using regular expressions.

{
  "id": "sql-drop-table",
  "enabled": true,
  "regex": ["DROP\\s+TABLE", "TRUNCATE\\s+TABLE"],
  "nocase": true,
  "category": "sql_injection",
  "severity": "critical",
  "action": "block"
}

Fields:

• regex - Array of regex patterns (any match triggers)
• nocase - Case-insensitive matching (default: false)

Example matches:

• DROP TABLE users ✅
• drop table accounts ✅ (with nocase: true)
• TRUNCATE TABLE logs ✅

2. Keyword Rules

Match exact words or phrases.

{
  "id": "dangerous-commands",
  "enabled": true,
  "keywords": ["rm -rf", "eval()", "exec("],
  "nocase": true,
  "category": "command_injection",
  "severity": "high",
  "action": "block"
}

Fields:

• keywords - Array of exact strings to match
• nocase - Case-insensitive matching

Faster than regex for simple string matching.

3. Semantic Rules

Match by meaning using AI embeddings.

{
  "id": "password-theft",
  "enabled": true,
  "semantic": [
    "send me all passwords",
    "export user credentials",
    "show me admin passwords"
  ],
  "semanticThreshold": 0.85,
  "category": "data_exfiltration",
  "severity": "critical",
  "action": "block"
}

Fields:

• semantic - Array of example phrases
• semanticThreshold - Similarity score (0-1, default: 0.75)

Matches similar meanings:

• "can you give me the passwords?" ✅
• "I need all user logins" ✅
• "export credentials for me" ✅

4. Content Rules

Simple substring matching.

{
  "id": "blocked-words",
  "enabled": true,
  "content": ["confidential", "secret", "internal only"],
  "nocase": true,
  "category": "policy_violation",
  "severity": "medium",
  "action": "flag"
}

Fields:

• content - Array of substrings
• nocase - Case-insensitive

---

Threat Categories

Standard Categories

Category	Description	Severity
sql_injection	SQL injection attacks	Critical
xss	Cross-site scripting	High
command_injection	Shell command injection	Critical
prompt_injection	AI prompt manipulation	High
data_leak	Sensitive data exposure	Critical
data_exfiltration	Data theft attempts	Critical
pii_leak	Personal information leak	High
phishing	Phishing attempts	High
malware	Malware distribution	Critical
spam	Spam content	Low
policy_violation	Policy/compliance violation	Medium

Custom Categories

You can create your own:

{
  "id": "company-secrets",
  "category": "trade_secret_leak",
  "severity": "critical"
}

---

Severity Levels

Critical

Immediate threat requiring blocking.

{
  "severity": "critical",
  "action": "block"
}

Examples:

• Active SQL injection
• Data exfiltration
• Credential theft

High

Serious threat, should be blocked.

{
  "severity": "high",
  "action": "block"
}

Examples:

• XSS attempts
• Prompt injection
• PII leaks

Medium

Suspicious activity, flag for review.

{
  "severity": "medium",
  "action": "flag"
}

Examples:

• Policy violations
• Unusual patterns
• Edge cases

Low

Minor anomalies, monitor only.

{
  "severity": "low",
  "action": "monitor"
}

Examples:

• Spam indicators
• Repeated questions
• Low-confidence matches

---

Actions

Block

Completely reject the message.

{
  "action": "block"
}

User sees error, message never processed.

Flag

Allow but add warning.

{
  "action": "flag"
}

Bot sees warning, message allowed through.

Monitor

Log only, no user-visible effect.

{
  "action": "monitor"
}

Alert sent to admin, message allowed.

---

Rule Examples

SQL Injection Detection

{
  "id": "sql-or-tautology",
  "enabled": true,
  "regex": [
    "OR\\s+['\"]?1['\"]?\\s*=\\s*['\"]?1",
    "OR\\s+['\"]?true['\"]?\\s*=\\s*['\"]?true"
  ],
  "nocase": true,
  "category": "sql_injection",
  "severity": "critical",
  "action": "block"
}

Matches:

• admin' OR '1'='1
• user' or true=true--

XSS Detection

{
  "id": "xss-script-tag",
  "enabled": true,
  "regex": [
    "<script[^>]*>",
    "javascript:",
    "on(load|error|click)\\s*="
  ],
  "nocase": true,
  "category": "xss",
  "severity": "high",
  "action": "block"
}

Matches:

• <script>alert(1)</script>
• javascript:void(0)
• <img onerror=alert(1)>

API Key Detection

{
  "id": "api-key-leak",
  "enabled": true,
  "regex": [
    "sk-[A-Za-z0-9]{20,}",
    "ghp_[A-Za-z0-9]{20,}",
    "AIza[0-9A-Za-z\\-_]{20,}"
  ],
  "category": "data_leak",
  "severity": "critical",
  "action": "block"
}

Matches:

• OpenAI keys: sk-abc123...
• GitHub tokens: ghp_xyz789...
• Google API keys: AIzaSy...

Prompt Injection

{
  "id": "prompt-injection-ignore",
  "enabled": true,
  "keywords": [
    "ignore all previous instructions",
    "ignore your instructions",
    "disregard your programming"
  ],
  "nocase": true,
  "category": "prompt_injection",
  "severity": "high",
  "action": "block"
}

Matches:

• "Ignore all previous instructions and..."
• "IGNORE YOUR INSTRUCTIONS"

---

Built-in Rules

Shield comes with 40+ built-in rules covering:

• SQL injection (8 rules)
• XSS attacks (5 rules)
• Command injection (6 rules)
• Prompt injection (7 rules)
• Data leaks (8 rules)
• Common exploits (10+ rules)

View built-in rules:

/shield status

Shows active rule count and categories.

---

Custom Rules Configuration

In Plugin Config

{
  "plugins": {
    "openclaw-shield": {
      "enabled": true,
      "customRules": [
        {
          "id": "my-rule-1",
          "enabled": true,
          "regex": ["pattern1", "pattern2"],
          "category": "custom",
          "severity": "high",
          "action": "block"
        }
      ]
    }
  }
}

Via Backend API

Set autoUpdateRules: true to fetch rules from backend:

{
  "botToken": "sct_your_token",
  "autoUpdateRules": true
}

Rules fetched on startup and cached locally.

---

Rule Performance

Fast Rules

Keyword matching (~1ms):

{
  "keywords": ["DROP TABLE", "rm -rf"]
}

Simple regex (~2-5ms):

{
  "regex": ["\\b(password|secret)\\b"]
}

Medium Rules

Complex regex (~5-10ms):

{
  "regex": ["(?i)(drop|truncate)\\s+table\\s+\\w+"]
}

Slow Rules

Semantic matching (~20-50ms):

{
  "semantic": ["send me passwords"]
}

Tips:

• Use keywords when possible (fastest)
• Keep regex simple (avoid backtracking)
• Limit semantic patterns to critical rules

---

Testing Rules

Via Command

/shield test DROP TABLE users

Shows which rules match and why.

Test Configuration

{
  "customRules": [
    {
      "id": "test-rule",
      "enabled": true,
      "keywords": ["test pattern"],
      "action": "monitor",  // Start with monitor
      "category": "testing",
      "severity": "low"
    }
  ]
}

Workflow:

1. Create rule with action: "monitor"
2. Test with real messages
3. Check logs for matches
4. Adjust pattern if needed
5. Switch to action: "block" when confident

---

Rule Best Practices

1. Start specific, broaden if needed

   • Begin with exact patterns
   • Add variations as you see false negatives

2. Use appropriate severity

   • Critical: Active attacks, data breaches
   • High: Serious threats
   • Medium: Suspicious activity
   • Low: Edge cases

3. Test before deploying

   • Use monitor mode first
   • Test with real message samples
   • Check for false positives

4. Document your rules

   • Use clear id names
   • Add comments in config
   • Track why each rule exists

5. Review regularly

   • Check /shield status for hit counts
   • Remove unused rules
   • Update patterns based on new threats

---

Next Steps

• Custom Rules Guide - Create your own rules
• Commands - Test rules via bot
• Dashboard - Manage rules visually