@guava-parity/guard-scanner 13.0.0 → 15.0.0

package/openclaw-plugin.mts

@@ -0,0 +1,91 @@
+import { createRequire } from "node:module";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+
+const require = createRequire(import.meta.url);
+const runtimeGuard = require("../src/runtime-guard.js") 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;
+        },
+    ) => {
+        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;
+};
+
+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 = runtimeGuard.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,
+    });
+
+    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 (validated for 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.",
+  "version": "15.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,36 @@
 {
   "name": "@guava-parity/guard-scanner",
-  "version": "13.0.0",
+  "version": "15.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 (v15)",
+  "openclaw": {
+    "extensions": [
+      "./dist/openclaw-plugin.mjs"
+    ]
   },
   "main": "src/scanner.js",
   "bin": {
     "guard-scanner": "src/cli.js"
   },
   "scripts": {
+    "build:plugin": "npx tsc -p tsconfig.build.json",
+    "check:upstream": "node scripts/check-openclaw-upstream.js",
     "scan": "node src/cli.js",
-    "test": "node scripts/test-quality-gate.js && node --test test/*.test.js",
+    "lint": "node scripts/lint.js",
+    "typecheck": "npx tsc --noEmit -p tsconfig.json",
+    "release:gate": "node scripts/release-gate.js",
+    "test": "npm run lint && npm run typecheck && npm run build:plugin && node scripts/generate-capabilities.js && node scripts/generate-readme-metrics.js && node scripts/generate-readme-stats.js && node scripts/verify-capabilities.js && node scripts/test-quality-gate.js && node scripts/corpus-metrics.js --check && node scripts/perf-regression.js && node scripts/release-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"
+    "test:contracts": "npm run build:plugin && node scripts/release-gate.js && node --test test/finding-schema.test.js test/mcp.test.js test/e2e-mcp.test.js test/openclaw-plugin-compat.test.js test/stale-claims.test.js test/openclaw-upstream-check.test.js",
+    "test:corpus": "node scripts/corpus-metrics.js --check",
+    "test:perf": "node scripts/perf-regression.js",
+    "test:quality": "node scripts/test-quality-gate.js",
+    "sbom": "node scripts/generate-sbom.js",
+    "sync:readme": "node scripts/generate-capabilities.js && node scripts/generate-readme-metrics.js && node scripts/generate-readme-stats.js",
+    "prepack": "npm run build:plugin && npm run release:gate"
   },
   "keywords": [
     "security",
@@ -47,9 +59,11 @@
   },
   "homepage": "https://github.com/koatora20/guard-scanner",
   "files": [
+    "dist/",
     "src/",
     "hooks/",
     "docs/",
+    "openclaw-plugin.mts",
     "openclaw.plugin.json",
     "SKILL.md",
     "SECURITY.md",
@@ -58,9 +72,10 @@
   ],
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "openclaw": "2026.3.8",
     "typescript": "^5.7.0"
   },
   "dependencies": {
     "ws": "^8.19.0"
   }
-}
+}

package/src/cli.js

@@ -150,6 +150,141 @@ Examples:
       process.exit(2);
     }
   })();
