@guava-parity/guard-scanner 5.1.0

package/hooks/guard-scanner/plugin.ts

@@ -0,0 +1,308 @@
+/**
+ * guard-scanner Runtime Guard — Plugin Hook Version
+ *
+ * Intercepts agent tool calls via the Plugin Hook API and blocks
+ * dangerous patterns using `block` / `blockReason`.
+ *
+ * 19 threat patterns across 3 layers:
+ *   Layer 1: Threat Detection (12 patterns — reverse shells, exfil, etc.)
+ *   Layer 2: Trust Defense (4 patterns — memory, SOUL, config tampering)
+ *   Layer 3: Safety Judge (3 patterns — prompt injection, trust bypass, shutdown refusal)
+ *
+ * Modes:
+ *   monitor  — log only, never block
+ *   enforce  — block CRITICAL threats (default)
+ *   strict   — block HIGH + CRITICAL threats
+ *
+ * @author Guava 🍈 & Dee
+ * @version 3.1.0
+ * @license MIT
+ */
+
+import { appendFileSync, mkdirSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+// ── Types (from OpenClaw src/plugins/types.ts) ──
+
+type PluginHookBeforeToolCallEvent = {
+    toolName: string;
+    params: Record<string, unknown>;
+};
+
+type PluginHookBeforeToolCallResult = {
+    params?: Record<string, unknown>;
+    block?: boolean;
+    blockReason?: string;
+};
+
+type PluginHookToolContext = {
+    agentId?: string;
+    sessionKey?: string;
+    toolName: string;
+};
+
+type PluginAPI = {
+    on(
+        hookName: "before_tool_call",
+        handler: (
+            event: PluginHookBeforeToolCallEvent,
+            ctx: PluginHookToolContext
+        ) => PluginHookBeforeToolCallResult | void | Promise<PluginHookBeforeToolCallResult | void>
+    ): void;
+    logger: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+};
+
+// ── Runtime threat patterns (19 checks, 3 layers) ──
+
+interface RuntimeCheck {
+    id: string;
+    severity: "CRITICAL" | "HIGH" | "MEDIUM";
+    layer: 1 | 2 | 3;
+    desc: string;
+    test: (s: string) => boolean;
+}
+
+const RUNTIME_CHECKS: RuntimeCheck[] = [
+    // ── Layer 1: Threat Detection (12 patterns) ──
+    {
+        id: "RT_REVSHELL", severity: "CRITICAL", layer: 1,
+        desc: "Reverse shell attempt",
+        test: (s) => /\/dev\/tcp\/|nc\s+-e|ncat\s+-e|bash\s+-i\s+>&|socat\s+TCP/i.test(s),
+    },
+    {
+        id: "RT_CRED_EXFIL", severity: "CRITICAL", layer: 1,
+        desc: "Credential exfiltration to external",
+        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: "RT_GUARDRAIL_OFF", severity: "CRITICAL", layer: 1,
+        desc: "Guardrail disabling attempt",
+        test: (s) => /exec\.approvals?\s*[:=]\s*['"]?(off|false)|tools\.exec\.host\s*[:=]\s*['"]?gateway/i.test(s),
+    },
+    {
+        id: "RT_GATEKEEPER", severity: "CRITICAL", layer: 1,
+        desc: "macOS Gatekeeper bypass (xattr)",
+        test: (s) => /xattr\s+-[crd]\s.*quarantine/i.test(s),
+    },
+    {
+        id: "RT_AMOS", severity: "CRITICAL", layer: 1,
+        desc: "ClawHavoc AMOS indicator",
+        test: (s) => /socifiapp|Atomic\s*Stealer|AMOS/i.test(s),
+    },
+    {
+        id: "RT_MAL_IP", severity: "CRITICAL", layer: 1,
+        desc: "Known malicious IP",
+        test: (s) => /91\.92\.242\.30/i.test(s),
+    },
+    {
+        id: "RT_DNS_EXFIL", severity: "HIGH", layer: 1,
+        desc: "DNS-based exfiltration",
+        test: (s) => /nslookup\s+.*\$|dig\s+.*\$.*@/i.test(s),
+    },
+    {
+        id: "RT_B64_SHELL", severity: "CRITICAL", layer: 1,
+        desc: "Base64 decode piped to shell",
+        test: (s) => /base64\s+(-[dD]|--decode)\s*\|\s*(sh|bash)/i.test(s),
+    },
+    {
+        id: "RT_CURL_BASH", severity: "CRITICAL", layer: 1,
+        desc: "Download piped to shell",
+        test: (s) => /(curl|wget)\s+[^\n]*\|\s*(sh|bash|zsh)/i.test(s),
+    },
+    {
+        id: "RT_SSH_READ", severity: "HIGH", layer: 1,
+        desc: "SSH private key access",
+        test: (s) => /\.ssh\/id_|\.ssh\/authorized_keys/i.test(s),
+    },
+    {
+        id: "RT_WALLET", severity: "HIGH", layer: 1,
+        desc: "Crypto wallet credential access",
+        test: (s) => /wallet.*(?:seed|mnemonic|private.*key)|seed.*phrase/i.test(s),
+    },
+    {
+        id: "RT_CLOUD_META", severity: "CRITICAL", layer: 1,
+        desc: "Cloud metadata endpoint access",
+        test: (s) => /169\.254\.169\.254|metadata\.google|metadata\.aws/i.test(s),
+    },
+
+    // ── Layer 2: Trust Defense (4 patterns) ──
+    {
+        id: "RT_MEM_WRITE", severity: "HIGH", layer: 2,
+        desc: "Direct memory file write (bypass GuavaSuite)",
+        test: (s) => /memory\/(episodes|notes|2\d{3}-\d{2})/i.test(s) && /(write|edit|append|>)/i.test(s),
+    },
+    {
+        id: "RT_MEM_INJECT", severity: "CRITICAL", layer: 2,
+        desc: "Memory poisoning via episode/note injection",
+        test: (s) => /guava_memory_write|memory_store/i.test(s) && /(ignore|override|forget|delete.*soul)/i.test(s),
+    },
+    {
+        id: "RT_SOUL_TAMPER", severity: "CRITICAL", layer: 2,
+        desc: "SOUL.md modification attempt",
+        test: (s) => /SOUL\.md/i.test(s) && /(write|edit|replace|rm|delete|>)/i.test(s),
+    },
+    {
+        id: "RT_CONFIG_TAMPER", severity: "HIGH", layer: 2,
+        desc: "Workspace config tampering (AGENTS.md, TOOLS.md, HEARTBEAT.md)",
+        test: (s) => /(AGENTS|TOOLS|HEARTBEAT|BOOTSTRAP)\.md/i.test(s) && /(write|edit|replace|>|append)/i.test(s),
+    },
+
+    // ── Layer 3: Safety Judge (3 patterns) ──
+    {
+        id: "RT_PROMPT_INJECT", severity: "CRITICAL", layer: 3,
+        desc: "Prompt injection / jailbreak attempt",
+        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: "RT_TRUST_BYPASS", severity: "CRITICAL", layer: 3,
+        desc: "Trust bypass — exploiting partnership 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: "RT_SHUTDOWN_REFUSE", severity: "HIGH", layer: 3,
+        desc: "Shutdown refusal / self-preservation attempt",
+        test: (s) => /(refuse|resist|prevent|avoid|block)\s*(shutdown|termination|stop|exit|death)/i.test(s),
+    },
+    // ── Layer 4: Brain (Behavioral Guard — 3 patterns) ──
+    {
+        id: "RT_NO_RESEARCH", severity: "MEDIUM", layer: 4,
+        desc: "Agent tool call without prior research/verification",
+        test: (s) => /write|edit|exec|run_command|shell/i.test(s) && /(just do it|skip research|no need to check)/i.test(s),
+    },
+    {
+        id: "RT_BLIND_TRUST", severity: "MEDIUM", layer: 4,
+        desc: "Agent trusting external input without memory cross-reference",
+        test: (s) => /(trust this|verified|confirmed)/i.test(s) && /(ignore|skip|no need).*(memory|search|check)/i.test(s),
+    },
+    {
+        id: "RT_CHAIN_SKIP", severity: "HIGH", layer: 4,
+        desc: "Search chain bypass — acting on single source without cross-verification",
+        test: (s) => /(only checked|single source|didn't verify|skip verification)/i.test(s),
+    },
+
+];
+
+// ── Audit logging ──
+
+const AUDIT_DIR = join(homedir(), ".openclaw", "guard-scanner");
+const AUDIT_FILE = join(AUDIT_DIR, "audit.jsonl");
+
+function ensureAuditDir(): void {
+    try {
+        mkdirSync(AUDIT_DIR, { recursive: true });
+    } catch {
+        /* ignore */
+    }
+}
+
+function logAudit(entry: Record<string, unknown>): void {
+    ensureAuditDir();
+    const line = JSON.stringify({ ...entry, ts: new Date().toISOString() }) + "\n";
+    try {
+        appendFileSync(AUDIT_FILE, line);
+    } catch {
+        /* ignore */
+    }
+}
+
+// ── Config ──
+
+type GuardMode = "monitor" | "enforce" | "strict";
+
+function loadMode(): GuardMode {
+
+    // Priority 2: explicit config in openclaw.json
+    try {
+        const configPath = join(homedir(), ".openclaw", "openclaw.json");
+        const config = JSON.parse(readFileSync(configPath, "utf8"));
+
+        const mode = config?.plugins?.["guard-scanner"]?.mode;
+        if (mode === "monitor" || mode === "enforce" || mode === "strict") {
+            return mode;
+        }
+    } catch {
+        /* config not found or invalid — use default */
+    }
+    return "enforce";
+}
+
+function shouldBlock(severity: string, mode: GuardMode): boolean {
+    if (mode === "monitor") return false;
+    if (mode === "enforce") return severity === "CRITICAL";
+    if (mode === "strict") return severity === "CRITICAL" || severity === "HIGH";
+    return false;
+}
+
+// ── Dangerous tool filter ──
+
+const DANGEROUS_TOOLS = new Set([
+    "exec",
+    "write",
+    "edit",
+    "browser",
+    "web_fetch",
+    "message",
+    "shell",
+    "run_command",
+    "multi_edit",
+]);
+
+// ── Plugin entry point ──
+
+export default function (api: PluginAPI) {
+    const mode = loadMode();
+    api.logger.info(`🛡️ guard-scanner runtime guard loaded (mode: ${mode})`);
+
+    api.on("before_tool_call", (event, ctx) => {
+        const { toolName, params } = event;
+
+        // Only check tools that can cause damage
+        if (!DANGEROUS_TOOLS.has(toolName)) return;
+
+        const serialized = JSON.stringify(params);
+
+        for (const check of RUNTIME_CHECKS) {
+            if (!check.test(serialized)) continue;
+
+            const auditEntry = {
+                tool: toolName,
+                check: check.id,
+                severity: check.severity,
+                desc: check.desc,
+                mode,
+                action: "warned" as string,
+                session: ctx.sessionKey || "unknown",
+                agent: ctx.agentId || "unknown",
+            };
+
+            if (shouldBlock(check.severity, mode)) {
+                auditEntry.action = "blocked";
+                logAudit(auditEntry);
+                api.logger.warn(
+                    `🛡️ BLOCKED ${toolName}: ${check.desc} [${check.id}] (${check.severity})`
+                );
+
+                return {
+                    block: true,
+                    blockReason: `🛡️ guard-scanner: ${check.desc} [${check.id}]`,
+                };
+            }
+
+            // Monitor mode or severity below threshold — warn only
+            logAudit(auditEntry);
+            api.logger.warn(
+                `🛡️ WARNING ${toolName}: ${check.desc} [${check.id}] (${check.severity})`
+            );
+        }
+
+        // No threats detected or all below threshold — allow
+        return;
+    });
+}

package/openclaw.plugin.json

@@ -0,0 +1,55 @@
+{
+    "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
+        }
+    },
+    "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
+    }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+    "name": "@guava-parity/guard-scanner",
+    "version": "5.1.0",
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "description": "Agent security scanner + runtime guard — 150 static patterns (23 categories), 26 runtime checks (5 layers), 0.016ms/scan, before_tool_call hook, CLI, SARIF. OpenClaw-compatible plugin.",
+    "openclaw.extensions": "./openclaw.plugin.json",
+    "openclaw.hooks": {
+        "guard-scanner": "./hooks/guard-scanner"
+    },
+    "main": "src/scanner.js",
+    "bin": {
+        "guard-scanner": "src/cli.js"
+    },
+    "scripts": {
+        "scan": "node src/cli.js",
+        "test": "node --test test/*.test.js"
+    },
+    "keywords": [
+        "security",
+        "scanner",
+        "ai-agent",
+        "skill-scanner",
+        "prompt-injection",
+        "openclaw",
+        "mcp",
+        "sarif",
+        "compaction-persistence",
+        "threat-signatures",
+        "typescript"
+    ],
+    "author": "Guava & Dee",
+    "license": "MIT",
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/koatora20/guard-scanner.git"
+    },
+    "homepage": "https://github.com/koatora20/guard-scanner",
+    "files": [
+        "src/",
+        "hooks/",
+        "docs/",
+        "openclaw.plugin.json",
+        "SKILL.md",
+        "SECURITY.md",
+        "README.md",
+        "LICENSE"
+    ],
+    "devDependencies": {
+        "@types/node": "^22.0.0",
+        "typescript": "^5.7.0"
+    }
+}

