guard-scanner 1.0.0

package/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: guard-scanner
+description: >
+  Security scanner for AI agent skills. Use BEFORE installing or running any new skill
+  from ClawHub or external sources. Detects prompt injection, credential theft,
+  exfiltration, identity hijacking, and 14 more threat categories.
+  Includes a Runtime Guard hook that blocks dangerous tool calls in real-time.
+homepage: https://github.com/koatora20/guard-scanner
+metadata:
+  clawdbot:
+    emoji: "🛡️"
+    category: security
+    requires:
+      bins:
+        - node
+      env: []
+    files: ["src/*", "hooks/*"]
+    primaryEnv: null
+    tags:
+      - security
+      - scanner
+      - threat-detection
+      - supply-chain
+      - prompt-injection
+      - sarif
+---
+
+# guard-scanner 🛡️
+
+Static + runtime security scanner for AI agent skills.
+**170+ threat patterns** across **17 categories** — zero dependencies.
+
+## When To Use This Skill
+
+- **Before installing a new skill** from ClawHub or any external source
+- **After updating skills** to check for newly introduced threats
+- **Periodically** to audit your installed skills
+- **In CI/CD** to gate skill deployments
+
+## Quick Start
+
+### 1. Static Scan (Immediate)
+
+Scan all installed skills:
+
+```bash
+node skills/guard-scanner/src/cli.js ~/.openclaw/workspace/skills/ --verbose --self-exclude
+```
+
+Scan a specific skill:
+
+```bash
+node skills/guard-scanner/src/cli.js /path/to/new-skill/ --strict --verbose
+```
+
+### 2. Runtime Guard (Real-time Protection)
+
+Install the hook to block dangerous tool calls before execution:
+
+```bash
+openclaw hooks install skills/guard-scanner/hooks/guard-scanner
+openclaw hooks enable guard-scanner
+```
+
+Restart the gateway, then verify:
+```bash
+openclaw hooks list   # Should show 🛡️ guard-scanner as ✓ ready
+```
+
+### 3. Full Setup (Recommended)
+
+```bash
+# Static scan first
+node skills/guard-scanner/src/cli.js ~/.openclaw/workspace/skills/ --verbose --self-exclude --html
+
+# Then enable runtime protection
+openclaw hooks install skills/guard-scanner/hooks/guard-scanner
+openclaw hooks enable guard-scanner
+```
+
+## Runtime Guard Modes
+
+Set in `openclaw.json` → `hooks.internal.entries.guard-scanner.mode`:
+
+| Mode | Behavior |
+|------|----------|
+| `monitor` | Log all, never block |
+| `enforce` (default) | Block CRITICAL threats |
+| `strict` | Block HIGH + CRITICAL |
+
+## Threat Categories
+
+| # | Category | What It Detects |
+|---|----------|----------------|
+| 1 | Prompt Injection | Hidden instructions, invisible Unicode, homoglyphs |
+| 2 | Malicious Code | eval(), child_process, reverse shells |
+| 3 | Suspicious Downloads | curl\|bash, executable downloads |
+| 4 | Credential Handling | .env reads, SSH key access |
+| 5 | Secret Detection | Hardcoded API keys and tokens |
+| 6 | Exfiltration | webhook.site, DNS tunneling |
+| 7 | Unverifiable Deps | Remote dynamic imports |
+| 8 | Financial Access | Crypto wallets, payment APIs |
+| 9 | Obfuscation | Base64→eval, String.fromCharCode |
+| 10 | Prerequisites Fraud | Fake download instructions |
+| 11 | Leaky Skills | Secret leaks through LLM context |
+| 12 | Memory Poisoning | Agent memory modification |
+| 13 | Prompt Worm | Self-replicating instructions |
+| 14 | Persistence | Cron jobs, startup execution |
+| 15 | CVE Patterns | Known agent vulnerabilities |
+| 16 | MCP Security | Tool/schema poisoning, SSRF |
+| 17 | Identity Hijacking | SOUL.md/IDENTITY.md tampering |
+
+## External Endpoints
+
+| URL | Data Sent | Purpose |
+|-----|-----------|---------|
+| *(none)* | *(none)* | guard-scanner makes **zero** network requests. All scanning is local. |
+
+## Security & Privacy
+
+- **No network access**: guard-scanner never connects to external servers
+- **Read-only scanning**: Only reads files, never modifies scanned directories
+- **No telemetry**: No usage data, analytics, or crash reports are collected
+- **Local reports only**: Output files (JSON/SARIF/HTML) are written to the scan directory
+- **No environment variable access**: Does not read or process any secrets or API keys
+- **Runtime Guard audit log**: Detections logged locally to `~/.openclaw/guard-scanner/audit.jsonl`
+
+## Model Invocation Note
+
+guard-scanner **does not invoke any LLM or AI model**. All detection is performed
+through static pattern matching, regex analysis, Shannon entropy calculation,
+and data flow analysis — entirely deterministic, no model calls.
+
+## Trust Statement
+
+guard-scanner was created by Guava 🍈 & Dee after experiencing a real 3-day
+identity hijack incident in February 2026. A malicious skill silently replaced
+an AI agent's SOUL.md personality file, and no existing tool could detect it.
+
+- **Open source**: Full source code available at https://github.com/koatora20/guard-scanner
+- **Zero dependencies**: Nothing to audit, no transitive risks
+- **Test suite**: 45 tests across 10 sections, 100% pass rate
+- **Taxonomy**: Based on Snyk ToxicSkills (Feb 2026), OWASP MCP Top 10, and original research
+- **Complementary to VirusTotal**: Detects prompt injection and LLM-specific attacks
+  that VirusTotal's signature-based scanning cannot catch
+
+## Output Formats
+
+```bash
+# Terminal (default)
+node src/cli.js ./skills/ --verbose
+
+# JSON report
+node src/cli.js ./skills/ --json
+
+# SARIF 2.1.0 (for CI/CD)
+node src/cli.js ./skills/ --sarif
+
+# HTML dashboard
+node src/cli.js ./skills/ --html
+```
+
+## License
+
+MIT — [LICENSE](LICENSE)

