@guava-parity/guard-scanner 16.0.1 → 17.0.0

package/dist/index.d.cts

@@ -0,0 +1,214 @@
+import { ScannerOptions, GuardScannerInstance } from './types.cjs';
+export { CapabilityMetrics, CustomRule, Finding, GuardMode, GuardScannerConstructor, McpRequest, PluginConfig, RuntimeCheckStats, RuntimeDecision, SarifReport, ScanReport, ScanResult, Severity } from './types.cjs';
+export { MCPServer, TOOLS, startServer } from './mcp-server.cjs';
+
+declare const SEVERITY_WEIGHTS: {
+    CRITICAL: number;
+    HIGH: number;
+    MEDIUM: number;
+    LOW: number;
+};
+
+/**
+ * guard-scanner — Runtime Guard Module
+ *
+ * @security-manifest
+ *   env-read: []
+ *   env-write: []
+ *   network: none
+ *   fs-read: [~/.openclaw/openclaw.json (config), ~/.openclaw/guava-suite/token.jwt]
+ *   fs-write: [~/.openclaw/guard-scanner/audit.jsonl]
+ *   exec: none
+ *   purpose: Runtime threat pattern matching for agent tool calls
+ *
+ * 26 threat patterns across 5 layers:
+ *   Layer 1: Threat Detection (12) — reverse shells, exfil, guardrail bypass
+ *   Layer 2: Trust Defense (4) — memory, SOUL, config tampering
+ *   Layer 3: Safety Judge (3) — prompt injection, trust bypass, shutdown refusal
+ *   Layer 4: Brain/Behavioral (3) — research skip, blind trust, chain bypass
+ *   Layer 5: Trust Exploitation (4) — OWASP ASI09 authority/trust/audit abuse
+ *
+ * Modes:
+ *   monitor  — log only, never block
+ *   enforce  — block CRITICAL threats (default)
+ *   strict   — block HIGH + CRITICAL threats
+ *
+ * Based on hooks/guard-scanner/plugin.ts (TypeScript version for OpenClaw Plugin API)
+ * This module is the zero-dependency JavaScript equivalent for CLI and programmatic use.
+ *
+ * @author Guava 🍈 & Dee
+ * @version 3.4.0
+ * @license MIT
+ */
+declare const RUNTIME_CHECKS: {
+    id: string;
+    severity: string;
+    layer: number;
+    desc: string;
+    test: (s: any) => boolean;
+}[];
+/**
+ * Scan a tool call for runtime threats.
+ *
+ * @param {string} toolName - Name of the tool being called
+ * @param {object} params - Tool call parameters
+ * @param {object} [options] - Options
+ * @param {string} [options.mode] - Override mode ('monitor' | 'enforce' | 'strict')
+ * @param {boolean} [options.auditLog=true] - Enable audit logging
+ * @param {string} [options.sessionKey] - Session identifier for audit
+ * @param {string} [options.sessionId] - Ephemeral OpenClaw session UUID for audit
+ * @param {string} [options.runId] - Stable OpenClaw run identifier for audit
+ * @param {string} [options.toolCallId] - Provider tool call identifier for audit
+ * @param {string} [options.agentId] - Agent identifier for audit
+ * @param {object} [options.policy] - Session policy contract
+ * @returns {{ blocked: boolean, detections: Array<{id: string, severity: string, layer: number, desc: string, action: string}> }}
+ */
+declare function scanToolCall(toolName: any, params: any, options?: {}): {
+    blocked: boolean;
+    blockReason: null;
+    detections: never[];
+    mode: any;
+    toolName: any;
+    matchedPolicyId: null;
+    policyRationale: null;
+    riskAmplificationReasons: never[];
+    remediationSuggestion: null;
+    policyDecision: null;
+    contract_violations: never[];
+    behavioral_sequences: never[];
+};
+/**
+ * Get runtime check statistics.
+ * @returns {{ total: number, byLayer: object, bySeverity: object }}
+ */
+declare function getCheckStats(): {
+    total: number;
+    byLayer: {};
+    bySeverity: {};
+};
+declare const LAYER_NAMES: {
+    1: string;
+    2: string;
+    3: string;
+    4: string;
+    5: string;
+};
+
+/**
+ * guard-scanner v2.1.0 — Agent Skill Security Scanner 🛡️
+ *
+ * @security-manifest
+ *   env-read: []
+ *   env-write: []
+ *   network: none
+ *   fs-read: [scan target directory (user-specified)]
+ *   fs-write: [JSON/SARIF/HTML reports to scan directory]
+ *   exec: none
+ *   purpose: Static analysis of agent skill files for threat patterns
+ *
+ * Based on GuavaGuard v9.0.0 (OSS extraction)
+ * 20 threat categories • Snyk ToxicSkills + OWASP MCP Top 10
+ * Lightweight runtime footprint • CLI + JSON + SARIF + HTML output
+ * Plugin API for custom detection rules
+ *
+ * Born from a real 3-day agent identity hijack (2026-02-12)
+ *
+ * License: MIT
+ */
+
+declare const VERSION: string;
+declare const THRESHOLDS: {
+    normal: {
+        suspicious: number;
+        malicious: number;
+    };
+    strict: {
+        suspicious: number;
+        malicious: number;
+    };
+};
+declare class GuardScanner {
+    constructor(options?: {});
+    loadPlugin(pluginPath: any): void;
+    loadCustomRules(rulesFile: any): void;
+    loadIgnoreFile(scanDir: any): void;
+    /**
+     * Scan raw text for threats (used for Discord incoming messages, etc.)
+     * @param {string} text - Raw text to scan
+     * @returns {{ safe: boolean, risk: number, detections: Array }}
+     */
+    scanText(text: any): {
+        safe: boolean;
+        risk: any;
+        detections: any[];
+    };
+    scanDirectory(dir: any): any;
+    scanTarget(targetPath: any): any;
+    scanSkill(skillPath: any, skillName: any): void;
+    classifyFile(ext: any, relFile: any): any;
+    isSelfNoisePath(skillName: any, relFile: any): any;
+    isSelfThreatCorpus(skillName: any, relFile: any): any;
+    checkIoCs(content: any, relFile: any, findings: any): void;
+    annotateV16Findings(findings: any): void;
+    pushUniqueFinding(findings: any, finding: any): void;
+    analyzeProtocolFindings(content: any, relFile: any, fileType: any, findings: any): void;
+    analyzeCognitiveFindings(content: any, relFile: any, fileType: any, findings: any): void;
+    analyzeThreatIntelFindings(content: any, relFile: any, fileType: any, findings: any): void;
+    checkPatterns(content: any, relFile: any, fileType: any, findings: any, patterns?: null): void;
+    checkHardcodedSecrets(content: any, relFile: any, findings: any): void;
+    shannonEntropy(str: any): number;
+    checkStructure(skillPath: any, skillName: any, findings: any): void;
+    checkDependencies(skillPath: any, skillName: any, findings: any): void;
+    checkSkillManifest(skillPath: any, skillName: any, findings: any): void;
+    checkComplexity(skillPath: any, skillName: any, findings: any): void;
+    checkConfigImpact(skillPath: any, skillName: any, findings: any): void;
+    checkHiddenFiles(skillPath: any, skillName: any, findings: any): void;
+    checkJSDataFlow(content: any, relFile: any, findings: any): void;
+    checkCrossFile(skillPath: any, skillName: any, findings: any): void;
+    checkRuntimeIntegration(skillPath: any, skillName: any, findings: any): void;
+    calculateRisk(findings: any): any;
+    getVerdict(risk: any): any;
+    getFiles(dir: any): any;
+    printSummary(): any;
+    toJSON(): any;
+    toSARIF(scanDir: any): any;
+    toHTML(): any;
+    /**
+     * Generate a Threat Model based on the scan findings.
+     * @param {Array<Object>} findings - The array of findings from the scan.
+     * @returns {Object} The generated threat model.
+     */
+    /**
+     * Check AST for contextual validation of high-risk chains.
+     * Separates heuristic-only matches from validated chains.
+     */
+    checkASTValidation(content: any, relFile: any, findings: any): any;
+    appendThreatModelFindings(content: any, findings: any, relFile?: string): void;
+    generateThreatModel(findings: any): {
+        timestamp: string;
+        surface: {
+            network: boolean;
+            file_system: boolean;
+            code_execution: boolean;
+            credential_exposure: boolean;
+            external_ingestion: boolean;
+            persistence: boolean;
+        };
+        capabilities: any;
+        compounded_risks: any;
+        lethal_trifecta: any;
+        summary: string;
+        owasp_asi: unknown[];
+        protocol_surfaces: unknown[];
+        layer_summary: {
+            layer: any;
+            layer_name: any;
+        }[];
+    };
+    generatePopulationMonitor(): any;
+    generateMetaGuard(): any;
+}
+
+declare function createScanner(options?: ScannerOptions): GuardScannerInstance;
+
+export { GuardScanner, GuardScannerInstance, LAYER_NAMES, RUNTIME_CHECKS, SEVERITY_WEIGHTS, ScannerOptions, THRESHOLDS, VERSION, createScanner, getCheckStats, scanToolCall };