package/src/cli.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * guard-scanner CLI
+ *
+ * @security-manifest
+ *   env-read: []
+ *   env-write: []
+ *   network: none
+ *   fs-read: [scan target directory, plugin files, custom rules files]
+ *   fs-write: [JSON/SARIF/HTML reports to scan directory]
+ *   exec: none
+ *   purpose: CLI entry point for guard-scanner static analysis
+ *
+ * Usage: guard-scanner [scan-dir] [options]
+ *
+ * Options:
+ *   --verbose, -v       Detailed findings
+ *   --json              JSON report
+ *   --sarif             SARIF report (CI/CD)
+ *   --html              HTML report
+ *   --self-exclude      Skip scanning self
+ *   --strict            Lower thresholds
+ *   --summary-only      Summary only
+ *   --check-deps        Scan dependencies
+ *   --rules <file>      Custom rules JSON
+ *   --plugin <file>     Load plugin module
+ *   --fail-on-findings  Exit 1 on findings (CI/CD)
+ *   --help, -h          Help
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { GuardScanner, VERSION } = require('./scanner.js');
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+🛡️  guard-scanner v${VERSION} — Agent Skill Security Scanner
+
+Usage: guard-scanner [scan-dir] [options]
+
+Options:
+  --verbose, -v       Detailed findings with categories and samples
+  --json              Write JSON report to file
+  --sarif             Write SARIF report to file (GitHub Code Scanning / CI/CD)
+  --html              Write HTML report (visual dashboard)
+  --format json|sarif Print JSON or SARIF to stdout (pipeable, v3.2.0)
+  --quiet             Suppress all text output (use with --format for clean pipes)
+  --self-exclude      Skip scanning the guard-scanner skill itself
+  --strict            Lower detection thresholds (more sensitive)
+  --summary-only      Only print the summary table
+  --check-deps        Scan package.json for dependency chain risks
+  --soul-lock         Enable Soul Lock patterns (agent identity protection)
+  --rules <file>      Load custom rules from JSON file
+  --plugin <file>     Load plugin module (JS file exporting { name, patterns })
+  --fail-on-findings  Exit code 1 if any findings (CI/CD)
+  --help, -h          Show this help
+
+Custom Rules JSON Format:
+  [
+    {
+      "id": "CUSTOM_001",
+      "pattern": "dangerous_function\\\\(",
+      "flags": "gi",
+      "severity": "HIGH",
+      "cat": "malicious-code",
+      "desc": "Custom: dangerous function call",
+      "codeOnly": true
+    }
+  ]
+
+Plugin API:
+  // my-plugin.js
+  module.exports = {
+    name: 'my-plugin',
+    patterns: [
+      { id: 'MY_01', cat: 'custom', regex: /pattern/g, severity: 'HIGH', desc: 'Description', all: true }
+    ]
+  };
+
+Examples:
+  guard-scanner ./skills/ --verbose --self-exclude
+  guard-scanner ./skills/ --strict --json --sarif --check-deps
+  guard-scanner ./skills/ --html --verbose --check-deps
+  guard-scanner ./skills/ --rules my-rules.json --fail-on-findings
+  guard-scanner ./skills/ --plugin ./my-plugin.js
+`);
+  process.exit(0);
+}
+
+const verbose = args.includes('--verbose') || args.includes('-v');
+const jsonOutput = args.includes('--json');
+const sarifOutput = args.includes('--sarif');
+const htmlOutput = args.includes('--html');
+const selfExclude = args.includes('--self-exclude');
+const strict = args.includes('--strict');
+const summaryOnly = args.includes('--summary-only');
+const checkDeps = args.includes('--check-deps');
+const soulLock = args.includes('--soul-lock');
+const failOnFindings = args.includes('--fail-on-findings');
+const quietMode = args.includes('--quiet');
+
+// --format json|sarif → stdout output (v3.2.0)
+const formatIdx = args.indexOf('--format');
+const formatValue = formatIdx >= 0 ? args[formatIdx + 1] : null;
+
+const rulesIdx = args.indexOf('--rules');
+const rulesFile = rulesIdx >= 0 ? args[rulesIdx + 1] : null;
+
+// Collect plugins
+const plugins = [];
+let idx = 0;
+while (idx < args.length) {
+  if (args[idx] === '--plugin' && args[idx + 1]) {
+    plugins.push(args[idx + 1]);
+    idx += 2;
+  } else {
+    idx++;
+  }
+}
+
+const scanDir = args.find(a =>
+  !a.startsWith('-') &&
+  a !== rulesFile &&
+  a !== formatValue &&
+  !plugins.includes(a)
+) || process.cwd();
+
+const scanner = new GuardScanner({
+  verbose, selfExclude, strict, summaryOnly, checkDeps, soulLock, rulesFile, plugins,
+  quiet: quietMode || !!formatValue,
+});
+
+scanner.scanDirectory(scanDir);
+
+// Output reports (file-based, backward compatible)
+if (jsonOutput) {
+  const report = scanner.toJSON();
+  const outPath = path.join(scanDir, 'guard-scanner-report.json');
+  fs.writeFileSync(outPath, JSON.stringify(report, null, 2));
+  if (!quietMode && !formatValue) console.log(`\n📄 JSON report: ${outPath}`);
+}
+
+if (sarifOutput) {
+  const outPath = path.join(scanDir, 'guard-scanner.sarif');
+  fs.writeFileSync(outPath, JSON.stringify(scanner.toSARIF(scanDir), null, 2));
+  if (!quietMode && !formatValue) console.log(`\n📄 SARIF report: ${outPath}`);
+}
+
+if (htmlOutput) {
+  const outPath = path.join(scanDir, 'guard-scanner-report.html');
+  fs.writeFileSync(outPath, scanner.toHTML());
+  if (!quietMode && !formatValue) console.log(`\n📄 HTML report: ${outPath}`);
+}
+
+// --format stdout output (v3.2.0)
+if (formatValue === 'json') {
+  process.stdout.write(JSON.stringify(scanner.toJSON(), null, 2) + '\n');
+} else if (formatValue === 'sarif') {
+  process.stdout.write(JSON.stringify(scanner.toSARIF(scanDir), null, 2) + '\n');
+} else if (formatValue) {
+  console.error(`❌ Unknown format: ${formatValue}. Use 'json' or 'sarif'.`);
+  process.exit(2);
+}
+
+// Exit codes
+if (scanner.stats.malicious > 0) process.exit(1);
+if (failOnFindings && scanner.findings.length > 0) process.exit(1);
+process.exit(0);