+
+  // ── crawl subcommand ──────────────────────────────────────────
+} else if (args[0] === 'crawl') {
+  const { SkillCrawler } = require('./skill-crawler.js');
+  const subCmd = args[1]; // clawhub | github | url
+  const target = args[2]; // query or URL
+  const verbose = args.includes('--verbose') || args.includes('-v');
+  const formatIdx = args.indexOf('--format');
+  const formatValue = formatIdx >= 0 ? args[formatIdx + 1] : null;
+  const quiet = !!formatValue;
+  const maxIdx = args.indexOf('--max');
+  const maxSkills = maxIdx >= 0 ? parseInt(args[maxIdx + 1], 10) : 50;
+
+  if (!subCmd || subCmd === '--help' || subCmd === '-h') {
+    console.log(`
+🛡️  guard-scanner crawl — Autonomous Skill Scanner
+
+Usage:
+  guard-scanner crawl clawhub              Crawl ClawHub for all SKILL.md
+  guard-scanner crawl github <query>       Search GitHub for SKILL.md
+  guard-scanner crawl url <url>            Scan a single SKILL.md URL
+
+Options:
+  --verbose, -v       Show detection details
+  --format json       Output JSON to stdout
+  --max <n>           Max skills to scan (default: 50)
+  --help, -h          Show this help
+
+Examples:
+  guard-scanner crawl clawhub --verbose
+  guard-scanner crawl github "polymarket trader" --format json
+  guard-scanner crawl url https://raw.githubusercontent.com/.../SKILL.md
+`);
+    process.exit(0);
+  }
+
+  const crawler = new SkillCrawler({ verbose, quiet, concurrency: 5 });
+
+  (async () => {
+    try {
+      if (subCmd === 'clawhub') {
+        await crawler.crawlClawHub({ maxSkills });
+      } else if (subCmd === 'github') {
+        if (!target) { console.error('❌ Usage: guard-scanner crawl github <query>'); process.exit(2); }
+        await crawler.crawlGitHub(target, { maxResults: maxSkills });
+      } else if (subCmd === 'url') {
+        if (!target) { console.error('❌ Usage: guard-scanner crawl url <url>'); process.exit(2); }
+        await crawler.scanUrl(target, target);
+      } else {
+        console.error(`❌ Unknown crawl target: ${subCmd}. Use: clawhub, github, or url`);
+        process.exit(2);
+      }
+
+      if (formatValue === 'json') {
+        process.stdout.write(JSON.stringify(crawler.toJSON(), null, 2) + '\n');
+      } else {
+        crawler.printSummary();
+      }
+
+      const summary = crawler.getSummary();
+      process.exit(summary.unsafe > 0 ? 1 : 0);
+    } catch (e) {
+      console.error(`❌ Crawl error: ${e.message}`);
+      process.exit(2);
+    }
+  })();
+
+  // ── patrol subcommand ──────────────────────────────────────────
+} else if (args[0] === 'patrol') {
+  const { SkillCrawler } = require('./skill-crawler.js');
+  const verbose = args.includes('--verbose') || args.includes('-v');
+  const once = args.includes('--once');
+  const intervalIdx = args.indexOf('--interval');
+  const intervalSecs = intervalIdx >= 0 ? parseInt(args[intervalIdx + 1], 10) : 3600;
+  const formatIdx = args.indexOf('--format');
+  const formatValue = formatIdx >= 0 ? args[formatIdx + 1] : null;
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+🛡️  guard-scanner patrol — Autonomous Security Patrol
+
+Usage:
+  guard-scanner patrol --once              Run one patrol cycle
+  guard-scanner patrol --interval 3600     Patrol every N seconds
+
+Options:
+  --once              Run once and exit
+  --interval <secs>   Polling interval (default: 3600 = 1 hour)
+  --verbose, -v       Show detection details
+  --format json       Output JSON
+  --help, -h          Show this help
+`);
+    process.exit(0);
+  }
+
+  async function runPatrol() {
+    const timestamp = new Date().toISOString();
+    console.log(`\n🚨 Patrol cycle starting at ${timestamp}`);
+    console.log('─'.repeat(54));
+
+    const crawler = new SkillCrawler({ verbose, quiet: !!formatValue, concurrency: 5 });
+    await crawler.crawlClawHub({ maxSkills: 50 });
+
+    if (formatValue === 'json') {
+      process.stdout.write(JSON.stringify(crawler.toJSON(), null, 2) + '\n');
+    } else {
+      crawler.printSummary();
+    }
+
+    const summary = crawler.getSummary();
+    if (summary.unsafe > 0) {
+      console.log(`\n⚠️  ${summary.unsafe} unsafe skill(s) detected!`);
+    }
+    return summary;
+  }
+
+  (async () => {
+    try {
+      if (once) {
+        const summary = await runPatrol();
+        process.exit(summary.unsafe > 0 ? 1 : 0);
+      } else {
+        console.log(`🛡️  guard-scanner patrol mode — interval: ${intervalSecs}s`);
+        console.log(`   Press Ctrl+C to stop\n`);
+        await runPatrol();
+        setInterval(async () => {
+          await runPatrol();
+        }, intervalSecs * 1000);
+      }
+    } catch (e) {
+      console.error(`❌ Patrol error: ${e.message}`);
+      process.exit(2);
+    }
+  })();
+
 } else {
   // ── existing scan logic (backward compatible) ─────────────────
 
@@ -249,46 +384,51 @@ Examples:
     !plugins.includes(a)
   ) || process.cwd();
 
-  const scanner = new GuardScanner({
-    verbose, selfExclude, strict, summaryOnly, checkDeps, soulLock, rulesFile, plugins,
-    quiet: quietMode || !!formatValue,
-  });
+  try {
+    const scanner = new GuardScanner({
+      verbose, selfExclude, strict, summaryOnly, checkDeps, soulLock, rulesFile, plugins,
+      quiet: quietMode || !!formatValue,
+    });
 
-  scanner.scanDirectory(scanDir);
+    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}`);
-  }
+    // 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 (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}`);
-  }
+    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'.`);
+    // --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);
+  } catch (error) {
+    console.error(`❌ ${error.message}`);
     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);