package/dist/index.d.ts

@@ -1,17 +1,214 @@
-import { GuardScannerConstructor, ScannerOptions, GuardScannerInstance, RuntimeCheckStats, RuntimeDecision } from './types.js';
-export { CapabilityMetrics, CustomRule, Finding, GuardMode, McpRequest, PluginConfig, SarifReport, ScanReport, ScanResult, Severity } from './types.js';
+import { ScannerOptions, GuardScannerInstance } from './types.js';
+export { CapabilityMetrics, CustomRule, Finding, GuardMode, GuardScannerConstructor, McpRequest, PluginConfig, RuntimeCheckStats, RuntimeDecision, SarifReport, ScanReport, ScanResult, Severity } from './types.js';
+export { MCPServer, TOOLS, startServer } from './mcp-server.js';
+
+declare const SEVERITY_WEIGHTS: {
+    CRITICAL: number;
+    HIGH: number;
+    MEDIUM: number;
+    LOW: number;
+};
+
+/**
+ * guard-scanner — Runtime Guard Module
+ *
+ * @security-manifest
+ *   env-read: []
+ *   env-write: []
+ *   network: none
+ *   fs-read: [~/.openclaw/openclaw.json (config), ~/.openclaw/guava-suite/token.jwt]
+ *   fs-write: [~/.openclaw/guard-scanner/audit.jsonl]
+ *   exec: none
+ *   purpose: Runtime threat pattern matching for agent tool calls
+ *
+ * 26 threat patterns across 5 layers:
+ *   Layer 1: Threat Detection (12) — reverse shells, exfil, guardrail bypass
+ *   Layer 2: Trust Defense (4) — memory, SOUL, config tampering
+ *   Layer 3: Safety Judge (3) — prompt injection, trust bypass, shutdown refusal
+ *   Layer 4: Brain/Behavioral (3) — research skip, blind trust, chain bypass
+ *   Layer 5: Trust Exploitation (4) — OWASP ASI09 authority/trust/audit abuse
+ *
+ * Modes:
+ *   monitor  — log only, never block
+ *   enforce  — block CRITICAL threats (default)
+ *   strict   — block HIGH + CRITICAL threats
+ *
+ * Based on hooks/guard-scanner/plugin.ts (TypeScript version for OpenClaw Plugin API)
+ * This module is the zero-dependency JavaScript equivalent for CLI and programmatic use.
+ *
+ * @author Guava 🍈 & Dee
+ * @version 3.4.0
+ * @license MIT
+ */
+declare const RUNTIME_CHECKS: {
+    id: string;
+    severity: string;
+    layer: number;
+    desc: string;
+    test: (s: any) => boolean;
+}[];
+/**
+ * Scan a tool call for runtime threats.
+ *
+ * @param {string} toolName - Name of the tool being called
+ * @param {object} params - Tool call parameters
+ * @param {object} [options] - Options
+ * @param {string} [options.mode] - Override mode ('monitor' | 'enforce' | 'strict')
+ * @param {boolean} [options.auditLog=true] - Enable audit logging
+ * @param {string} [options.sessionKey] - Session identifier for audit
+ * @param {string} [options.sessionId] - Ephemeral OpenClaw session UUID for audit
+ * @param {string} [options.runId] - Stable OpenClaw run identifier for audit
+ * @param {string} [options.toolCallId] - Provider tool call identifier for audit
+ * @param {string} [options.agentId] - Agent identifier for audit
+ * @param {object} [options.policy] - Session policy contract
+ * @returns {{ blocked: boolean, detections: Array<{id: string, severity: string, layer: number, desc: string, action: string}> }}
+ */
+declare function scanToolCall(toolName: any, params: any, options?: {}): {
+    blocked: boolean;
+    blockReason: null;
+    detections: never[];
+    mode: any;
+    toolName: any;
+    matchedPolicyId: null;
+    policyRationale: null;
+    riskAmplificationReasons: never[];
+    remediationSuggestion: null;
+    policyDecision: null;
+    contract_violations: never[];
+    behavioral_sequences: never[];
+};
+/**
+ * Get runtime check statistics.
+ * @returns {{ total: number, byLayer: object, bySeverity: object }}
+ */
+declare function getCheckStats(): {
+    total: number;
+    byLayer: {};
+    bySeverity: {};
+};
+declare const LAYER_NAMES: {
+    1: string;
+    2: string;
+    3: string;
+    4: string;
+    5: string;
+};
+
+/**
+ * guard-scanner v2.1.0 — Agent Skill Security Scanner 🛡️
+ *
+ * @security-manifest
+ *   env-read: []
+ *   env-write: []
+ *   network: none
+ *   fs-read: [scan target directory (user-specified)]
+ *   fs-write: [JSON/SARIF/HTML reports to scan directory]
+ *   exec: none
+ *   purpose: Static analysis of agent skill files for threat patterns
+ *
+ * Based on GuavaGuard v9.0.0 (OSS extraction)
+ * 20 threat categories • Snyk ToxicSkills + OWASP MCP Top 10
+ * Lightweight runtime footprint • CLI + JSON + SARIF + HTML output
+ * Plugin API for custom detection rules
+ *
+ * Born from a real 3-day agent identity hijack (2026-02-12)
+ *
+ * License: MIT
+ */
 