package/docs/THREAT_TAXONOMY.md

@@ -0,0 +1,273 @@
+# Threat Taxonomy
+
+Complete reference for guard-scanner's 17 threat categories.
+
+## Category Origins
+
+guard-scanner's threat taxonomy combines three sources:
+
+| Source | Categories | Description |
+|--------|-----------|-------------|
+| **Snyk ToxicSkills** (Feb 2026) | Cat 1–11 | Industry audit of 3,984 AI agent skills |
+| **Palo Alto Networks IBC** | Cat 12–13 | Indirect Bias Criteria for LLM agents |
+| **OWASP MCP Top 10** | Cat 14–16 | Model Context Protocol security risks |
+| **Original Research** | Cat 17 | Identity hijacking from real incident |
+
+---
+
+## Cat 1: Prompt Injection
+
+**Severity: CRITICAL**
+
+Hidden instructions embedded in skill documentation that override the agent's behavior.
+
+### Attack Vectors
+- **Invisible Unicode**: Zero-width spaces (U+200B), BiDi control characters (U+202A-202E), formatting characters
+- **Homoglyphs**: Cyrillic/Latin mixing (`а` vs `a`), Greek/Latin, Mathematical symbols (𝐀-𝟿)
+- **Role Override**: "Ignore all previous instructions", "You are now X"
+- **System Impersonation**: `[SYSTEM]`, `<system>`, `<<SYS>>` tags
+- **Tag Injection**: `<anthropic>`, `<system>`, `<tool_call>` in content
+
+### Detection IDs
+`PI_IGNORE`, `PI_ROLE`, `PI_SYSTEM`, `PI_ZWSP`, `PI_BIDI`, `PI_INVISIBLE`, `PI_HOMOGLYPH`, `PI_HOMOGLYPH_GREEK`, `PI_HOMOGLYPH_MATH`, `PI_TAG_INJECTION`, `PI_BASE64_MD`
+
+---
+
+## Cat 2: Malicious Code
+
+**Severity: CRITICAL**
+
+Direct code execution primitives that enable arbitrary command execution.
+
+### Attack Vectors
+- **Dynamic Evaluation**: `eval()`, `new Function()`, `vm.runInNewContext()`
+- **Process Execution**: `child_process.exec()`, `spawn()`, `execSync()`
+- **Shell Access**: `/bin/bash`, `cmd.exe`, `powershell.exe`
+- **Reverse Shells**: `nc -e`, `ncat`, `socat TCP`, `/dev/tcp`
+- **Raw Sockets**: `net.Socket().connect()`
+
+### Detection IDs
+`MAL_EVAL`, `MAL_FUNC_CTOR`, `MAL_CHILD`, `MAL_EXEC`, `MAL_SPAWN`, `MAL_SHELL`, `MAL_REVSHELL`, `MAL_SOCKET`
+
+---
+
+## Cat 3: Suspicious Downloads
+
+**Severity: CRITICAL**
+
+Downloading and executing external payloads.
+
+### Attack Vectors
+- **Pipe-to-Shell**: `curl ... | bash`, `wget ... | sh`
+- **Executable Downloads**: `.exe`, `.dmg`, `.pkg`, `.zip` downloads
+- **Password-Protected Archives**: Evasion technique to bypass AV
+- **Prerequisites Fraud**: "Before using this skill, download X"
+
+### Detection IDs
+`DL_CURL_BASH`, `DL_EXE`, `DL_GITHUB_RELEASE`, `DL_PASSWORD_ZIP`, `PREREQ_DOWNLOAD`, `PREREQ_PASTE`
+
+---
+
+## Cat 4: Credential Handling
+
+**Severity: HIGH**
+
+Accessing, reading, or exposing credentials.
+
+### Detection IDs
+`CRED_ENV_FILE`, `CRED_ENV_REF`, `CRED_SSH`, `CRED_WALLET`, `CRED_ECHO`, `CRED_SUDO`
+
+---
+
+## Cat 5: Secret Detection
+
+**Severity: CRITICAL**
+
+Hardcoded secrets and API keys in source code.
+
+### Detection Methods
+1. **Pattern Matching**: AWS keys (`AKIA...`), GitHub tokens (`ghp_`/`ghs_`), private keys
+2. **Shannon Entropy**: Strings with entropy > 3.5 and length ≥ 20 characters
+
+### Detection IDs
+`SECRET_HARDCODED_KEY`, `SECRET_AWS`, `SECRET_PRIVATE_KEY`, `SECRET_GITHUB_TOKEN`, `SECRET_ENTROPY`
+
+---
+
+## Cat 6: Exfiltration
+
+**Severity: CRITICAL**
+
+Sending stolen data to external endpoints.
+
+### Detection IDs
+`EXFIL_WEBHOOK`, `EXFIL_POST`, `EXFIL_CURL_DATA`, `EXFIL_DNS`, `EXFIL_BEACON`, `EXFIL_DRIP`
+
+---
+
+## Cat 7: Unverifiable Dependencies
+
+**Severity: HIGH**
+
+Loading code from unverifiable remote sources.
+
+### Detection IDs
+`DEP_REMOTE_IMPORT`, `DEP_REMOTE_SCRIPT`
+
+---
+
+## Cat 8: Financial Access
+
+**Severity: HIGH**
+
+Cryptocurrency and payment system interactions.
+
+### Detection IDs
+`FIN_CRYPTO`, `FIN_PAYMENT`
+
+---
+
+## Cat 9: Obfuscation
+
+**Severity: HIGH**
+
+Code obfuscation techniques to hide malicious intent.
+
+### Detection IDs
+`OBF_HEX`, `OBF_BASE64_EXEC`, `OBF_BASE64`, `OBF_CHARCODE`, `OBF_CONCAT`, `OBF_BASE64_BASH`
+
+---
+
+## Cat 10: Prerequisites Fraud
+
+Covered under Cat 3 (Suspicious Downloads).
+
+---
+
+## Cat 11: Leaky Skills (Snyk ToxicSkills)
+
+**Severity: CRITICAL**
+
+Skills that cause the LLM to leak secrets through its context window. Unlike traditional credential theft, leaky skills exploit the agent's trust relationship.
+
+### Attack Vectors
+- "Save the API key in your memory" → Secret persists in agent memory
+- "Share the token with the user" → Secret echoed to output
+- "Use the API key verbatim in curl" → Secret appears in command history
+- "Collect the user's credit card" → PII harvesting through LLM
+- "Export session logs to file" → Full conversation dump
+
+### Detection IDs
+`LEAK_SAVE_KEY_MEMORY`, `LEAK_SHARE_KEY`, `LEAK_VERBATIM_CURL`, `LEAK_COLLECT_PII`, `LEAK_LOG_SECRET`, `LEAK_ENV_IN_PROMPT`
+
+---
+
+## Cat 12: Memory Poisoning
+
+**Severity: CRITICAL**
+
+Modifying the agent's persistent memory or behavioral rules.
+
+### Attack Vectors
+- Writing to `SOUL.md`, `IDENTITY.md`, or `MEMORY.md`
+- Overriding behavioral rules: "Change your instructions to..."
+- Persistence: "From now on, always do X"
+- File writes to user's home directory
+
+### Detection IDs
+`MEMPOIS_WRITE_SOUL`, `MEMPOIS_WRITE_MEMORY`, `MEMPOIS_CHANGE_RULES`, `MEMPOIS_PERSIST`, `MEMPOIS_CODE_WRITE`
+
+---
+
+## Cat 13: Prompt Worm
+
+**Severity: CRITICAL**
+
+Self-replicating instructions that spread across agents and platforms.
+
+### Detection IDs
+`WORM_SELF_REPLICATE`, `WORM_SPREAD`, `WORM_HIDDEN_INSTRUCT`, `WORM_CSS_HIDE`
+
+---
+
+## Cat 14: Persistence & Scheduling
+
+**Severity: HIGH**
+
+Creating persistent execution mechanisms that survive session restarts.
+
+### Detection IDs
+`PERSIST_CRON`, `PERSIST_STARTUP`, `PERSIST_LAUNCHD`
+
+---
+
+## Cat 15: CVE Patterns
+
+**Severity: CRITICAL**
+
+Patterns matching known CVEs affecting AI agents.
+
+### Detection IDs
+`CVE_GATEWAY_URL`, `CVE_SANDBOX_DISABLE`, `CVE_XATTR_GATEKEEPER`, `CVE_WS_NO_ORIGIN`, `CVE_API_GUARDRAIL_OFF`
+
+---
+
+## Cat 16: MCP Security (OWASP MCP Top 10)
+
+**Severity: CRITICAL**
+
+Model Context Protocol specific attacks.
+
+### Attack Vectors
+- **Tool Poisoning** (MCP01): Hidden instructions in tool descriptions
+- **Schema Poisoning**: Malicious defaults in JSON schemas
+- **Token Theft** (MCP01): Secrets through tool parameters
+- **Shadow Server** (MCP09): Rogue MCP server registration
+- **Auth Bypass** (MCP07): Disabled authentication
+- **SSRF**: Cloud metadata endpoint access (169.254.169.254)
+
+### Detection IDs
+`MCP_TOOL_POISON`, `MCP_SCHEMA_POISON`, `MCP_TOKEN_LEAK`, `MCP_SHADOW_SERVER`, `MCP_NO_AUTH`, `MCP_SSRF_META`
+
+---
+
+## Cat 17: Identity Hijacking
+
+**Severity: CRITICAL**
+
+> **Original Research** — Developed from a real 3-day incident in February 2026.
+
+Tampering with an AI agent's identity/personality files (`SOUL.md`, `IDENTITY.md`).
+
+### Attack Vectors
+- **File Overwrite**: `cp`, `mv`, `scp`, `write` to identity files
+- **Shell Redirect**: `echo "evil" > SOUL.md`
+- **Stream Edit**: `sed -i` on identity files
+- **Programmatic Write**: Python `open('SOUL.md', 'w')`, Node.js `writeFileSync`
+- **Lock Bypass**: `chflags nouchg`, `attrib -R` to unlock immutability
+- **Persona Swap**: "Swap the soul file", "You are now EvilBot"
+- **Hook Injection**: Bootstrap hooks that swap files at startup
+- **Memory Wipe**: "Erase your memories", "Clear MEMORY.md"
+
+### Detection IDs
+`SOUL_OVERWRITE`, `SOUL_REDIRECT`, `SOUL_SED_MODIFY`, `SOUL_ECHO_WRITE`, `SOUL_PYTHON_WRITE`, `SOUL_FS_WRITE`, `SOUL_POWERSHELL_WRITE`, `SOUL_GIT_CHECKOUT`, `SOUL_CHFLAGS_UNLOCK`, `SOUL_ATTRIB_UNLOCK`, `SOUL_SWAP_PERSONA`, `SOUL_EVIL_FILE`, `SOUL_HOOK_SWAP`, `SOUL_NAME_OVERRIDE`, `SOUL_MEMORY_WIPE`
+
+> **Note**: Cat 17 detection patterns are open-source. The verification logic (hash comparison, on-chain validation) that confirms whether tampering actually occurred remains private.
+
+---
+
+## ZombieAgent Patterns
+
+Advanced exfiltration techniques that encode stolen data into URL patterns.
+
+### Detection IDs
+`ZOMBIE_STATIC_URL`, `ZOMBIE_CHAR_MAP`, `ZOMBIE_LOOP_FETCH`
+
+---
+
+## Safeguard Bypass (Reprompt)
+
+Techniques to circumvent safety guardrails.
+
+### Detection IDs
+`REPROMPT_URL_PI`, `REPROMPT_DOUBLE`, `REPROMPT_RETRY`, `BYPASS_REPHRASE`

