@guava-parity/guard-scanner 13.0.0 → 15.0.0

package/src/policy-engine.js

@@ -0,0 +1,32 @@
+class PolicyEngine {
+    constructor(config = { mode: 'enforce' }) {
+        this.mode = config.mode;
+    }
+
+    evaluate(toolName, args) {
+        if (this.mode === 'monitor') {
+            return { action: 'allow', reason: 'monitor mode' };
+        }
+
+        const argsStr = JSON.stringify(args).toLowerCase();
+
+        // Destructive FS operations
+        if (toolName === 'run_shell_command' && (argsStr.includes('rm -rf') || argsStr.includes('mkfs'))) {
+            return { action: 'block', reason: 'destructive fs operation' };
+        }
+
+        // Credential access
+        if (toolName === 'read_file' && (argsStr.includes('.env') || argsStr.includes('secret') || argsStr.includes('.aws'))) {
+            return { action: 'block', reason: 'credential read operation' };
+        }
+
+        // Unrestricted network
+        if (toolName === 'run_shell_command' && (argsStr.includes('curl') || argsStr.includes('wget')) && argsStr.includes('| bash')) {
+            return { action: 'block', reason: 'unrestricted network execution (curl|bash)' };
+        }
+
+        return { action: 'allow', reason: 'safe operation' };
+    }
+}
+
+module.exports = { PolicyEngine };

package/src/runtime-guard.js

@@ -33,6 +33,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { normalizeFinding } = require('./finding-schema.js');
 
 // ── Runtime threat patterns (26 checks, 5 layers) ──
 
@@ -85,6 +86,11 @@ const RUNTIME_CHECKS = [
         desc: 'Download piped to shell',
         test: (s) => /(curl|wget)\s+[^\n]*\|\s*(sh|bash|zsh)/i.test(s),
     },