-
 } // end else (scan mode)

package/src/core/content-loader.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function loadIgnoreFile(scanDir) {
+    const ignoredSkills = new Set();
+    const ignoredPatterns = new Set();
+    const ignorePaths = [
+        path.join(scanDir, '.guard-scanner-ignore'),
+        path.join(scanDir, '.guava-guard-ignore'),
+    ];
+
+    for (const ignorePath of ignorePaths) {
+        if (!fs.existsSync(ignorePath)) continue;
+        const lines = fs.readFileSync(ignorePath, 'utf-8').split('\n');
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#')) continue;
+            if (trimmed.startsWith('pattern:')) ignoredPatterns.add(trimmed.replace('pattern:', '').trim());
+            else ignoredSkills.add(trimmed);
+        }
+        break;
+    }
+
+    return { ignoredSkills, ignoredPatterns };
+}
+
+function loadTextFile(filePath, maxLength = 500000) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        if (content.length > maxLength) return null;
+        return content;
+    } catch {
+        return null;
+    }
+}
+
+module.exports = {
+    loadIgnoreFile,
+    loadTextFile,
+};

package/src/core/inventory.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CODE_EXTENSIONS = new Set(['.js', '.ts', '.mjs', '.cjs', '.py', '.sh', '.bash', '.ps1', '.rb', '.go', '.rs', '.php', '.pl']);
+const DOC_EXTENSIONS = new Set(['.md', '.txt', '.rst', '.adoc']);
+const DATA_EXTENSIONS = new Set(['.json', '.yaml', '.yml', '.toml', '.xml', '.csv']);
+const BINARY_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.ico', '.woff', '.woff2', '.ttf', '.eot', '.wasm', '.wav', '.mp3', '.mp4', '.webm', '.ogg', '.pdf', '.zip', '.tar', '.gz', '.bz2', '.7z', '.exe', '.dll', '.so', '.dylib']);
+const GENERATED_REPORT_FILES = new Set(['guard-scanner-report.json', 'guard-scanner-report.html', 'guard-scanner.sarif']);
+
+function classifyFile(ext, relFile) {
+    if (CODE_EXTENSIONS.has(ext)) return 'code';
+    if (DOC_EXTENSIONS.has(ext)) return 'doc';
+    if (DATA_EXTENSIONS.has(ext)) return 'data';
+    const base = path.basename(relFile).toLowerCase();
+    if (base === 'skill.md' || base === 'readme.md') return 'skill-doc';
+    return 'other';
+}
+
+function isSelfNoisePath(skillName, relFile) {
+    if (skillName !== 'guard-scanner') return false;
+    return /^test\//.test(relFile)
+        || /^dist\/__tests__\//.test(relFile)
+        || /^ts-src\/__tests__\//.test(relFile)
+        || /^docs\//.test(relFile)
+        || relFile === 'ROADMAP-RESEARCH.md'
+        || relFile === 'CHANGELOG.md';
+}
+
+function isSelfThreatCorpus(skillName, relFile) {
+    if (skillName !== 'guard-scanner') return false;
+    return /(^|\/)(ioc-db|patterns)\.(js|ts)$/.test(relFile);
+}
+
+function getFiles(dir) {
+    const results = [];
+    try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === '.git' || entry.name === 'node_modules') continue;
+                results.push(...getFiles(fullPath));
+            } else {
+                const baseName = entry.name.toLowerCase();
+                if (GENERATED_REPORT_FILES.has(baseName)) continue;
+                results.push(fullPath);
+            }
+        }
+    } catch { }
+    return results;
+}
+
+function listSkills(dir) {
+    return fs.readdirSync(dir).filter((file) => {
+        const fullPath = path.join(dir, file);
+        return fs.statSync(fullPath).isDirectory();
+    });
+}
+
+module.exports = {
+    CODE_EXTENSIONS,
+    DOC_EXTENSIONS,
+    DATA_EXTENSIONS,
+    BINARY_EXTENSIONS,
+    GENERATED_REPORT_FILES,
+    classifyFile,
+    isSelfNoisePath,
+    isSelfThreatCorpus,
+    getFiles,
+    listSkills,
+};