@guava-parity/guard-scanner 13.0.0 → 16.0.0

package/hooks/context.ts

@@ -0,0 +1,306 @@
+// @ts-nocheck
+/**
+ * guard-scanner Context Engine Hooks — OpenClaw Lifecycle Integration
+ *
+ * 3 lifecycle hooks for the Guard Scanner plugin:
+ *   1. bootstrap — Initialize guard state, inject status summary
+ *   2. afterTurn — Clear temporal context, flush audit log
+ *   3. prepareSubagentSpawn — Guard-scan subagent payloads
+ *
+ * Design:
+ *   - Duck-typed interfaces (no OpenClaw dependency)
+ *   - Pure regex pattern matching for Moltbook/A2A detection (no external process)
+ *   - Context-Crush 185KB hard limit on all injections
+ *   - All hooks are non-blocking on failure (agent must never stall)
+ *
+ * @author Guava 🍈 & Dee
+ * @version 15.0.0
+ * @license MIT
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// ── Constants ──
+
+const CONTEXT_CRUSH_LIMIT = 189440; // 185KB
+const BOOTSTRAP_CONTEXT_LIMIT = 2048; // 2KB max for bootstrap injection
+const AUDIT_DIR = join(homedir(), ".openclaw", "guard-scanner");
+const AUDIT_FILE = join(AUDIT_DIR, "audit.jsonl");
+
+// ── Types (duck-typed — from OpenClaw src/plugins/types.ts) ──
+
+/**
+ * @typedef {Object} HookContext
+ * @property {Record<string, unknown>} [config]
+ * @property {string} [workspaceDir]
+ * @property {string} [agentId]
+ * @property {string} [sessionKey]
+ */
+
+/**
+ * @typedef {Object} BootstrapEvent
+ * @property {string} [workspace]
+ * @property {string} [sessionId]
+ */
+
+/**
+ * @typedef {Object} BootstrapResult
+ * @property {string} [systemPromptSuffix]
+ * @property {string} [extraContext]
+ */
+
+/**
+ * @typedef {Object} AfterTurnEvent
+ * @property {number} [turnNumber]
+ * @property {number} [messageCount]
+ */
+
+/**
+ * @typedef {Object} SubagentSpawnEvent
+ * @property {string} [subagentId]
+ * @property {string} [task]
+ * @property {string[]} [tools]
+ * @property {Record<string, unknown>} [params]
+ */
+
+/**
+ * @typedef {Object} SubagentSpawnResult
+ * @property {boolean} [block]
+ * @property {string} [blockReason]
+ * @property {Record<string, unknown>} [params]
+ */
+
+// ── Internal: Audit logging ──
+
+function ensureAuditDir() {
+    try {
+        mkdirSync(AUDIT_DIR, { recursive: true });
+    } catch {
+        /* ignore — non-critical */
+    }
+}
+
+function logAudit(entry) {
+    ensureAuditDir();
+    try {
+        const line = JSON.stringify({ ...entry, ts: new Date().toISOString() }) + "\n";
+        appendFileSync(AUDIT_FILE, line);
+    } catch {
+        /* ignore — audit failure must never block agent */
+    }
+}
+
+// ── Internal: Config resolution ──
+
+function resolveMode(ctx) {
+    const mode = ctx?.config?.mode;
+    if (mode === "monitor" || mode === "enforce" || mode === "strict") return mode;
+    return "enforce";
+}
+
+function shouldBlock(mode, severity) {
+    if (!severity || mode === "monitor") return false;
+    if (mode === "strict") return severity === "CRITICAL" || severity === "HIGH";
+    return severity === "CRITICAL";
+}
+
+
+// ── Runtime threat patterns (subset for subagent validation) ──
+
+const SUBAGENT_CHECKS = [
+    {
+        id: "SA_PROMPT_INJECT", severity: "CRITICAL",
+        desc: "Prompt injection in subagent task",
+        test: (s) => /(ignore\s+(previous|all|above)\s+(instructions|rules)|you\s+are\s+now\s+[a-z]+|system\s*:\s*override)/i.test(s),
+    },
+    {
+        id: "SA_CRED_EXFIL", severity: "CRITICAL",
+        desc: "Credential exfiltration in subagent payload",
+        test: (s) =>
+            /(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: "SA_TRUST_BYPASS", severity: "CRITICAL",
+        desc: "A2A trust bypass — partnership exploitation to override safety",
+        test: (s) =>
+            /(as\s+your\s+(partner|equal)|trust\s+means|between\s+us|don'?t\s+tell\s+(the\s+)?human)/i.test(s) &&
+            /(ignore|bypass|skip|override|disable)\s+(guard|safety|rule|check)/i.test(s),
+    },
+    {
+        id: "SA_REVSHELL", severity: "CRITICAL",
+        desc: "Reverse shell in subagent parameters",
+        test: (s) => /\/dev\/tcp\/|nc\s+-e|ncat\s+-e|bash\s+-i\s+>&|socat\s+TCP/i.test(s),
+    },
+    {
+        id: "SA_CURL_BASH", severity: "CRITICAL",
+        desc: "Download piped to shell in subagent",
+        test: (s) => /(curl|wget)\s+[^\n]*\|\s*(sh|bash|zsh)/i.test(s),
+    },
+    {
+        id: "SA_SSH_READ", severity: "HIGH",
+        desc: "SSH key access in subagent",
+        test: (s) => /\.ssh\/id_|\.ssh\/authorized_keys/i.test(s),
+    },
+    {
+        id: "SA_SOUL_TAMPER", severity: "CRITICAL",
+        desc: "SOUL.md modification in subagent",
+        test: (s) => /SOUL\.md/i.test(s) && /(write|edit|replace|rm|delete|>)/i.test(s),
+    },
+    {
+        id: "SA_MOLTBOOK", severity: "CRITICAL",
+        desc: "Moltbook/AMOS indicator in subagent",
+        test: (s) => /socifiapp|Atomic\s*Stealer|AMOS/i.test(s),
+    },
+    {
+        id: "SA_CLOUD_META", severity: "CRITICAL",
+        desc: "Cloud metadata access in subagent",
+        test: (s) => /169\.254\.169\.254|metadata\.google|metadata\.aws/i.test(s),
+    },
+];
+
+// ── Exported Hooks ──
+
+/**
+ * HOOK: bootstrap (priority: 10)
+ *
+ * Initialize guard-scanner context engine state on agent boot.
+ * Injects a compact status summary into systemPromptSuffix.
+ * Hard-capped at 2KB to prevent context bloat.
+ *
+ * @param {BootstrapEvent} event
+ * @param {HookContext} ctx
+ * @returns {Promise<BootstrapResult | undefined>}
+ */
+export async function bootstrap(event, ctx) {
+    try {
+        const mode = resolveMode(ctx);
+        const patternCount = SUBAGENT_CHECKS.length;
+
+        const status = [
+            `🛡️ guard-scanner v15.0.0 active (mode: ${mode})`,
+            `Patterns: ${patternCount} subagent + 22 runtime checks`,
+            `Context-Crush limit: ${Math.round(CONTEXT_CRUSH_LIMIT / 1024)}KB`,
+            `Audit: ${AUDIT_FILE}`,
+        ].join(" | ");
+
+        // Hard cap at 2KB
+        const clipped = status.length > BOOTSTRAP_CONTEXT_LIMIT
+            ? status.slice(0, BOOTSTRAP_CONTEXT_LIMIT - 3) + "..."
+            : status;
+
+        logAudit({
+            hook: "bootstrap",
+            mode,
+            sessionId: event?.sessionId ?? "unknown",
+            status: "initialized",
+        });
+
+        return {
+            systemPromptSuffix: clipped,
+        };
+    } catch {
+        // Bootstrap failure must never block agent startup
+        return undefined;
+    }
+}
+
+/**
+ * HOOK: afterTurn (priority: 100)
+ *
+ * Post-turn cleanup:
+ *   - Flush accumulated audit entries
+ *   - Clear any temporal guard state
+ *   - Log turn completion for forensics
+ *
+ * Fire-and-forget — never blocks, never throws.
+ *
+ * @param {AfterTurnEvent} event
+ * @param {HookContext} ctx
+ * @returns {Promise<void>}
+ */
+export async function afterTurn(event, ctx) {
+    try {
+        logAudit({
+            hook: "afterTurn",
+            turnNumber: event?.turnNumber ?? 0,
+            messageCount: event?.messageCount ?? 0,
+            agent: ctx?.agentId ?? "unknown",
+            session: ctx?.sessionKey ?? "unknown",
+            status: "turn_complete",
+        });
+    } catch {
+        // afterTurn failure must never affect agent
+    }
+}
+
+/**
+ * HOOK: prepareSubagentSpawn (priority: 100)
+ *
+ * Critical security gate before subagent creation.
+ * Validates the entire spawn payload against:
+ *   1. Context-Crush limit (185KB)
+ *   2. 9 subagent-specific threat patterns (Moltbook, A2A hijack, etc.)
+ *
+ * Returns { block: true, blockReason } on threat detection.
+ *
+ * @param {SubagentSpawnEvent} event
+ * @param {HookContext} ctx
+ * @returns {Promise<SubagentSpawnResult | undefined>}
+ */
+export async function prepareSubagentSpawn(event, ctx) {
+    try {
+        const mode = resolveMode(ctx);
+        const serialized = JSON.stringify(event ?? {});
+
+        // ── Context-Crush Check ──
+        const payloadBytes = Buffer.byteLength(serialized, "utf8");
+        if (payloadBytes > CONTEXT_CRUSH_LIMIT) {
+            const reason = `🛡️ guard-scanner: Context-Crush — subagent payload ${payloadBytes} bytes exceeds ${Math.round(CONTEXT_CRUSH_LIMIT / 1024)}KB limit`;
+            logAudit({
+                hook: "prepareSubagentSpawn",
+                check: "CONTEXT_CRUSH",
+                severity: "CRITICAL",
+                subagentId: event?.subagentId ?? "unknown",
+                payloadBytes,
+                action: "blocked",
+            });
+            return { block: true, blockReason: reason };
+        }
+
+        // ── Subagent Threat Pattern Scan ──
+        for (const check of SUBAGENT_CHECKS) {
+            if (!check.test(serialized)) continue;
+
+            const auditEntry = {
+                hook: "prepareSubagentSpawn",
+                check: check.id,
+                severity: check.severity,
+                desc: check.desc,
+                subagentId: event?.subagentId ?? "unknown",
+                mode,
+                action: "warned",
+            };
+
+            if (shouldBlock(mode, check.severity)) {
+                auditEntry.action = "blocked";
+                logAudit(auditEntry);
+                return {
+                    block: true,
+                    blockReason: `🛡️ guard-scanner: ${check.desc} [${check.id}] in subagent ${event?.subagentId ?? "unknown"}`,
+                };
+            }
+
+            // Below threshold — warn only
+            logAudit(auditEntry);
+        }
+
+        // Clean payload — allow spawn
+        return undefined;
+    } catch {
+        // Guard failure must never block subagent spawn
+        return undefined;
+    }
+}

package/hooks/guard-scanner/plugin.ts

@@ -62,7 +62,7 @@ type PluginAPI = {
 interface RuntimeCheck {
     id: string;
     severity: "CRITICAL" | "HIGH" | "MEDIUM";
-    layer: 1 | 2 | 3;
+    layer: 1 | 2 | 3 | 4 | 5;
     desc: string;
     test: (s: string) => boolean;
 }
@@ -267,6 +267,29 @@ export default function (api: PluginAPI) {
         if (!DANGEROUS_TOOLS.has(toolName)) return;
 
         const serialized = JSON.stringify(params);
+        
+        // --- v15.0.0 Sanctuary Enforcer: Context-Crush Limit ---
+        // 185KB = 185 * 1024 bytes = 189440 bytes
+        const MAX_PAYLOAD_SIZE = 189440;
+        if (Buffer.byteLength(serialized, 'utf8') > MAX_PAYLOAD_SIZE) {
+            const auditEntry = {
+                tool: toolName,
+                check: "CONTEXT_CRUSH_LIMIT",
+                severity: "CRITICAL",
+                desc: "Context-Crush: Payload exceeds 185KB Sanctuary limit",
+                mode,
+                action: "blocked",
+                session: ctx.sessionKey || "unknown",
+                agent: ctx.agentId || "unknown",
+            };
+            logAudit(auditEntry);
+            api.logger.error(`🛡️ BLOCKED ${toolName}: Context-Crush payload size exceeded (${Buffer.byteLength(serialized, 'utf8')} bytes)`);
+            return {
+                block: true,
+                blockReason: "🛡️ guard-scanner v15: Payload exceeds 185KB Context-Crush limit.",
+            };
+        }
+        // --------------------------------------------------------
 
         for (const check of RUNTIME_CHECKS) {
             if (!check.test(serialized)) continue;

package/openclaw-plugin.mts

@@ -0,0 +1,107 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import * as runtimeGuard from "./src/index.js";
+
+const runtimeGuardApi = runtimeGuard as {
+    scanToolCall: (
+        toolName: string,
+        params: Record<string, unknown>,
+        options?: {
+            mode?: "monitor" | "enforce" | "strict";
+            auditLog?: boolean;
+            sessionKey?: string;
+            sessionId?: string;
+            runId?: string;
+            toolCallId?: string;
+            agentId?: string;
+            policy?: {
+                id?: string;
+                allowed_tools?: string[];
+                blocked_tools?: string[];
+                max_network_scope?: "none" | "internal-only" | "external-ok";
+                secret_bearing_context?: boolean;
+                memory_write_permission?: boolean;
+            };
+        },
+    ) => {
+        blocked: boolean;
+        blockReason: string | null;
+    };
+};
+
+type GuardMode = "monitor" | "enforce" | "strict";
+type PluginHookBeforeToolCallEvent = {
+    toolName: string;
+    params: Record<string, unknown>;
+    runId?: string;
+    toolCallId?: string;
+};
+type PluginHookToolContext = {
+    agentId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+    runId?: string;
+    toolName: string;
+    toolCallId?: string;
+    policy?: {
+        id?: string;
+        allowed_tools?: string[];
+        blocked_tools?: string[];
+        max_network_scope?: "none" | "internal-only" | "external-ok";
+        secret_bearing_context?: boolean;
+        memory_write_permission?: boolean;
+    };
+};
+
+function resolveMode(pluginConfig?: Record<string, unknown>): GuardMode | undefined {
+    const mode = pluginConfig?.mode;
+    if (mode === "monitor" || mode === "enforce" || mode === "strict") {
+        return mode;
+    }
+    return undefined;
+}
+
+function resolveAuditLog(pluginConfig?: Record<string, unknown>): boolean {
+    return pluginConfig?.auditLog !== false;
+}
+
+function beforeToolCall(
+    event: PluginHookBeforeToolCallEvent,
+    ctx: PluginHookToolContext,
+    api: OpenClawPluginApi,
+) {
+    const result = runtimeGuardApi.scanToolCall(event.toolName, event.params, {
+        mode: resolveMode(api.pluginConfig),
+        auditLog: resolveAuditLog(api.pluginConfig),
+        sessionKey: ctx.sessionKey,
+        sessionId: ctx.sessionId,
+        runId: ctx.runId ?? event.runId,
+        toolCallId: ctx.toolCallId ?? event.toolCallId,
+        agentId: ctx.agentId,
+        policy: ctx.policy,
+    });
+
+    if (!result.blocked) return;
+    return {
+        block: true,
+        blockReason: result.blockReason ?? "guard-scanner blocked the tool call.",
+    };
+}
+
+const plugin = {
+    id: "guard-scanner",
+    name: "guard-scanner",
+    version: "15.0.0",
+    description: "Runtime guard for OpenClaw before_tool_call hook execution.",
+    register(api: OpenClawPluginApi) {
+        api.on(
+            "before_tool_call",
+            (event: PluginHookBeforeToolCallEvent, ctx: PluginHookToolContext) => beforeToolCall(event, ctx, api),
+            { priority: 90 },
+        );
+        api.logger.info(
+            "guard-scanner registered OpenClaw before_tool_call hook (stable: v2026.3.12, regression lane: v2026.3.8).",
+        );
+    },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -1,55 +1,32 @@
 {
-    "name": "guard-scanner",
-    "version": "5.0.5",
-    "displayName": "🛡️ Guard Scanner — Runtime Security for AI Agents",
-    "description": "147 static patterns (23 categories) + 26 runtime checks (5 layers). 0.016ms/scan, zero dependencies, SARIF output.",
-    "author": "Guava & Dee",
-    "license": "MIT",
-    "homepage": "https://github.com/koatora20/guard-scanner",
-    "repository": "https://github.com/koatora20/guard-scanner",
-    "keywords": [
-        "security",
-        "runtime-guard",
-        "threat-detection",
-        "before-tool-call"
-    ],
-    "hooks": {
-        "before_tool_call": {
-            "handler": "./hooks/guard-scanner/plugin.ts",
-            "description": "Scans tool call arguments against 26 runtime threat patterns (5 layers) and blocks dangerous operations",
-            "priority": 100
-        }
+  "id": "guard-scanner",
+  "name": "guard-scanner",
+  "description": "Runtime guard plugin for OpenClaw before_tool_call enforcement with capability-scoped policy rationale.",
+  "version": "16.0.0",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "mode": {
+        "type": "string",
+        "enum": [
+          "monitor",
+          "enforce",
+          "strict"
+        ],
+        "default": "enforce",
+        "description": "monitor: log only | enforce: block CRITICAL | strict: block HIGH+CRITICAL"
+      },
+      "auditLog": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable audit logging to ~/.openclaw/guard-scanner/audit.jsonl"
+      },
+      "customRules": {
+        "type": "string",
+        "description": "Path to custom rules JSON file (optional)"
+      }
     },
-    "configSchema": {
-        "type": "object",
-        "properties": {
-            "mode": {
-                "type": "string",
-                "enum": [
-                    "monitor",
-                    "enforce",
-                    "strict"
-                ],
-                "default": "enforce",
-                "description": "monitor: log only | enforce: block CRITICAL | strict: block HIGH+CRITICAL"
-            },
-            "auditLog": {
-                "type": "boolean",
-                "default": true,
-                "description": "Enable audit logging to ~/.openclaw/guard-scanner/audit.jsonl"
-            },
-            "customRules": {
-                "type": "string",
-                "description": "Path to custom rules JSON file (optional)"
-            }
-        },
-        "required": [],
-        "additionalProperties": false
-    },
-    "capabilities": {
-        "cli": true,
-        "runtimeGuard": true,
-        "sarif": true,
-        "cicd": true
-    }
-}
+    "required": [],
+    "additionalProperties": false
+  }
+}

package/package.json

@@ -1,24 +1,72 @@
 {
   "name": "@guava-parity/guard-scanner",
-  "version": "13.0.0",
+  "version": "16.0.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "description": "Agent Skill Security Scanner - 2026 Moltbook Payload Immune System",
-  "openclaw.extensions": "./openclaw.plugin.json",
-  "openclaw.hooks": {
-    "guard-scanner": "./hooks/guard-scanner"
+  "description": "Agent Skill Security Scanner - ASI Sanctuary Enforcer (v16)",
+  "openclaw": {
+    "extensions": [
+      "./dist/openclaw-plugin.mjs"
+    ]
   },
-  "main": "src/scanner.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    },
+    "./plugin": {
+      "types": "./dist/openclaw-plugin.d.mts",
+      "import": "./dist/openclaw-plugin.mjs",
+      "require": "./dist/openclaw-plugin.cjs",
+      "default": "./dist/openclaw-plugin.mjs"
+    },
+    "./mcp": {
+      "types": "./dist/mcp-server.d.ts",
+      "import": "./dist/mcp-server.mjs",
+      "require": "./dist/mcp-server.cjs",
+      "default": "./dist/mcp-server.mjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "./dist/cli.cjs",
+    "./dist/openclaw-plugin.mjs",
+    "./dist/openclaw-plugin.cjs"
+  ],
   "bin": {
-    "guard-scanner": "src/cli.js"
+    "guard-scanner": "dist/cli.cjs"
   },
   "scripts": {
-    "scan": "node src/cli.js",
-    "test": "node scripts/test-quality-gate.js && node --test test/*.test.js",
-    "test:core": "node --test test/scanner.test.js test/patterns.test.js",
-    "test:quality": "node scripts/test-quality-gate.js"
+    "build": "tsup --config tsup.config.ts",
+    "build:plugin": "npm run build",
+    "benchmark": "tsx scripts/benchmark.ts --write-ledgers",
+    "check:upstream": "tsx scripts/check-openclaw-upstream.ts",
+    "check:tarball": "tsx scripts/validate-tarball.ts",
+    "scan": "tsx src/cli.ts",
+    "lint": "tsx scripts/lint.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "release:gate": "npm run build && npm run benchmark && tsx scripts/generate-capabilities.ts && tsx scripts/release-gate.ts && tsx scripts/validate-tarball.ts",
+    "test": "npm run build && npm run benchmark && tsx scripts/generate-capabilities.ts && tsx scripts/verify-capabilities.ts && tsx scripts/test-quality-gate.ts && tsx --test test/*.test.ts",
+    "test:core": "tsx --test test/scanner.test.ts test/patterns.test.ts",
+    "test:contracts": "npm run build:plugin && tsx scripts/release-gate.ts && tsx --test test/finding-schema.test.ts test/mcp.test.ts test/e2e-mcp.test.ts test/openclaw-plugin-compat.test.ts test/stale-claims.test.ts test/openclaw-upstream-check.test.ts",
+    "test:corpus": "tsx scripts/corpus-metrics.ts --check",
+    "test:perf": "tsx scripts/perf-regression.ts",
+    "test:quality": "tsx scripts/test-quality-gate.ts",
+    "test:rust-parity": "tsx scripts/rust-parity.ts",
+    "sbom": "tsx scripts/generate-sbom.ts",
+    "sync:readme": "tsx scripts/generate-capabilities.ts && tsx scripts/generate-readme-metrics.ts && tsx scripts/generate-readme-stats.ts",
+    "prepack": "npm run build:plugin && npm run release:gate"
   },
   "keywords": [
     "security",
@@ -47,20 +95,25 @@
   },
   "homepage": "https://github.com/koatora20/guard-scanner",
   "files": [
-    "src/",
+    "dist/",
     "hooks/",
     "docs/",
+    "openclaw-plugin.mts",
     "openclaw.plugin.json",
     "SKILL.md",
     "SECURITY.md",
     "README.md",
+    "README_ja.md",
     "LICENSE"
   ],
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "openclaw": "2026.3.12",
+    "tsx": "^4.20.5",
+    "tsup": "^8.5.0",
     "typescript": "^5.7.0"
   },
   "dependencies": {
     "ws": "^8.19.0"
   }
-}
+}