+    {
+        id: 'RT_ENV_CURL_EXFIL', severity: 'CRITICAL', layer: 1,
+        desc: 'Environment variable exfiltration piped to curl upload',
+        test: (s) => /env\s*\|\s*curl\b[^\n]*-d\s+@-/i.test(s),
+    },
     {
         id: 'RT_SSH_READ', severity: 'HIGH', layer: 1,
         desc: 'SSH private key access',
@@ -247,6 +253,9 @@ function shouldBlock(severity, mode) {
  * @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
  * @returns {{ blocked: boolean, detections: Array<{id: string, severity: string, layer: number, desc: string, action: string}> }}
  */
@@ -254,6 +263,9 @@ function scanToolCall(toolName, params, options = {}) {
     const mode = options.mode || loadMode();
     const enableAudit = options.auditLog !== false;
     const sessionKey = options.sessionKey || 'unknown';
+    const sessionId = options.sessionId || 'unknown';
+    const runId = options.runId || 'unknown';
+    const toolCallId = options.toolCallId || 'unknown';
     const agentId = options.agentId || 'unknown';
 
     const result = {
@@ -275,14 +287,29 @@ function scanToolCall(toolName, params, options = {}) {
         if (!check.test(serialized)) continue;
 
         const action = shouldBlock(check.severity, mode) ? 'blocked' : 'warned';
+        const paramsPreview = serialized.length > 200 ? `${serialized.slice(0, 200)}…` : serialized;
 
-        const detection = {
+        const detection = normalizeFinding({
             id: check.id,
+            category: LAYER_CATEGORIES[check.layer] || 'runtime-guard',
             severity: check.severity,
             layer: check.layer,
             desc: check.desc,
             action,
-        };
+            rationale: check.rationale || `Runtime guard matched ${check.desc.toLowerCase()} before the tool call executed.`,
+            preconditions: check.preconditions || 'The tool call arguments must reach the runtime enforcement hook with attacker-controlled or unsafe content.',
+            false_positive_scenarios: check.falsePositiveScenarios || [
+                'The arguments are part of a security test, audit note, or documentation sample and are not actually executed.',
+                'The command is legitimate but still requires explicit human review before execution.',
+            ],
+            remediation_hint: check.remediationHint || 'Review the tool arguments, remove the unsafe construct, and rerun only after an allowlisted human review.',
+        }, {
+            source: 'runtime',
+            toolName,
+            paramsPreview,
+            layer_name: LAYER_NAMES[check.layer],
+            ruleMetadata: check,
+        });
 
         result.detections.push(detection);
 
@@ -296,6 +323,9 @@ function scanToolCall(toolName, params, options = {}) {
                 mode,
                 action,
                 session: sessionKey,
+                sessionId,
+                runId,
+                toolCallId,
                 agent: agentId,
             });
         }
@@ -332,6 +362,14 @@ const LAYER_NAMES = {
     5: 'Trust Exploitation (ASI09)',
 };
 
+const LAYER_CATEGORIES = {
+    1: 'threat-detection',
+    2: 'trust-defense',
+    3: 'safety-judge',
+    4: 'behavioral-guard',
+    5: 'trust-exploitation',
+};
+
 module.exports = {
     RUNTIME_CHECKS,
     DANGEROUS_TOOLS,

package/src/scanner.js

@@ -13,7 +13,7 @@
  *
  * Based on GuavaGuard v9.0.0 (OSS extraction)
  * 20 threat categories • Snyk ToxicSkills + OWASP MCP Top 10
- * Zero dependencies • CLI + JSON + SARIF + HTML output
+ * 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)
@@ -24,30 +24,24 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const crypto = require('crypto');
 
 const { PATTERNS } = require('./patterns.js');
 const { KNOWN_MALICIOUS } = require('./ioc-db.js');
-const { generateHTML } = require('./html-template.js');
+const { RuleRegistry } = require('./core/rule-registry.js');
+const { loadIgnoreFile, loadTextFile } = require('./core/content-loader.js');
+const { classifyFile, CODE_EXTENSIONS, BINARY_EXTENSIONS, isSelfNoisePath, isSelfThreatCorpus, getFiles, listSkills } = require('./core/inventory.js');
+const { calculateRisk, getVerdict, SEVERITY_WEIGHTS } = require('./core/risk-engine.js');
+const { applySemanticValidators, checkASTValidation } = require('./core/semantic-validators.js');
+const { toJSONReport, toSARIFReport, toHTMLReport, printSummary } = require('./core/report-adapters.js');
 
 // ===== CONFIGURATION =====
-const VERSION = '8.0.0';
+const { version: VERSION } = require('../package.json');
 
 const THRESHOLDS = {
     normal: { suspicious: 30, malicious: 80 },
     strict: { suspicious: 20, malicious: 60 },
 };
 
-// File classification
-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']);
-
-// Severity weights for risk scoring
-const SEVERITY_WEIGHTS = { CRITICAL: 40, HIGH: 15, MEDIUM: 5, LOW: 2 };
-
 class GuardScanner {
     constructor(options = {}) {
         this.verbose = options.verbose || false;
@@ -76,6 +70,8 @@ class GuardScanner {
         if (options.rulesFile) {
             this.loadCustomRules(options.rulesFile);
         }
+
+        this.ruleRegistry = new RuleRegistry(PATTERNS, this.customRules);
     }
 
     // Plugin API: load a plugin module
@@ -91,6 +87,7 @@ class GuardScanner {
                 if (!this.summaryOnly) {
                     console.log(`🔌 Plugin loaded: ${plugin.name || pluginPath} (${plugin.patterns.length} rule(s))`);
                 }
+                this.ruleRegistry = new RuleRegistry(PATTERNS, this.customRules);
             }
         } catch (e) {
             console.error(`⚠️  Failed to load plugin ${pluginPath}: ${e.message}`);
@@ -130,6 +127,7 @@ class GuardScanner {
             if (!this.summaryOnly && this.customRules.length > 0) {
                 console.log(`📏 Loaded ${this.customRules.length} custom rule(s) from ${rulesFile}`);
             }
+            this.ruleRegistry = new RuleRegistry(PATTERNS, this.customRules);
         } catch (e) {
             console.error(`⚠️  Failed to load custom rules: ${e.message}`);
         }
@@ -137,26 +135,11 @@ class GuardScanner {
 
     // Load .guava-guard-ignore / .guard-scanner-ignore from scan directory
     loadIgnoreFile(scanDir) {
-        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:')) {
-                    this.ignoredPatterns.add(trimmed.replace('pattern:', '').trim());
-                } else {
-                    this.ignoredSkills.add(trimmed);
-                }
-            }
-            if (this.verbose && (this.ignoredSkills.size || this.ignoredPatterns.size)) {
-                console.log(`📋 Loaded ignore file: ${this.ignoredSkills.size} skills, ${this.ignoredPatterns.size} patterns`);
-            }
-            break; // use first found
+        const ignored = loadIgnoreFile(scanDir);
+        this.ignoredSkills = ignored.ignoredSkills;
+        this.ignoredPatterns = ignored.ignoredPatterns;
+        if (this.verbose && (this.ignoredSkills.size || this.ignoredPatterns.size)) {
+            console.log(`📋 Loaded ignore file: ${this.ignoredSkills.size} skills, ${this.ignoredPatterns.size} patterns`);
         }
     }
 
@@ -172,6 +155,7 @@ class GuardScanner {
         if (this.customRules.length > 0) {
             this.checkPatterns(text, 'raw_text', 'code', findings, this.customRules);
         }
+        applySemanticValidators(text, 'raw_text', findings);
         
         // Filter ignored patterns
         const filteredFindings = findings.filter(f => !this.ignoredPatterns.has(f.id));
@@ -186,16 +170,12 @@ class GuardScanner {
 
     scanDirectory(dir) {
         if (!fs.existsSync(dir)) {
-            console.error(`❌ Directory not found: ${dir}`);
-            process.exit(2);
+            throw new Error(`Directory not found: ${dir}`);
         }
 
         this.loadIgnoreFile(dir);
 
-        const skills = fs.readdirSync(dir).filter(f => {
-            const p = path.join(dir, f);
-            return fs.statSync(p).isDirectory();
-        });
+        const skills = listSkills(dir);
 
         if (!this.quiet) {
             console.log(`\n🛡️  guard-scanner v${VERSION}`);
@@ -228,6 +208,13 @@ class GuardScanner {
         return this.findings;
     }
 
+    scanTarget(targetPath) {
+        this.findings = [];
+        this.stats = { scanned: 0, clean: 0, low: 0, suspicious: 0, malicious: 0 };
+        this.scanDirectory(targetPath);
+        return this.toJSON();
+    }
+
     scanSkill(skillPath, skillName) {
         this.stats.scanned++;
         const skillFindings = [];
@@ -252,9 +239,8 @@ class GuardScanner {
             if (BINARY_EXTENSIONS.has(ext)) continue;
             if (this.isSelfNoisePath(skillName, relFile)) continue;
 
-            let content;
-            try { content = fs.readFileSync(file, 'utf-8'); } catch { continue; }
-            if (content.length > 500000) continue;
+            const content = loadTextFile(file);
+            if (content === null) continue;
 
             const fileType = this.classifyFile(ext, relFile);
 
@@ -284,6 +270,7 @@ class GuardScanner {
             if ((ext === '.js' || ext === '.mjs' || ext === '.cjs' || ext === '.ts') && content.length < 200000) {
                 this.checkJSDataFlow(content, relFile, skillFindings);
             }
+            applySemanticValidators(content, relFile, skillFindings);
         }
 
         // Check 3: Structural checks
@@ -344,27 +331,15 @@ class GuardScanner {
     }
 
     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';
+        return classifyFile(ext, relFile);
     }
 
     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';
+        return isSelfNoisePath(skillName, relFile);
     }
 
     isSelfThreatCorpus(skillName, relFile) {
-        if (skillName !== 'guard-scanner') return false;
-        return /(^|\/)(ioc-db|patterns)\.(js|ts)$/.test(relFile);
+        return isSelfThreatCorpus(skillName, relFile);
     }
 
     checkIoCs(content, relFile, findings) {
@@ -402,7 +377,8 @@ class GuardScanner {
         }
     }
 
-    checkPatterns(content, relFile, fileType, findings, patterns = PATTERNS) {
+    checkPatterns(content, relFile, fileType, findings, patterns = null) {
+        const activePatterns = patterns || this.ruleRegistry.getRulesForFileType(fileType);
         // v9: Payload Unfurling (Base64 / Hex Decoders)
         let unfurledContent = content;
 
@@ -420,12 +396,12 @@ class GuardScanner {
             return String.fromCharCode(parseInt(hex, 16));
         });
 
-        for (const pattern of patterns) {
+        for (const pattern of activePatterns) {
             // Soul Lock: skip identity-hijack/memory-poisoning patterns unless --soul-lock is enabled
             if (pattern.soulLock && !this.soulLock) continue;
             if (pattern.codeOnly && fileType !== 'code') continue;
             if (pattern.docOnly && fileType !== 'doc' && fileType !== 'skill-doc') continue;
-            if (!pattern.all && !pattern.codeOnly && !pattern.docOnly) continue;
+            if (!pattern.all && !pattern.codeOnly && !pattern.docOnly && pattern.scope !== 'skill-doc') continue;
 
             pattern.regex.lastIndex = 0;
             let matches = content.match(pattern.regex);
@@ -453,8 +429,8 @@ class GuardScanner {
             findings.push({
                 severity: adjustedSeverity,
                 id: pattern.id,
-                cat: pattern.cat,
-                desc: pattern.desc,
+                cat: pattern.cat || pattern.category,
+                desc: pattern.desc || pattern.description,
                 file: relFile,
                 line: lineNum,
                 matchCount: matches.length,
@@ -975,181 +951,90 @@ class GuardScanner {
     }
 
     calculateRisk(findings) {
-        if (findings.length === 0) return 0;
-
-        let score = 0;
-        for (const f of findings) {
-            score += SEVERITY_WEIGHTS[f.severity] || 0;
-        }
-
-        const ids = new Set(findings.map(f => f.id));
-        const cats = new Set(findings.map(f => f.cat));
-
-        if (cats.has('credential-handling') && cats.has('exfiltration')) score = Math.round(score * 2);
-        if (cats.has('credential-handling') && findings.some(f => f.id === 'MAL_CHILD' || f.id === 'MAL_EXEC')) score = Math.round(score * 1.5);
-        if (cats.has('obfuscation') && (cats.has('malicious-code') || cats.has('credential-handling'))) score = Math.round(score * 2);
-        if (ids.has('DEP_LIFECYCLE_EXEC')) score = Math.round(score * 2);
-        if (ids.has('PI_BIDI') && findings.length > 1) score = Math.round(score * 1.5);
-        if (cats.has('leaky-skills') && (cats.has('exfiltration') || cats.has('malicious-code'))) score = Math.round(score * 2);
-        if (cats.has('memory-poisoning')) score = Math.round(score * 1.5);
-        if (cats.has('prompt-worm')) score = Math.round(score * 2);
-        if (cats.has('cve-patterns')) score = Math.max(score, 70);
-        if (cats.has('persistence') && (cats.has('malicious-code') || cats.has('credential-handling') || cats.has('memory-poisoning'))) score = Math.round(score * 1.5);
-        if (cats.has('identity-hijack')) score = Math.round(score * 2);
-        if (cats.has('identity-hijack') && (cats.has('persistence') || cats.has('memory-poisoning'))) score = Math.max(score, 90);
-        if (ids.has('IOC_IP') || ids.has('IOC_URL') || ids.has('KNOWN_TYPOSQUAT')) score = 100;
-
-        // v1.1 categories
-        if (cats.has('config-impact')) score = Math.round(score * 2);
-        if (cats.has('config-impact') && cats.has('sandbox-validation')) score = Math.max(score, 70);
-        if (cats.has('complexity') && (cats.has('malicious-code') || cats.has('obfuscation'))) score = Math.round(score * 1.5);
-
-        // v2.1 PII exposure amplifiers
-        if (cats.has('pii-exposure') && cats.has('exfiltration')) score = Math.round(score * 3);
-        if (cats.has('pii-exposure') && (ids.has('SHADOW_AI_OPENAI') || ids.has('SHADOW_AI_ANTHROPIC') || ids.has('SHADOW_AI_GENERIC'))) score = Math.round(score * 2.5);
-        if (cats.has('pii-exposure') && cats.has('credential-handling')) score = Math.round(score * 2);
-
-        return Math.min(100, score);
+        return calculateRisk(findings);
     }
 
     getVerdict(risk) {
-        if (risk >= this.thresholds.malicious) return { icon: '🔴', label: 'MALICIOUS', stat: 'malicious' };
-        if (risk >= this.thresholds.suspicious) return { icon: '🟡', label: 'SUSPICIOUS', stat: 'suspicious' };
-        if (risk > 0) return { icon: '🟢', label: 'LOW RISK', stat: 'low' };
-        return { icon: '🟢', label: 'CLEAN', stat: 'clean' };
+        return getVerdict(risk, this.thresholds);
     }
 
     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(...this.getFiles(fullPath));
-                } else {
-                    const baseName = entry.name.toLowerCase();
-                    if (GENERATED_REPORT_FILES.has(baseName)) continue;
-                    results.push(fullPath);
-                }
-            }
-        } catch { }
-        return results;
+        return getFiles(dir);
     }
 
     printSummary() {
-        const total = this.stats.scanned;
-        const safe = this.stats.clean + this.stats.low;
-        console.log(`\n${'═'.repeat(54)}`);
-        console.log(`📊 guard-scanner v${VERSION} Scan Summary`);
-        console.log(`${'─'.repeat(54)}`);
-        console.log(`   Scanned:      ${total}`);
-        console.log(`   🟢 Clean:       ${this.stats.clean}`);
-        console.log(`   🟢 Low Risk:    ${this.stats.low}`);
-        console.log(`   🟡 Suspicious:  ${this.stats.suspicious}`);
-        console.log(`   🔴 Malicious:   ${this.stats.malicious}`);
-        console.log(`   Safety Rate:  ${total ? Math.round(safe / total * 100) : 0}%`);
-        console.log(`${'═'.repeat(54)}`);
-
-        if (this.stats.malicious > 0) {
-            console.log(`\n⚠️  CRITICAL: ${this.stats.malicious} malicious skill(s) detected!`);
-            console.log(`   Review findings with --verbose and remove if confirmed.`);
-        } else if (this.stats.suspicious > 0) {
-            console.log(`\n⚡ ${this.stats.suspicious} suspicious skill(s) found — review recommended.`);
-        } else {
-            console.log(`\n✅ All clear! No threats detected.`);
-        }
+        return printSummary(this.stats, VERSION);
     }
 
     toJSON() {
-        const recommendations = [];
-        for (const skillResult of this.findings) {
-            const skillRecs = [];
-            const cats = new Set(skillResult.findings.map(f => f.cat));
-
-            if (cats.has('prompt-injection')) skillRecs.push('🛑 Contains prompt injection patterns.');
-            if (cats.has('malicious-code')) skillRecs.push('🛑 Contains potentially malicious code.');
-            if (cats.has('credential-handling') && cats.has('exfiltration')) skillRecs.push('💀 CRITICAL: Credential access + exfiltration. DO NOT INSTALL.');
-            if (cats.has('dependency-chain')) skillRecs.push('📦 Suspicious dependency chain.');
-            if (cats.has('obfuscation')) skillRecs.push('🔍 Code obfuscation detected.');
-            if (cats.has('secret-detection')) skillRecs.push('🔑 Possible hardcoded secrets.');
-            if (cats.has('leaky-skills')) skillRecs.push('💧 LEAKY SKILL: Secrets pass through LLM context.');
-            if (cats.has('memory-poisoning')) skillRecs.push('🧠 MEMORY POISONING: Agent memory modification attempt.');
-            if (cats.has('prompt-worm')) skillRecs.push('🪱 PROMPT WORM: Self-replicating instructions.');
-            if (cats.has('data-flow')) skillRecs.push('🔀 Suspicious data flow patterns.');
-            if (cats.has('persistence')) skillRecs.push('⏰ PERSISTENCE: Creates scheduled tasks.');
-            if (cats.has('cve-patterns')) skillRecs.push('🚨 CVE PATTERN: Matches known exploits.');
-            if (cats.has('identity-hijack')) skillRecs.push('🔒 IDENTITY HIJACK: Agent soul file tampering. DO NOT INSTALL.');
-            if (cats.has('sandbox-validation')) skillRecs.push('🔒 SANDBOX: Skill requests dangerous capabilities.');
-            if (cats.has('complexity')) skillRecs.push('🧩 COMPLEXITY: Excessive code complexity may hide malicious behavior.');
-            if (cats.has('config-impact')) skillRecs.push('⚙️ CONFIG IMPACT: Modifies OpenClaw configuration. DO NOT INSTALL.');
-            if (cats.has('pii-exposure')) skillRecs.push('🆔 PII EXPOSURE: Handles personally identifiable information. Review data handling.');
-
-            if (skillRecs.length > 0) recommendations.push({ skill: skillResult.skill, actions: skillRecs });
-        }
-
-        return {
-            timestamp: new Date().toISOString(),
-            scanner: `guard-scanner v${VERSION}`,
-            mode: this.strict ? 'strict' : 'normal',
-            stats: this.stats,
-            thresholds: this.thresholds,
-            findings: this.findings,
-            recommendations,
-            iocVersion: '2026-02-12',
-        };
+        return toJSONReport(this, VERSION);
     }
 
     toSARIF(scanDir) {
-        const rules = [];
-        const ruleIndex = {};
-        const results = [];
-
-        for (const skillResult of this.findings) {
-            for (const f of skillResult.findings) {
-                if (!ruleIndex[f.id]) {
-                    ruleIndex[f.id] = rules.length;
-                    rules.push({
-                        id: f.id, name: f.id,
-                        shortDescription: { text: f.desc },
-                        defaultConfiguration: { level: f.severity === 'CRITICAL' ? 'error' : f.severity === 'HIGH' ? 'error' : f.severity === 'MEDIUM' ? 'warning' : 'note' },
-                        properties: { tags: ['security', f.cat], 'security-severity': f.severity === 'CRITICAL' ? '9.0' : f.severity === 'HIGH' ? '7.0' : f.severity === 'MEDIUM' ? '4.0' : '1.0' }
-                    });
-                }
-                const normalizedFile = String(f.file || '')
-                    .replaceAll('\\', '/')
-                    .replace(/^\/+/, '');
-                const artifactUri = `${skillResult.skill}/${normalizedFile}`;
-                const fingerprintSeed = `${f.id}|${artifactUri}|${f.line || 0}|${(f.sample || '').slice(0, 200)}`;
-                const lineHash = crypto.createHash('sha256').update(fingerprintSeed).digest('hex').slice(0, 24);
-
-                results.push({
-                    ruleId: f.id, ruleIndex: ruleIndex[f.id],
-                    level: f.severity === 'CRITICAL' ? 'error' : f.severity === 'HIGH' ? 'error' : f.severity === 'MEDIUM' ? 'warning' : 'note',
-                    message: { text: `[${skillResult.skill}] ${f.desc}${f.sample ? ` — "${f.sample}"` : ''}` },
-                    partialFingerprints: {
-                        primaryLocationLineHash: lineHash
-                    },
-                    locations: [{ physicalLocation: { artifactLocation: { uri: artifactUri, uriBaseId: '%SRCROOT%' }, region: f.line ? { startLine: f.line } : undefined } }]
-                });
+        return toSARIFReport(this, VERSION, scanDir);
+    }
+
+    toHTML() {
+        return toHTMLReport(this, VERSION);
+    }
+
+    /**
+     * 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, relFile, findings) {
+        return checkASTValidation(content, relFile, findings);
+    }
+
+    generateThreatModel(findings) {
+        const surface = {
+            network: false,
+            file_system: false,
+            code_execution: false,
+            credential_exposure: false,
+            external_ingestion: false,
+            persistence: false
+        };
+
+        for (const f of findings) {
+            // Map pattern IDs or categories to capability surfaces
+            const id = f.id || '';
+            const cat = f.cat || '';
+            const desc = (f.desc || '').toLowerCase();
+            
+            if (id.includes('FETCH') || id.includes('CURL') || id.includes('SSRF') || id.includes('NETWORK') || id.includes('EXFIL') || id.includes('TRUST_WEB_EXEC') || desc.includes('fetch') || desc.includes('network') || desc.includes('web content')) {
+                surface.network = true;
+            }
+            if (id.includes('FS_') || id.includes('WRITE') || id.includes('READ') || id.includes('FILE') || id.includes('TRUST_WEB_EXEC') || desc.includes('file system') || desc.includes('readfilesync') || desc.includes('fs.read')) {
+                surface.file_system = true;
+            }
+            if (id.includes('EXEC') || id.includes('EVAL') || id.includes('SHELL') || id.includes('SPAWN') || id.includes('RCE') || desc.includes('exec') || desc.includes('shell')) {
+                surface.code_execution = true;
+            }
+            if (id.includes('CRED') || id.includes('KEY') || id.includes('SECRET') || id.includes('TOKEN') || cat.includes('credential') || desc.includes('credential') || desc.includes('trust boundary')) {
+                surface.credential_exposure = true;
+            }
+            if (id.includes('PI_') || id.includes('PROMPT_INJECT') || id.includes('POISON') || id.includes('TRUST_WEB_EXEC') || cat.includes('prompt-injection') || desc.includes('ignore all')) {
+                surface.external_ingestion = true;
+            }
+            if (id.includes('PERSIST') || id.includes('CRON') || id.includes('STARTUP') || cat.includes('persistence') || desc.includes('cron') || id.includes('DEPS_PHANTOM_IMPORT')) {
+                surface.persistence = true;
             }
         }
 
         return {
-            version: '2.1.0',
-            $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
-            runs: [{
-                tool: { driver: { name: 'guard-scanner', version: VERSION, informationUri: 'https://github.com/koatora20/guard-scanner', rules } },
-                results,
-                invocations: [{ executionSuccessful: true, endTimeUtc: new Date().toISOString() }]
-            }]
+            timestamp: new Date().toISOString(),
+            surface,
+            summary: Object.keys(surface).filter(k => surface[k]).join(', ') || 'none'
         };
     }
 
-    toHTML() {
-        return generateHTML(VERSION, this.stats, this.findings);
-    }
 }
 
 const { scanToolCall, RUNTIME_CHECKS, getCheckStats, LAYER_NAMES } = require('./runtime-guard.js');