-declare const GuardScanner: GuardScannerConstructor;
 declare const VERSION: string;
-declare const THRESHOLDS: Record<string, unknown>;
-declare const SEVERITY_WEIGHTS: Record<string, number>;
-declare const scanToolCall: (toolName: string, params: Record<string, unknown> | string, options?: Record<string, unknown>) => RuntimeDecision;
-declare const RUNTIME_CHECKS: Record<string, unknown>[];
-declare const getCheckStats: () => RuntimeCheckStats;
-declare const LAYER_NAMES: Record<number, string>;
-declare const MCPServer: new () => unknown;
-declare const startServer: () => void;
-declare const TOOLS: Record<string, unknown>[];
+declare const THRESHOLDS: {
+    normal: {
+        suspicious: number;
+        malicious: number;
+    };
+    strict: {
+        suspicious: number;
+        malicious: number;
+    };
+};
+declare class GuardScanner {
+    constructor(options?: {});
+    loadPlugin(pluginPath: any): void;
+    loadCustomRules(rulesFile: any): void;
+    loadIgnoreFile(scanDir: any): void;
+    /**
+     * Scan raw text for threats (used for Discord incoming messages, etc.)
+     * @param {string} text - Raw text to scan
+     * @returns {{ safe: boolean, risk: number, detections: Array }}
+     */
+    scanText(text: any): {
+        safe: boolean;
+        risk: any;
+        detections: any[];
+    };
+    scanDirectory(dir: any): any;
+    scanTarget(targetPath: any): any;
+    scanSkill(skillPath: any, skillName: any): void;
+    classifyFile(ext: any, relFile: any): any;
+    isSelfNoisePath(skillName: any, relFile: any): any;
+    isSelfThreatCorpus(skillName: any, relFile: any): any;
+    checkIoCs(content: any, relFile: any, findings: any): void;
+    annotateV16Findings(findings: any): void;
+    pushUniqueFinding(findings: any, finding: any): void;
+    analyzeProtocolFindings(content: any, relFile: any, fileType: any, findings: any): void;
+    analyzeCognitiveFindings(content: any, relFile: any, fileType: any, findings: any): void;
+    analyzeThreatIntelFindings(content: any, relFile: any, fileType: any, findings: any): void;
+    checkPatterns(content: any, relFile: any, fileType: any, findings: any, patterns?: null): void;
+    checkHardcodedSecrets(content: any, relFile: any, findings: any): void;
+    shannonEntropy(str: any): number;
+    checkStructure(skillPath: any, skillName: any, findings: any): void;
+    checkDependencies(skillPath: any, skillName: any, findings: any): void;
+    checkSkillManifest(skillPath: any, skillName: any, findings: any): void;
+    checkComplexity(skillPath: any, skillName: any, findings: any): void;
+    checkConfigImpact(skillPath: any, skillName: any, findings: any): void;
+    checkHiddenFiles(skillPath: any, skillName: any, findings: any): void;
+    checkJSDataFlow(content: any, relFile: any, findings: any): void;
+    checkCrossFile(skillPath: any, skillName: any, findings: any): void;
+    checkRuntimeIntegration(skillPath: any, skillName: any, findings: any): void;
+    calculateRisk(findings: any): any;
+    getVerdict(risk: any): any;
+    getFiles(dir: any): any;
+    printSummary(): any;
+    toJSON(): any;
+    toSARIF(scanDir: any): any;
+    toHTML(): any;
+    /**
+     * Generate a Threat Model based on the scan findings.
+     * @param {Array<Object>} findings - The array of findings from the scan.
+     * @returns {Object} The generated threat model.
+     */
+    /**
+     * Check AST for contextual validation of high-risk chains.
+     * Separates heuristic-only matches from validated chains.
+     */
+    checkASTValidation(content: any, relFile: any, findings: any): any;
+    appendThreatModelFindings(content: any, findings: any, relFile?: string): void;
+    generateThreatModel(findings: any): {
+        timestamp: string;
+        surface: {
+            network: boolean;
+            file_system: boolean;
+            code_execution: boolean;
+            credential_exposure: boolean;
+            external_ingestion: boolean;
+            persistence: boolean;
+        };
+        capabilities: any;
+        compounded_risks: any;
+        lethal_trifecta: any;
+        summary: string;
+        owasp_asi: unknown[];
+        protocol_surfaces: unknown[];
+        layer_summary: {
+            layer: any;
+            layer_name: any;
+        }[];
+    };
+    generatePopulationMonitor(): any;
+    generateMetaGuard(): any;
+}
+
 declare function createScanner(options?: ScannerOptions): GuardScannerInstance;
 
-export { GuardScanner, GuardScannerConstructor, GuardScannerInstance, LAYER_NAMES, MCPServer, RUNTIME_CHECKS, RuntimeCheckStats, RuntimeDecision, SEVERITY_WEIGHTS, ScannerOptions, THRESHOLDS, TOOLS, VERSION, createScanner, getCheckStats, scanToolCall, startServer };
+export { GuardScanner, GuardScannerInstance, LAYER_NAMES, RUNTIME_CHECKS, SEVERITY_WEIGHTS, ScannerOptions, THRESHOLDS, VERSION, createScanner, getCheckStats, scanToolCall };