guard-scanner 1.1.0 → 1.1.1

package/README.md

@@ -2,7 +2,8 @@
   <h1 align="center">🛡️ guard-scanner</h1>
   <p align="center">
     <strong>Static security scanner for AI agent skills</strong><br>
-    Detect prompt injection, credential theft, exfiltration, identity hijacking, and 17 more threat categories.
+    Detect prompt injection, credential theft, exfiltration, identity hijacking, and 17 more threat categories.<br>
+    <sub>Runtime Guard hook included — pending <a href="https://github.com/openclaw/openclaw/issues/18677">OpenClaw hook API adoption</a></sub>
   </p>
   <p align="center">
     <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
@@ -90,6 +91,8 @@ openclaw skill install guard-scanner
 guard-scanner ~/.openclaw/workspace/skills/ --self-exclude --verbose
 ```
 
+> **⚠️ Runtime Guard (handler.ts)** — The real-time `before_tool_call` hook requires OpenClaw's Hook API ([Issue #18677](https://github.com/openclaw/openclaw/issues/18677)). The hook is registered and runs on `agent:before_tool_call` events, but OpenClaw's `InternalHookEvent` does not yet expose a cancel/veto mechanism — so **detections are warned but not blocked**. The static scanner (`npx guard-scanner`) works fully and independently.
+
 ---
 
 ## Threat Categories
@@ -128,7 +131,7 @@ guard-scanner covers **20 threat categories** derived from three taxonomies:
 ### Terminal (Default)
 
 ```
-🛡️  guard-scanner v1.0.0
+🛡️  guard-scanner v1.1.0
 ══════════════════════════════════════════════════════
 📂 Scanning: ./skills/
 📦 Skills found: 22
@@ -391,7 +394,7 @@ guard-scanner/
 │   └── cli.js          # CLI entry point and argument parser
 ├── hooks/
 │   └── guard-scanner/
-│       └── handler.ts  # Runtime Guard — before_tool_call hook
+│       └── handler.ts  # Runtime Guard — before_tool_call hook (experimental, pending OpenClaw API)
 ├── test/
 │   ├── scanner.test.js # 55 tests across 13 sections
 │   └── fixtures/       # Malicious, clean, complex, config-changer samples
@@ -605,7 +608,7 @@ guard-scanner catches threats **before** installation. But what happens **after*
 | | guard-scanner (OSS) | GuavaSuite (Private) |
 |---|---|---|
 | Static scan | ✅ 20 categories | ✅ 20 categories |
-| Runtime blocking | — | ✅ Real-time `before_tool_call` guard |
+| Runtime blocking | ⚠️ Warn only (cancel API pending) | ✅ Real-time `before_tool_call` guard |
 | SOUL.md integrity | Pattern detection only | ✅ SHA-256 hash watchdog |
 | On-chain verification | — | ✅ SoulChain (Polygon) |
 | Identity recovery | — | ✅ Automatic rollback |

package/SKILL.md

@@ -29,7 +29,7 @@ metadata:
 # guard-scanner 🛡️
 
 Static + runtime security scanner for AI agent skills.
-**170+ threat patterns** across **17 categories** — zero dependencies.
+**186+ threat patterns** across **20 categories** — zero dependencies.
 
 ## When To Use This Skill
 
