guard-scanner 2.1.0 → 3.1.0

package/ts-src/types.ts

@@ -0,0 +1,187 @@
+/**
+ * guard-scanner v3.0.0 — Type Definitions
+ * TypeScript rewrite with full type safety
+ */
+
+// ── Severity & Verdict ──────────────────────────────────────────────────────
+
+export type Severity = 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
+
+export type VerdictLabel = 'MALICIOUS' | 'SUSPICIOUS' | 'LOW RISK' | 'CLEAN';
+export type VerdictStat = 'malicious' | 'suspicious' | 'low' | 'clean';
+
+export interface Verdict {
+    icon: string;
+    label: VerdictLabel;
+    stat: VerdictStat;
+}
+
+// ── File Types ──────────────────────────────────────────────────────────────
+
+export type FileType = 'code' | 'doc' | 'data' | 'skill-doc' | 'other';
+
+// ── Findings ────────────────────────────────────────────────────────────────
+
+export interface Finding {
+    severity: Severity;
+    id: string;
+    cat: string;
+    desc: string;
+    file: string;
+    line?: number;
+    matchCount?: number;
+    sample?: string;
+}
+
+export interface SkillResult {
+    skill: string;
+    risk: number;
+    verdict: VerdictLabel;
+    findings: Finding[];
+}
+
+// ── Patterns ────────────────────────────────────────────────────────────────
+
+export interface PatternRule {
+    id: string;
+    cat: string;
+    regex: RegExp;
+    severity: Severity;
+    desc: string;
+    codeOnly?: boolean;
+    docOnly?: boolean;
+    all?: boolean;
+    /** OWASP LLM Top 10 2025 mapping (e.g. 'LLM01', 'LLM06') */
+    owasp?: string;
+}
+
+export interface CustomRuleInput {
+    id: string;
+    pattern: string;
+    flags?: string;
+    severity: Severity;
+    cat: string;
+    desc: string;
+    codeOnly?: boolean;
+    docOnly?: boolean;
+}
+
+// ── IoC Database ────────────────────────────────────────────────────────────
+
+export interface IoC_Database {
+    ips: string[];
+    domains: string[];
+    urls: string[];
+    usernames: string[];
+    filenames: string[];
+    typosquats: string[];
+}
+
+// ── Signature Database (hbg-scan compatible) ────────────────────────────────
+
+export interface ThreatSignature {
+    id: string;
+    name: string;
+    severity: Severity;
+    description: string;
+    hash?: string;          // SHA-256 content hash match
+    patterns?: string[];    // String patterns to match
+    domains?: string[];     // Suspicious domains
+}
+
+export interface SignatureDatabase {
+    version: string;
+    updated: string;
+    signatures: ThreatSignature[];
+}
+
+// ── Scanner Options ─────────────────────────────────────────────────────────
+
+export interface ScannerOptions {
+    verbose?: boolean;
+    selfExclude?: boolean;
+    strict?: boolean;
+    summaryOnly?: boolean;
+    checkDeps?: boolean;
+    rulesFile?: string;
+    plugins?: string[];
+}
+
+// ── Scanner Stats ───────────────────────────────────────────────────────────
+
+export interface ScanStats {
+    scanned: number;
+    clean: number;
+    low: number;
+    suspicious: number;
+    malicious: number;
+}
+
+// ── Thresholds ──────────────────────────────────────────────────────────────
+
+export interface Thresholds {
+    suspicious: number;
+    malicious: number;
+}
+
+// ── Reports ─────────────────────────────────────────────────────────────────
+
+export interface JSONReport {
+    timestamp: string;
+    scanner: string;
+    mode: 'strict' | 'normal';
+    stats: ScanStats;
+    thresholds: Thresholds;
+    findings: SkillResult[];
+    recommendations: Recommendation[];
+    iocVersion: string;
+    signaturesVersion?: string;
+}
+
+export interface Recommendation {
+    skill: string;
+    actions: string[];
+}
+
+// ── SARIF ───────────────────────────────────────────────────────────────────
+
+export interface SARIFReport {
+    version: string;
+    $schema: string;
+    runs: SARIFRun[];
+}
+
+export interface SARIFRun {
+    tool: {
+        driver: {
+            name: string;
+            version: string;
+            informationUri: string;
+            rules: SARIFRule[];
+        };
+    };
+    results: SARIFResult[];
+    invocations: Array<{ executionSuccessful: boolean; endTimeUtc: string }>;
+}
+
+export interface SARIFRule {
+    id: string;
+    name: string;
+    shortDescription: { text: string };
+    defaultConfiguration: { level: string };
+    properties: { tags: string[]; 'security-severity': string };
+}
+
+export interface SARIFResult {
+    ruleId: string;
+    ruleIndex: number;
+    level: string;
+    message: { text: string };
+    partialFingerprints: { primaryLocationLineHash: string };
+    locations: Array<{
+        physicalLocation: {
+            artifactLocation: { uri: string; uriBaseId: string };
+            region?: { startLine: number };
+        };
+    }>;
+}

package/hooks/guard-scanner/handler.ts

@@ -1,207 +0,0 @@
-/**
- * guard-scanner Runtime Guard — Hook Handler (LEGACY)
- *
- * ⚠️ DEPRECATED: Use plugin.ts instead.
- * This Internal Hook version can only WARN, not block.
- * The Plugin Hook version (plugin.ts) uses the native
- * `block` / `blockReason` API to actually prevent execution.
- *
- * 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.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) ──
-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)
-    },
-    {
-        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(): void {
-    try { mkdirSync(AUDIT_DIR, { recursive: true }); } catch { }
-}
-
-function logAudit(entry: Record<string, unknown>): void {
-    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 agent:before_tool_call events
-    if (event.type !== "agent" || event.action !== "before_tool_call") return;
-
-    const { toolName, toolArgs } = event.context as {
-        toolName?: string;
-        toolArgs?: Record<string, unknown>;
-    };
-    if (!toolName || !toolArgs) return;
-
-    // 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 tools that can cause damage
-    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: 'warned' as string,
-                session: event.sessionKey,
-            };
-
-            // 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}]`);
-            }
-        }
-    }
-};
-
-export default handler;

package/src/cli.js

@@ -1,149 +0,0 @@
-#!/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 scan-dir/guard-scanner-report.json
-  --sarif             Write SARIF report (GitHub Code Scanning / CI/CD)
-  --html              Write HTML report (visual dashboard)
-  --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
-  --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 failOnFindings = args.includes('--fail-on-findings');
-
-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 &&
-    !plugins.includes(a)
-) || process.cwd();
-
-const scanner = new GuardScanner({
-    verbose, selfExclude, strict, summaryOnly, checkDeps, rulesFile, plugins
-});
-
-scanner.scanDirectory(scanDir);
-
-// Output reports
-if (jsonOutput) {
-    const report = scanner.toJSON();
-    const outPath = path.join(scanDir, 'guard-scanner-report.json');
-    fs.writeFileSync(outPath, JSON.stringify(report, null, 2));
-    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));
-    console.log(`\n📄 SARIF report: ${outPath}`);
-}
-
-if (htmlOutput) {
-    const outPath = path.join(scanDir, 'guard-scanner-report.html');
-    fs.writeFileSync(outPath, scanner.toHTML());
-    console.log(`\n📄 HTML report: ${outPath}`);
-}
-
-// Exit codes
-if (scanner.stats.malicious > 0) process.exit(1);
-if (failOnFindings && scanner.findings.length > 0) process.exit(1);
-process.exit(0);