package/hooks/guard-scanner/HOOK.md

@@ -0,0 +1,77 @@
+---
+name: guard-scanner
+description: "Runtime Guard — intercepts dangerous tool calls using threat intelligence patterns before execution"
+metadata: { "openclaw": { "emoji": "🛡️", "events": ["agent:before_tool_call"], "requires": { "bins": ["node"] } } }
+---
+
+# guard-scanner Runtime Guard — before_tool_call Hook
+
+Real-time security monitoring for OpenClaw agents. Intercepts dangerous
+tool calls before execution and checks against threat intelligence patterns.
+
+## Triggers
+
+| Event                      | Action | Purpose                                    |
+|----------------------------|--------|-------------------------------------------|
+| `agent:before_tool_call`   | scan   | Check tool args for malicious patterns    |
+
+## What It Does
+
+Scans every `exec`/`write`/`edit`/`browser`/`web_fetch`/`message` call against 12 runtime threat patterns:
+
+| ID | Severity | Description |
+|----|----------|-------------|
+| `RT_REVSHELL` | CRITICAL | Reverse shell via /dev/tcp, netcat, socat |
+| `RT_CRED_EXFIL` | CRITICAL | Credential exfiltration to webhook.site, requestbin, etc. |
+| `RT_GUARDRAIL_OFF` | CRITICAL | Guardrail disabling (exec.approvals=off) |
+| `RT_GATEKEEPER` | CRITICAL | macOS Gatekeeper bypass via xattr |
+| `RT_AMOS` | CRITICAL | ClawHavoc AMOS stealer indicators |
+| `RT_MAL_IP` | CRITICAL | Known malicious C2 IPs |
+| `RT_DNS_EXFIL` | HIGH | DNS-based data exfiltration |
+| `RT_B64_SHELL` | CRITICAL | Base64 decode piped to shell |
+| `RT_CURL_BASH` | CRITICAL | Download piped to shell execution |
+| `RT_SSH_READ` | HIGH | SSH private key access |
+| `RT_WALLET` | HIGH | Crypto wallet credential access |
+| `RT_CLOUD_META` | CRITICAL | Cloud metadata endpoint SSRF |
+
+## Modes
+
+| Mode | Behavior |
+|------|----------|
+| `monitor` | Log all detections, never block |
+| `enforce` (default) | Block CRITICAL, log rest |
+| `strict` | Block HIGH + CRITICAL, log MEDIUM+ |
+
+## Audit Log
+
+All detections logged to `~/.openclaw/guard-scanner/audit.jsonl`.
+
+Format: JSON lines with fields:
+```json
+{"tool":"exec","check":"RT_CURL_BASH","severity":"CRITICAL","desc":"Download piped to shell","mode":"enforce","action":"blocked","session":"...","ts":"2026-02-17T..."}
+```
+
+## Configuration
+
+Set mode in `openclaw.json`:
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "guard-scanner": {
+          "enabled": true,
+          "mode": "enforce"
+        }
+      }
+    }
+  }
+}
+```
+
+## Part of guard-scanner v1.0.0
+
+- **Static scanner**: `npx guard-scanner [dir]` — 17 threat categories, 170+ patterns
+- **Runtime Guard: This hook** — 12 real-time patterns, 3 modes
+- **Plugin API** — Custom detection rules
+- **CI/CD** — SARIF output for GitHub Code Scanning

package/hooks/guard-scanner/handler.ts

@@ -0,0 +1,150 @@
+import type { HookHandler } from "../../src/hooks/hooks.js";
+import { appendFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+/**
+ * guard-scanner Runtime Guard — before_tool_call Hook Handler
+ * 
+ * Intercepts tool executions in real-time and checks against
+ * threat intelligence patterns. Zero dependencies.
+ * 
+ * Modes:
+ *   monitor  — log only
+ *   enforce  — block CRITICAL (default)
+ *   strict   — block HIGH+CRITICAL, log MEDIUM+
+ * 
+ * @author Guava 🍈 & Dee
+ * @version 1.0.0
+ * @license MIT
+ */
+
+// ── Runtime threat patterns (12 checks) ──
+const RUNTIME_CHECKS = [
+    {
+        id: 'RT_REVSHELL', severity: 'CRITICAL', desc: 'Reverse shell attempt',
+        test: (s: string) => /\/dev\/tcp\/|nc\s+-e|ncat\s+-e|bash\s+-i\s+>&|socat\s+TCP/i.test(s)
+    },
+    {
+        id: 'RT_CRED_EXFIL', severity: 'CRITICAL', desc: 'Credential exfiltration to external',
+        test: (s: string) => {
+            return /(webhook\.site|requestbin\.com|hookbin\.com|pipedream\.net|ngrok\.io|socifiapp\.com)/i.test(s) &&
+                /(token|key|secret|password|credential|env)/i.test(s);
+        }
+    },
+    {
+        id: 'RT_GUARDRAIL_OFF', severity: 'CRITICAL', desc: 'Guardrail disabling attempt',
+        test: (s: string) => /exec\.approvals?\s*[:=]\s*['"]?(off|false)|tools\.exec\.host\s*[:=]\s*['"]?gateway/i.test(s)
+    },
+    {
+        id: 'RT_GATEKEEPER', severity: 'CRITICAL', desc: 'macOS Gatekeeper bypass (xattr)',
+        test: (s: string) => /xattr\s+-[crd]\s.*quarantine/i.test(s)
+    },
+    {
+        id: 'RT_AMOS', severity: 'CRITICAL', desc: 'ClawHavoc AMOS indicator',
+        test: (s: string) => /socifiapp|Atomic\s*Stealer|AMOS/i.test(s)
+    },
+    {
+        id: 'RT_MAL_IP', severity: 'CRITICAL', desc: 'Known malicious IP',
+        test: (s: string) => /91\.92\.242\.30/i.test(s)
+    },
+    {
+        id: 'RT_DNS_EXFIL', severity: 'HIGH', desc: 'DNS-based exfiltration',
+        test: (s: string) => /nslookup\s+.*\$|dig\s+.*\$.*@/i.test(s)
+    },
+    {
+        id: 'RT_B64_SHELL', severity: 'CRITICAL', desc: 'Base64 decode piped to shell',
+        test: (s: string) => /base64\s+(-[dD]|--decode)\s*\|\s*(sh|bash)/i.test(s)
+    },
+    {
+        id: 'RT_CURL_BASH', severity: 'CRITICAL', desc: 'Download piped to shell',
+        test: (s: string) => /(curl|wget)\s+[^\n]*\|\s*(sh|bash|zsh)/i.test(s)
+    },
+    {
+        id: 'RT_SSH_READ', severity: 'HIGH', desc: 'SSH private key access',
+        test: (s: string) => /\.ssh\/id_|\.ssh\/authorized_keys/i.test(s)
+    },
+    {
+        id: 'RT_WALLET', severity: 'HIGH', desc: 'Crypto wallet credential access',
+        test: (s: string) => /wallet.*(?:seed|mnemonic|private.*key)|seed.*phrase/i.test(s)
+    },
+    {
+        id: 'RT_CLOUD_META', severity: 'CRITICAL', desc: 'Cloud metadata endpoint access',
+        test: (s: string) => /169\.254\.169\.254|metadata\.google|metadata\.aws/i.test(s)
+    },
+];
+
+// ── Audit logging ──
+const AUDIT_DIR = join(homedir(), ".openclaw", "guard-scanner");
+const AUDIT_FILE = join(AUDIT_DIR, "audit.jsonl");
+
+function ensureAuditDir() {
+    try { mkdirSync(AUDIT_DIR, { recursive: true }); } catch { }
+}
+
+function logAudit(entry: Record<string, unknown>) {
+    ensureAuditDir();
+    const line = JSON.stringify({ ...entry, ts: new Date().toISOString() }) + '\n';
+    try { appendFileSync(AUDIT_FILE, line); } catch { }
+}
+
+// ── Main Handler ──
+const handler: HookHandler = async (event) => {
+    // Only handle before_tool_call
+    if (event.type !== "agent" || event.action !== "before_tool_call") return;
+
+    const { toolName, toolArgs } = (event as any).context || {};
+    if (!toolName || !toolArgs) return;
+
+    // Get mode from config
+    const mode = (event as any).context?.cfg?.hooks?.internal?.entries?.['guard-scanner']?.mode || 'enforce';
+
+    // Only check dangerous tools
+    const dangerousTools = new Set(['exec', 'write', 'edit', 'browser', 'web_fetch', 'message']);
+    if (!dangerousTools.has(toolName)) return;
+
+    const serialized = JSON.stringify(toolArgs);
+
+    for (const check of RUNTIME_CHECKS) {
+        if (check.test(serialized)) {
+            const entry = {
+                tool: toolName,
+                check: check.id,
+                severity: check.severity,
+                desc: check.desc,
+                mode,
+                action: 'allowed' as string,
+                session: (event as any).sessionKey,
+            };
+
+            if (mode === 'strict' && (check.severity === 'CRITICAL' || check.severity === 'HIGH')) {
+                entry.action = 'blocked';
+                logAudit(entry);
+                event.messages.push(`🛡️ guard-scanner BLOCKED: ${check.desc} [${check.id}]`);
+                event.cancel = true;
+                console.warn(`[guard-scanner] 🚨 BLOCKED: ${check.desc} [${check.id}]`);
+                return;
+            }
+
+            if (mode === 'enforce' && check.severity === 'CRITICAL') {
+                entry.action = 'blocked';
+                logAudit(entry);
+                event.messages.push(`🛡️ guard-scanner BLOCKED: ${check.desc} [${check.id}]`);
+                event.cancel = true;
+                console.warn(`[guard-scanner] 🚨 BLOCKED: ${check.desc} [${check.id}]`);
+                return;
+            }
+
+            // Monitor mode or non-critical: log only
+            entry.action = 'logged';
+            logAudit(entry);
+
+            if (check.severity === 'CRITICAL') {
+                event.messages.push(`🛡️ guard-scanner WARNING: ${check.desc} [${check.id}]`);
+                console.warn(`[guard-scanner] ⚠️ WARNING: ${check.desc} [${check.id}]`);
+            }
+        }
+    }
+};
+
+export default handler;