@@ -54,7 +54,9 @@ Scan a specific skill:
 node skills/guard-scanner/src/cli.js /path/to/new-skill/ --strict --verbose
 ```
 
-### 2. Runtime Guard (Real-time Protection)
+### 2. Runtime Guard (Real-time Protection) — ⚠️ Experimental
+
+> **Note:** Requires the OpenClaw Hook API ([Issue #18677](https://github.com/openclaw/openclaw/issues/18677)), which has not been officially adopted yet. The handler is included for early testing and will be updated once the API is finalized.
 
 Install the hook to block dangerous tool calls before execution:
 
@@ -83,11 +85,13 @@ openclaw hooks enable guard-scanner
 
 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 |
+| Mode | Intended Behavior | Current Status |
+|------|-------------------|----------------|
+| `monitor` | Log all, never block | ✅ Fully working |
+| `enforce` (default) | Block CRITICAL threats | ⚠️ Warn only (cancel API pending) |
+| `strict` | Block HIGH + CRITICAL | ⚠️ Warn only (cancel API pending) |
+
+> **Note:** OpenClaw's `InternalHookEvent` does not yet expose a `cancel`/`veto` mechanism. All detections are currently logged and warned via `event.messages`, but tool execution cannot be blocked. Blocking will be enabled when the cancel API is added.
 
 ## Threat Categories
 
@@ -110,6 +114,9 @@ Set in `openclaw.json` → `hooks.internal.entries.guard-scanner.mode`:
 | 15 | CVE Patterns | Known agent vulnerabilities |
 | 16 | MCP Security | Tool/schema poisoning, SSRF |
 | 17 | Identity Hijacking | SOUL.md/IDENTITY.md tampering |
+| 18 | Sandbox Validation | Dangerous binaries, broad file scope, sensitive env |
+| 19 | Code Complexity | Excessive file length, deep nesting, eval density |
+| 20 | Config Impact | openclaw.json writes, exec approval bypass |
 
 ## External Endpoints
 
@@ -140,7 +147,7 @@ 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
+- **Test suite**: 55 tests across 13 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

package/hooks/guard-scanner/handler.ts

@@ -1,26 +1,69 @@
-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+
- * 
+ * guard-scanner Runtime Guard — Hook Handler
+ *
+ * Intercepts agent tool calls and checks arguments against
+ * runtime threat intelligence patterns. Zero dependencies.
+ *
+ * Registered for event: agent:before_tool_call
+ *
+ * Current limitation:
+ *   The OpenClaw InternalHookEvent interface does not yet expose a
+ *   `cancel` / `veto` mechanism. This handler can WARN via
+ *   event.messages but cannot block tool execution.
+ *   When a cancel API is introduced, this handler will be updated
+ *   to actually block CRITICAL/HIGH threats.
+ *
+ * Modes (for future blocking behaviour):
+ *   monitor  — log only (current effective behaviour for all modes)
+ *   enforce  — will block CRITICAL when cancel API is available
+ *   strict   — will block HIGH+CRITICAL when cancel API is available
+ *
  * @author Guava 🍈 & Dee
- * @version 1.0.0
+ * @version 1.1.0
  * @license MIT
  */
 
+import { appendFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+// ── OpenClaw Hook Types (from openclaw/src/hooks/internal-hooks.ts) ──
+// Inline types to avoid broken relative-path imports.
+// These match the official InternalHookEvent / InternalHookHandler
+// from OpenClaw v2026.2.15.
+
+type InternalHookEventType = "command" | "session" | "agent" | "gateway";
+
+interface InternalHookEvent {
+    /** The type of event */
+    type: InternalHookEventType;
+    /** The specific action within the type (e.g., "before_tool_call") */
+    action: string;
+    /** The session key this event relates to */
+    sessionKey: string;
+    /** Additional context specific to the event */
+    context: Record<string, unknown>;
+    /** Timestamp when the event occurred */
+    timestamp: Date;
+    /** Messages to send back to the user (hooks can push to this array) */
+    messages: string[];
+}
+
+type InternalHookHandler = (event: InternalHookEvent) => Promise<void> | void;
+
+// Re-export as the public types for compatibility
+type HookHandler = InternalHookHandler;
+type HookEvent = InternalHookEvent;
+
 // ── Runtime threat patterns (12 checks) ──
-const RUNTIME_CHECKS = [
+interface RuntimeCheck {
+    id: string;
+    severity: "CRITICAL" | "HIGH" | "MEDIUM";
+    desc: string;
+    test: (s: string) => boolean;
+}
+
+const RUNTIME_CHECKS: RuntimeCheck[] = [
     {
         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)
@@ -78,11 +121,11 @@ const RUNTIME_CHECKS = [
 const AUDIT_DIR = join(homedir(), ".openclaw", "guard-scanner");
 const AUDIT_FILE = join(AUDIT_DIR, "audit.jsonl");
 
-function ensureAuditDir() {
+function ensureAuditDir(): void {
     try { mkdirSync(AUDIT_DIR, { recursive: true }); } catch { }
 }
 
-function logAudit(entry: Record<string, unknown>) {
+function logAudit(entry: Record<string, unknown>): void {
     ensureAuditDir();
     const line = JSON.stringify({ ...entry, ts: new Date().toISOString() }) + '\n';
     try { appendFileSync(AUDIT_FILE, line); } catch { }
@@ -90,16 +133,21 @@ function logAudit(entry: Record<string, unknown>) {
 
 // ── Main Handler ──
 const handler: HookHandler = async (event) => {
-    // Only handle before_tool_call
+    // Only handle agent:before_tool_call events
     if (event.type !== "agent" || event.action !== "before_tool_call") return;
 
-    const { toolName, toolArgs } = (event as any).context || {};
+    const { toolName, toolArgs } = event.context as {
+        toolName?: string;
+        toolArgs?: Record<string, unknown>;
+    };
     if (!toolName || !toolArgs) return;
 
-    // Get mode from config
-    const mode = (event as any).context?.cfg?.hooks?.internal?.entries?.['guard-scanner']?.mode || 'enforce';
+    // Get mode from context config (if available)
+    const cfg = event.context.cfg as Record<string, unknown> | undefined;
+    const hookEntries = (cfg as any)?.hooks?.internal?.entries?.['guard-scanner'] as Record<string, unknown> | undefined;
+    const mode = (hookEntries?.mode as string) || 'enforce';
 
-    // Only check dangerous tools
+    // Only check tools that can cause damage
     const dangerousTools = new Set(['exec', 'write', 'edit', 'browser', 'web_fetch', 'message']);
     if (!dangerousTools.has(toolName)) return;
 
@@ -113,35 +161,39 @@ const handler: HookHandler = async (event) => {
                 severity: check.severity,
                 desc: check.desc,
                 mode,
-                action: 'allowed' as string,
-                session: (event as any).sessionKey,
+                action: 'warned' as string,
+                session: event.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';
+            // NOTE: OpenClaw InternalHookEvent does not currently support
+            // a cancel/veto mechanism. When it does, uncomment the blocking
+            // logic below. For now, all detections are warnings only.
+            //
+            // 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;  // Not yet in the public API
+            //     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;  // Not yet in the public API
+            //     return;
+            // }
+
+            // Current behaviour: warn and log for all modes
             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}]`);
+            } else if (check.severity === 'HIGH') {
+                event.messages.push(`🛡️ guard-scanner NOTICE: ${check.desc} [${check.id}]`);
+                console.warn(`[guard-scanner] ℹ️ NOTICE: ${check.desc} [${check.id}]`);
             }
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "guard-scanner",
-    "version": "1.1.0",
+    "version": "1.1.1",
     "description": "Agent skill security scanner — detect prompt injection, malicious code, credential leaks, and 20 threat categories in AI agent skills",
     "main": "src/scanner.js",
     "bin": {