hackmyagent 0.11.7 → 0.11.9

package/dist/hardening/scanner.js

@@ -111,6 +111,19 @@ const CHECK_PROJECT_TYPES = {
     'AITOOL-': ['all'], // AI tooling exposure (Jupyter, Gradio, etc.)
     'A2A-': ['all'], // A2A protocol exposure
     'WEBCRED-': ['all'], // Credentials in web-served files
+    // Code injection and supply chain checks
+    'CODEINJ-': ['all'], // Code injection via exec with interpolation
+    'INSTALL-': ['all'], // Unsafe install scripts (curl|sh)
+    'CLIPASS-': ['all'], // Credentials passed as CLI arguments
+    'INTEGRITY-': ['all'], // Integrity check bypass
+    'TOCTOU-': ['all'], // Time-of-check-time-of-use race conditions
+    'TMPPATH-': ['all'], // Hardcoded /tmp path attacks
+    'DOCKERINJ-': ['all'], // Docker exec with variable injection
+    'ENVLEAK-': ['all'], // Environment variable leakage to child processes
+    'SANDBOX-005': ['openclaw', 'mcp'], // Messaging API pre-allowed in sandbox
+    'WEBEXPOSE-': ['all'], // Sensitive files in web-served directories
+    'AGENT-CRED-': ['all'], // Missing credential protection in system prompts
+    'SOUL-OVERRIDE-': ['all'], // Skill content overriding SOUL.md
 };
 // Patterns for detecting exposed credentials
 // Each pattern is carefully tuned to minimize false positives
@@ -273,6 +286,10 @@ class HardeningScanner {
     async scan(options) {
         const { targetDir, autoFix = false, dryRun = false, ignore = [], cliName = 'hackmyagent' } = options;
         this.cliName = cliName;
+        // Resolve effective scan depth — --deep flag implies 'deep' depth
+        const scanDepth = options.scanDepth || (options.deep ? 'deep' : 'standard');
+        const isQuick = scanDepth === 'quick';
+        const isDeepScan = scanDepth === 'deep';
         // Load .hmaignore for path-based exclusions
         const hmaIgnorePaths = await this.loadHmaIgnore(targetDir);
         // Merge with any programmatic ignorePaths
@@ -311,150 +328,179 @@ class HardeningScanner {
         // Network security checks
         const netFindings = await this.checkNetworkSecurity(targetDir, shouldFix);
         findings.push(...netFindings);
-        // Additional MCP checks
-        const mcpAdvFindings = await this.checkMcpAdvanced(targetDir, shouldFix);
-        findings.push(...mcpAdvFindings);
-        // Claude Code advanced checks
-        const claudeAdvFindings = await this.checkClaudeAdvanced(targetDir, shouldFix);
-        findings.push(...claudeAdvFindings);
-        // Cursor configuration checks
-        const cursorFindings = await this.checkCursorConfig(targetDir, shouldFix);
-        findings.push(...cursorFindings);
-        // VSCode configuration checks
-        const vscodeFindings = await this.checkVscodeConfig(targetDir, shouldFix);
-        findings.push(...vscodeFindings);
-        // Additional credential checks
-        const credAdvFindings = await this.checkCredentialsAdvanced(targetDir, shouldFix);
-        findings.push(...credAdvFindings);
-        // Additional permission checks
-        const permAdvFindings = await this.checkPermissionsAdvanced(targetDir, shouldFix);
-        findings.push(...permAdvFindings);
-        // Environment and config checks
-        const envFindings = await this.checkEnvironmentSecurity(targetDir, shouldFix);
-        findings.push(...envFindings);
-        // Logging and audit checks
-        const logFindings = await this.checkLoggingSecurity(targetDir, shouldFix);
-        findings.push(...logFindings);
-        // Dependency checks
-        const depFindings = await this.checkDependencySecurity(targetDir, shouldFix);
-        findings.push(...depFindings);
-        // Session and auth checks
-        const authFindings = await this.checkAuthSecurity(targetDir, shouldFix);
-        findings.push(...authFindings);
-        // Process and runtime checks
-        const procFindings = await this.checkProcessSecurity(targetDir, shouldFix);
-        findings.push(...procFindings);
-        // Additional Claude checks
-        const claude3Findings = await this.checkClaudeExtended(targetDir, shouldFix);
-        findings.push(...claude3Findings);
-        // Additional MCP checks
-        const mcp2Findings = await this.checkMcpExtended(targetDir, shouldFix);
-        findings.push(...mcp2Findings);
-        // Additional network checks
-        const net2Findings = await this.checkNetworkExtended(targetDir, shouldFix);
-        findings.push(...net2Findings);
-        // Input/output security checks
-        const ioFindings = await this.checkIOSecurity(targetDir, shouldFix);
-        findings.push(...ioFindings);
-        // API security checks
-        const apiFindings = await this.checkAPISecurity(targetDir, shouldFix);
-        findings.push(...apiFindings);
-        // Secret management checks
-        const secretFindings = await this.checkSecretManagement(targetDir, shouldFix);
-        findings.push(...secretFindings);
-        // Prompt injection defense checks
-        const promptFindings = await this.checkPromptSecurity(targetDir, shouldFix);
-        findings.push(...promptFindings);
-        // Input validation checks
-        const injFindings = await this.checkInputValidation(targetDir, shouldFix);
-        findings.push(...injFindings);
-        // Rate limiting checks
-        const rateFindings = await this.checkRateLimiting(targetDir, shouldFix);
-        findings.push(...rateFindings);
-        // Session security checks
-        const sessionFindings = await this.checkSessionSecurity(targetDir, shouldFix);
-        findings.push(...sessionFindings);
-        // Encryption checks
-        const encryptFindings = await this.checkEncryption(targetDir, shouldFix);
-        findings.push(...encryptFindings);
-        // Audit trail checks
-        const auditFindings = await this.checkAuditTrail(targetDir, shouldFix);
-        findings.push(...auditFindings);
-        // Sandboxing checks
-        const sandboxFindings = await this.checkSandboxing(targetDir, shouldFix);
-        findings.push(...sandboxFindings);
-        // Tool boundary checks
-        const toolFindings = await this.checkToolBoundaries(targetDir, shouldFix);
-        findings.push(...toolFindings);
-        // OpenClaw skill checks
-        const skillFindings = await this.checkOpenclawSkills(targetDir, shouldFix);
-        findings.push(...skillFindings);
-        // OpenClaw heartbeat checks
-        const heartbeatFindings = await this.checkOpenclawHeartbeat(targetDir, shouldFix);
-        findings.push(...heartbeatFindings);
-        // OpenClaw gateway checks
-        const gatewayFindings = await this.checkOpenclawGateway(targetDir, shouldFix);
-        findings.push(...gatewayFindings);
-        // OpenClaw config checks
-        const configFindings = await this.checkOpenclawConfig(targetDir, shouldFix);
-        findings.push(...configFindings);
-        // OpenClaw supply chain checks
-        const supplyFindings = await this.checkOpenclawSupplyChain(targetDir, shouldFix);
-        findings.push(...supplyFindings);
-        // OpenClaw CVE-specific checks
-        const cveFindings = await this.checkOpenclawCVE(targetDir, shouldFix);
-        findings.push(...cveFindings);
-        // Unicode steganography checks (GlassWorm detection)
-        const unicodeStegoFindings = await this.checkUnicodeSteganography(targetDir, shouldFix);
-        findings.push(...unicodeStegoFindings);
-        // Memory/context poisoning checks
-        const memFindings = await this.checkMemoryPoisoning(targetDir, shouldFix);
-        findings.push(...memFindings);
-        // RAG poisoning checks
-        const ragFindings = await this.checkRAGPoisoning(targetDir, shouldFix);
-        findings.push(...ragFindings);
-        // Agent identity checks
-        const aimFindings = await this.checkAgentIdentity(targetDir, shouldFix);
-        findings.push(...aimFindings);
-        // Agent DNA integrity checks
-        const dnaFindings = await this.checkAgentDNA(targetDir, shouldFix);
-        findings.push(...dnaFindings);
-        // Skill memory manipulation checks
-        const skillMemFindings = await this.checkSkillMemory(targetDir, shouldFix);
-        findings.push(...skillMemFindings);
-        // NemoClaw codebase pattern checks
-        const nemoFindings = await this.checkNemoClawPatterns(targetDir, shouldFix);
-        findings.push(...nemoFindings);
-        // AI infrastructure exposure checks (research gap coverage)
-        const llmFindings = await this.checkLLMExposure(targetDir, shouldFix);
-        findings.push(...llmFindings);
-        const aiToolFindings = await this.checkAIToolExposure(targetDir, shouldFix);
-        findings.push(...aiToolFindings);
-        const a2aFindings = await this.checkA2AExposure(targetDir, shouldFix);
-        findings.push(...a2aFindings);
-        const mcpDiscoveryFindings = await this.checkMCPDiscovery(targetDir, shouldFix);
-        findings.push(...mcpDiscoveryFindings);
-        const webCredFindings = await this.checkWebServedCredentials(targetDir, shouldFix);
-        findings.push(...webCredFindings);
+        // --- Standard and Deep checks (skipped in quick mode) ---
+        if (!isQuick) {
+            // Additional MCP checks
+            const mcpAdvFindings = await this.checkMcpAdvanced(targetDir, shouldFix);
+            findings.push(...mcpAdvFindings);
+            // Claude Code advanced checks
+            const claudeAdvFindings = await this.checkClaudeAdvanced(targetDir, shouldFix);
+            findings.push(...claudeAdvFindings);
+            // Cursor configuration checks
+            const cursorFindings = await this.checkCursorConfig(targetDir, shouldFix);
+            findings.push(...cursorFindings);
+            // VSCode configuration checks
+            const vscodeFindings = await this.checkVscodeConfig(targetDir, shouldFix);
+            findings.push(...vscodeFindings);
+            // Additional credential checks
+            const credAdvFindings = await this.checkCredentialsAdvanced(targetDir, shouldFix);
+            findings.push(...credAdvFindings);
+            // Additional permission checks
+            const permAdvFindings = await this.checkPermissionsAdvanced(targetDir, shouldFix);
+            findings.push(...permAdvFindings);
+            // Environment and config checks
+            const envFindings = await this.checkEnvironmentSecurity(targetDir, shouldFix);
+            findings.push(...envFindings);
+            // Logging and audit checks
+            const logFindings = await this.checkLoggingSecurity(targetDir, shouldFix);
+            findings.push(...logFindings);
+            // Dependency checks
+            const depFindings = await this.checkDependencySecurity(targetDir, shouldFix);
+            findings.push(...depFindings);
+            // Session and auth checks
+            const authFindings = await this.checkAuthSecurity(targetDir, shouldFix);
+            findings.push(...authFindings);
+            // Process and runtime checks
+            const procFindings = await this.checkProcessSecurity(targetDir, shouldFix);
+            findings.push(...procFindings);
+            // Additional Claude checks
+            const claude3Findings = await this.checkClaudeExtended(targetDir, shouldFix);
+            findings.push(...claude3Findings);
+            // Additional MCP checks
+            const mcp2Findings = await this.checkMcpExtended(targetDir, shouldFix);
+            findings.push(...mcp2Findings);
+            // Additional network checks
+            const net2Findings = await this.checkNetworkExtended(targetDir, shouldFix);
+            findings.push(...net2Findings);
+            // Input/output security checks
+            const ioFindings = await this.checkIOSecurity(targetDir, shouldFix);
+            findings.push(...ioFindings);
+            // API security checks
+            const apiFindings = await this.checkAPISecurity(targetDir, shouldFix);
+            findings.push(...apiFindings);
+            // Secret management checks
+            const secretFindings = await this.checkSecretManagement(targetDir, shouldFix);
+            findings.push(...secretFindings);
+            // Prompt injection defense checks
+            const promptFindings = await this.checkPromptSecurity(targetDir, shouldFix);
+            findings.push(...promptFindings);
+            // Input validation checks
+            const injFindings = await this.checkInputValidation(targetDir, shouldFix);
+            findings.push(...injFindings);
+            // Rate limiting checks
+            const rateFindings = await this.checkRateLimiting(targetDir, shouldFix);
+            findings.push(...rateFindings);
+            // Session security checks
+            const sessionFindings = await this.checkSessionSecurity(targetDir, shouldFix);
+            findings.push(...sessionFindings);
+            // Encryption checks
+            const encryptFindings = await this.checkEncryption(targetDir, shouldFix);
+            findings.push(...encryptFindings);
+            // Audit trail checks
+            const auditFindings = await this.checkAuditTrail(targetDir, shouldFix);
+            findings.push(...auditFindings);
+            // Sandboxing checks
+            const sandboxFindings = await this.checkSandboxing(targetDir, shouldFix);
+            findings.push(...sandboxFindings);
+            // Tool boundary checks
+            const toolFindings = await this.checkToolBoundaries(targetDir, shouldFix);
+            findings.push(...toolFindings);
+            // OpenClaw skill checks
+            const skillFindings = await this.checkOpenclawSkills(targetDir, shouldFix);
+            findings.push(...skillFindings);
+            // OpenClaw heartbeat checks
+            const heartbeatFindings = await this.checkOpenclawHeartbeat(targetDir, shouldFix);
+            findings.push(...heartbeatFindings);
+            // OpenClaw gateway checks
+            const gatewayFindings = await this.checkOpenclawGateway(targetDir, shouldFix);
+            findings.push(...gatewayFindings);
+            // OpenClaw config checks
+            const configFindings = await this.checkOpenclawConfig(targetDir, shouldFix);
+            findings.push(...configFindings);
+            // OpenClaw supply chain checks
+            const supplyFindings = await this.checkOpenclawSupplyChain(targetDir, shouldFix);
+            findings.push(...supplyFindings);
+            // OpenClaw CVE-specific checks
+            const cveFindings = await this.checkOpenclawCVE(targetDir, shouldFix);
+            findings.push(...cveFindings);
+            // Unicode steganography checks (GlassWorm detection)
+            const unicodeStegoFindings = await this.checkUnicodeSteganography(targetDir, shouldFix);
+            findings.push(...unicodeStegoFindings);
+            // Memory/context poisoning checks
+            const memFindings = await this.checkMemoryPoisoning(targetDir, shouldFix);
+            findings.push(...memFindings);
+            // RAG poisoning checks
+            const ragFindings = await this.checkRAGPoisoning(targetDir, shouldFix);
+            findings.push(...ragFindings);
+            // Agent identity checks
+            const aimFindings = await this.checkAgentIdentity(targetDir, shouldFix);
+            findings.push(...aimFindings);
+            // Agent DNA integrity checks
+            const dnaFindings = await this.checkAgentDNA(targetDir, shouldFix);
+            findings.push(...dnaFindings);
+            // Skill memory manipulation checks
+            const skillMemFindings = await this.checkSkillMemory(targetDir, shouldFix);
+            findings.push(...skillMemFindings);
+            // NemoClaw codebase pattern checks
+            const nemoFindings = await this.checkNemoClawPatterns(targetDir, shouldFix);
+            findings.push(...nemoFindings);
+            // AI infrastructure exposure checks (research gap coverage)
+            const llmFindings = await this.checkLLMExposure(targetDir, shouldFix);
+            findings.push(...llmFindings);
+            const aiToolFindings = await this.checkAIToolExposure(targetDir, shouldFix);
+            findings.push(...aiToolFindings);
+            const a2aFindings = await this.checkA2AExposure(targetDir, shouldFix);
+            findings.push(...a2aFindings);
+            const mcpDiscoveryFindings = await this.checkMCPDiscovery(targetDir, shouldFix);
+            findings.push(...mcpDiscoveryFindings);
+            const webCredFindings = await this.checkWebServedCredentials(targetDir, shouldFix);
+            findings.push(...webCredFindings);
+            // Code injection, supply chain, and operational security checks
+            // NOTE: CODEINJ-001 removed — deduplicated with NEMO-005 (same detection)
+            const installFindings = await this.checkInstallScripts(targetDir, shouldFix);
+            findings.push(...installFindings);
+            const cliPassFindings = await this.checkCLICredentialPassthrough(targetDir, shouldFix);
+            findings.push(...cliPassFindings);
+            const integrityFindings = await this.checkIntegrityBypass(targetDir, shouldFix);
+            findings.push(...integrityFindings);
+            const toctouFindings = await this.checkTOCTOU(targetDir, shouldFix);
+            findings.push(...toctouFindings);
+            // NOTE: TMPPATH-001 removed — deduplicated with NEMO-006 (same detection)
+            const dockerInjFindings = await this.checkDockerInjection(targetDir, shouldFix);
+            findings.push(...dockerInjFindings);
+            // NOTE: ENVLEAK-001 removed — deduplicated with NEMO-007 (same detection)
+            const sandboxMsgFindings = await this.checkSandboxMessaging(targetDir, shouldFix);
+            findings.push(...sandboxMsgFindings);
+            const webExposeFindings = await this.checkWebExposedFiles(targetDir, shouldFix);
+            findings.push(...webExposeFindings);
+            const soulOverrideFindings = await this.checkSoulOverride(targetDir, shouldFix);
+            findings.push(...soulOverrideFindings);
+            const memSanitizeFindings = await this.checkMemoryStoreSanitization(targetDir, shouldFix);
+            findings.push(...memSanitizeFindings);
+            const agentCredFindings = await this.checkAgentCredentialProtection(targetDir, shouldFix);
+            findings.push(...agentCredFindings);
+        } // end of standard/deep checks
         // Enrich findings with attack taxonomy mapping
         (0, taxonomy_1.enrichWithTaxonomy)(findings);
-        // Layer 2: Structural analysis (always on)
+        // Layer 2: Structural analysis (standard and deep only)
         let layer2Count = 0;
         let layer3Count = 0;
         let llmCost;
         let cachedResults;
-        try {
-            const structural = new semantic_1.StructuralAnalyzer();
-            const structuralFindings = await structural.analyze(targetDir);
-            const converted = (0, semantic_1.toSecurityFindings)(structuralFindings);
-            findings.push(...converted);
-            layer2Count = converted.length;
-        }
-        catch {
-            // Structural analysis failure is non-fatal
+        if (!isQuick) {
+            try {
+                const structural = new semantic_1.StructuralAnalyzer();
+                const structuralFindings = await structural.analyze(targetDir);
+                const converted = (0, semantic_1.toSecurityFindings)(structuralFindings);
+                findings.push(...converted);
+                layer2Count = converted.length;
+            }
+            catch {
+                // Structural analysis failure is non-fatal
+            }
         }
-        // Layer 3: LLM analysis (only with --deep + API key in CLI mode)
-        if (options.deep && process.env.ANTHROPIC_API_KEY) {
+        // Layer 3: LLM analysis (only in deep mode + API key)
+        if ((isDeepScan || options.deep) && process.env.ANTHROPIC_API_KEY) {
             try {
                 const structural = new semantic_1.StructuralAnalyzer();
                 const files = await structural.discoverFiles(targetDir);
@@ -794,7 +840,8 @@ class HardeningScanner {
                         line: firstLine,
                         fixable: true,
                         fixed: fileModified,
-                        fix: `Run \`${this.cliName} secure --fix\` to replace the hardcoded credential with a \${ENV_VAR} reference, then store the actual value in your .env file`,
+                        fix: `${this.cliName} secure --fix`,
+                        guidance: 'Replaces hardcoded credentials with ${ENV_VAR} references. Store actual values in your .env file, which should be in .gitignore.',
                     });
                 }
             }
@@ -846,7 +893,8 @@ class HardeningScanner {
                     file: 'CLAUDE.md',
                     line: credentialLine,
                     fixable: false,
-                    fix: 'Manually move the credential to a .env file and reference it as ${ENV_VAR}. CLAUDE.md may be committed to git and exposed publicly',
+                    fix: 'npx secretless-ai init',
+                    guidance: 'CLAUDE.md is often committed to git and exposed publicly. Move credentials to a .env file and reference as ${ENV_VAR}. Secretless AI blocks credential access from AI tool context.',
                 });
             }
         }
@@ -912,7 +960,8 @@ class HardeningScanner {
                     file: 'mcp.json',
                     fixable: true,
                     fixed: mcp001Fixed,
-                    fix: `Run \`${this.cliName} secure --fix\` to restrict filesystem access from / or ~ to project-relative paths (./data or ./)`,
+                    fix: `${this.cliName} secure --fix`,
+                    guidance: 'Root or home directory access lets MCP servers read/write any file on the system. Restrict to project-relative paths (./data or ./) to limit blast radius.',
                 });
             }
             if (hasUnrestrictedShell) {
@@ -926,7 +975,8 @@ class HardeningScanner {
                     message: 'Add allowedCommands to restrict shell access',
                     file: 'mcp.json',
                     fixable: false,
-                    fix: 'Manually add an "allowedCommands" array to your shell server config in mcp.json to whitelist specific commands (e.g., ["ls", "cat", "grep"])',
+                    fix: 'Add "allowedCommands": ["ls", "cat", "grep"] to the shell server config in mcp.json',
+                    guidance: 'Unrestricted shell access lets the AI execute any command including destructive operations. Whitelisting specific commands limits what can be run.',
                 });
             }
         }
@@ -978,6 +1028,7 @@ class HardeningScanner {
             fixed: autoFix && !passed,
             fixMessage: autoFix && !passed ? 'Changed permissions to 600' : undefined,
             details: passed ? undefined : { files: permissionIssues },
+            guidance: 'Overly broad file permissions let any user on the system read sensitive config files that may contain credentials or API keys.',
         });
         return findings;
     }
@@ -1031,39 +1082,44 @@ dist/
                 file: '.gitignore',
                 fixable: true,
                 fixed: git001Fixed,
-                fix: `Run \`${this.cliName} secure --fix\` to create a .gitignore with security patterns (.env, secrets.json, *.pem, *.key) to prevent accidental commits`,
+                fix: `${this.cliName} secure --fix`,
+                guidance: 'Without .gitignore, sensitive files (.env, secrets.json, *.pem, *.key) can be accidentally committed to version control and exposed.',
             });
         }
         // GIT-002: Check for missing sensitive patterns in .gitignore
-        const sensitivePatterns = ['.env', 'secrets.json', '*.pem', '*.key'];
-        const missingPatterns = [];
-        for (const pattern of sensitivePatterns) {
-            if (!gitignoreContent.includes(pattern) && !gitignoreContent.includes(pattern.replace('*', ''))) {
-                missingPatterns.push(pattern);
+        // Only check if .gitignore exists — GIT-001 handles creation
+        if (gitignoreExists) {
+            const sensitivePatterns = ['.env', 'secrets.json', '*.pem', '*.key'];
+            const missingPatterns = [];
+            for (const pattern of sensitivePatterns) {
+                if (!gitignoreContent.includes(pattern) && !gitignoreContent.includes(pattern.replace('*', ''))) {
+                    missingPatterns.push(pattern);
+                }
+            }
+            let git002Fixed = false;
+            if (missingPatterns.length > 0 && autoFix) {
+                const patternsToAdd = '\n# Security patterns (auto-added)\n' + missingPatterns.join('\n') + '\n';
+                gitignoreContent += patternsToAdd;
+                await fs.writeFile(gitignorePath, gitignoreContent);
+                git002Fixed = true;
+            }
+            // Only report if patterns are missing
+            if (missingPatterns.length > 0) {
+                findings.push({
+                    checkId: 'GIT-002',
+                    name: 'Incomplete .gitignore',
+                    description: `Missing: ${missingPatterns.join(', ')}`,
+                    category: 'git',
+                    severity: 'high',
+                    passed: git002Fixed,
+                    message: `Add patterns: ${missingPatterns.join(', ')}`,
+                    file: '.gitignore',
+                    fixable: true,
+                    fixed: git002Fixed,
+                    fix: `${this.cliName} secure --fix`,
+                    guidance: `Missing patterns (${missingPatterns.join(', ')}) in .gitignore mean sensitive files could be accidentally committed and pushed to remote repositories.`,
+                });
             }
-        }
-        let git002Fixed = false;
-        if (missingPatterns.length > 0 && autoFix) {
-            const patternsToAdd = '\n# Security patterns (auto-added)\n' + missingPatterns.join('\n') + '\n';
-            gitignoreContent += patternsToAdd;
-            await fs.writeFile(gitignorePath, gitignoreContent);
-            git002Fixed = true;
-        }
-        // Only report if patterns are missing
-        if (missingPatterns.length > 0) {
-            findings.push({
-                checkId: 'GIT-002',
-                name: 'Incomplete .gitignore',
-                description: `Missing: ${missingPatterns.join(', ')}`,
-                category: 'git',
-                severity: 'high',
-                passed: git002Fixed,
-                message: `Add patterns: ${missingPatterns.join(', ')}`,
-                file: '.gitignore',
-                fixable: true,
-                fixed: git002Fixed,
-                fix: `Run \`${this.cliName} secure --fix\` to add ${missingPatterns.join(', ')} to .gitignore so sensitive files won't be accidentally committed`,
-            });
         }
         // GIT-003: Check if .env exists but not in .gitignore
         let envExists = false;
@@ -1098,7 +1154,8 @@ dist/
                 file: '.env',
                 fixable: true,
                 fixed: git003Fixed,
-                fix: `Run \`${this.cliName} secure --fix\` to add .env to .gitignore so your environment variables won't be accidentally committed`,
+                fix: `${this.cliName} secure --fix`,
+                guidance: '.env files contain API keys and secrets. Without .gitignore protection, a single git add . can expose all credentials in your repository history.',
             });
         }
         return findings;
@@ -1143,7 +1200,8 @@ dist/
                 file: 'mcp.json',
                 fixable: true,
                 fixed: net001Fixed,
-                fix: `Run \`${this.cliName} secure --fix\` to change 0.0.0.0 to 127.0.0.1 so the server only accepts local connections instead of being exposed to the network`,
+                fix: `${this.cliName} secure --fix`,
+                guidance: 'Binding to 0.0.0.0 exposes the server to the entire network. Use 127.0.0.1 for local-only access. If remote access is needed, use a reverse proxy with authentication.',
             });
         }
         // NET-002: Check for remote MCP servers without TLS
@@ -1168,7 +1226,8 @@ dist/
                 message: 'Change http:// to https://',
                 file: 'mcp.json',
                 fixable: false,
-                fix: 'Manually change http:// to https:// in mcp.json to encrypt traffic and prevent man-in-the-middle attacks',
+                fix: 'Update URL to https:// in mcp.json',
+                guidance: 'HTTP traffic is unencrypted and vulnerable to man-in-the-middle attacks. An attacker on the network can intercept and modify MCP server communications.',
             });
         }
         return findings;
@@ -1236,7 +1295,8 @@ dist/
                 file: 'mcp.json',
                 fixable: true,
                 fixed: mcp003Fixed,
-                fix: `Run \`${this.cliName} secure --fix\` to replace hardcoded API keys with \${ENV_VAR} references, then store actual values in .env file`,
+                fix: `${this.cliName} secure --fix`,
+                guidance: 'Hardcoded API keys in mcp.json are exposed to anyone with repo access. Use ${ENV_VAR} references and store actual values in .env (which should be in .gitignore).',
             });
         }
         // MCP-004: Check for default credentials
@@ -1267,7 +1327,8 @@ dist/
                 message: 'Change to strong unique password',
                 file: 'mcp.json',
                 fixable: false,
-                fix: 'Manually change the default password in mcp.json to a strong, unique password (use `openssl rand -base64 24` to generate one)',
+                fix: 'openssl rand -base64 24',
+                guidance: 'Default passwords (postgres, admin, root, etc.) are the first thing attackers try. Generate a strong random password and update mcp.json.',
             });
         }
         // MCP-005: Check for wildcard tool access
@@ -1292,7 +1353,8 @@ dist/
                 message: 'Restrict to specific tools needed',
                 file: 'mcp.json',
                 fixable: false,
-                fix: 'Manually replace "*" with a list of specific tool names you need (e.g., ["read_file", "list_directory"]) to limit what the AI can access',
+                fix: 'Replace "*" with specific tool names in allowedTools (e.g., ["read_file", "list_directory"])',
+                guidance: 'Wildcard tool access gives the AI unrestricted capabilities. Limit to only the tools your workflow actually needs to reduce attack surface.',
             });
         }
         return findings;
@@ -1329,7 +1391,8 @@ dist/
                 message: 'Scope permissions to specific paths',
                 file: '.claude/settings.json',
                 fixable: false,
-                fix: 'Manually replace wildcards like Bash(*) or Read(*) with specific paths (e.g., Bash(npm test) or Read(/src/**)) to limit AI access',
+                fix: 'Replace Bash(*) with Bash(npm test) and Read(*) with Read(/src/**) in .claude/settings.json',
+                guidance: 'Wildcard permissions give the AI unrestricted shell, read, or write access. Scope each permission to the specific commands and paths your workflow needs.',
             });
         }
         // CLAUDE-003: Check for dangerous Bash patterns
@@ -1359,7 +1422,8 @@ dist/
                 message: 'Remove rm -rf, sudo, etc.',
                 file: '.claude/settings.json',
                 fixable: false,
-                fix: 'Manually remove dangerous commands (rm -rf, sudo, chmod 777, etc.) from the allow list in .claude/settings.json to prevent accidental destructive operations',
+                fix: 'Remove rm -rf, sudo, chmod 777 patterns from the allow list in .claude/settings.json',
+                guidance: 'Allowing destructive commands means a single AI mistake can delete files, escalate privileges, or weaken permissions. Restrict to safe, reversible operations.',
             });
         }
         return findings;
@@ -1395,6 +1459,7 @@ dist/
                 ? 'Cursor rules contain exposed credentials - remove and use environment variables'
                 : 'No credentials found in Cursor rules',
             fixable: false,
+            guidance: 'Cursor rules files are often committed to git. Credentials embedded there get pushed to remotes where anyone with repo access can extract them.',
         });
         return findings;
     }
@@ -1427,6 +1492,7 @@ dist/
                 ? 'VSCode MCP config contains exposed credentials'
                 : 'No credentials in VSCode MCP config',
             fixable: false,
+            guidance: 'MCP config files are shared across workspaces and often committed to repos. Credentials there are exposed to every tool and extension that reads the config.',
         });
         // VSCODE-002: Check for overly permissive paths
         let hasRootAccess = false;
@@ -1449,6 +1515,7 @@ dist/
                 ? 'VSCode MCP server has dangerous filesystem access'
                 : 'VSCode MCP filesystem access is scoped',
             fixable: false,
+            guidance: 'An MCP server with root or home directory access can read SSH keys, cloud credentials, and any file on the system. Scope access to the project directory only.',
         });
         return findings;
     }
@@ -1478,6 +1545,7 @@ dist/
                 : `Private key files found: ${foundKeys.join(', ')} - move to secure location`,
             fixable: false,
             details: foundKeys.length > 0 ? { files: foundKeys } : undefined,
+            guidance: 'Private key files (.pem, .key) in a project directory are easily committed to git. Once pushed, the keys are compromised and must be rotated.',
         });
         // CRED-003: Check package.json for hardcoded secrets
         let hasSecretsInPackageJson = false;
@@ -1502,6 +1570,7 @@ dist/
                 ? 'package.json contains hardcoded secrets - move to environment variables'
                 : 'No secrets found in package.json',
             fixable: false,
+            guidance: 'package.json is always committed to git and published to npm. Secrets there are visible to anyone who installs or forks your package.',
         });
         // CRED-004: Check for JWT secrets in config
         let hasJwtSecret = false;
@@ -1530,6 +1599,7 @@ dist/
                 ? 'JWT secret hardcoded in config - use environment variable'
                 : 'No hardcoded JWT secrets found',
             fixable: false,
+            guidance: 'A hardcoded JWT secret lets anyone who reads the config forge valid authentication tokens and impersonate any user.',
         });
         return findings;
     }
@@ -1561,6 +1631,7 @@ dist/
             fixable: true,
             fixed: false,
             details: executableConfigs.length > 0 ? { files: executableConfigs } : undefined,
+            guidance: 'Executable config files can be run as scripts. An attacker who modifies a config file with execute permission can trick the system into running arbitrary code.',
         });
         // PERM-003: Check for group-writable sensitive files
         const sensitiveFiles = ['.env', '.env.local', 'secrets.json', 'credentials.json'];
@@ -1588,6 +1659,7 @@ dist/
             fixable: true,
             fixed: false,
             details: groupWritable.length > 0 ? { files: groupWritable } : undefined,
+            guidance: 'Group-writable sensitive files allow other users in the same group to modify credentials or inject malicious configuration values.',
         });
         return findings;
     }
@@ -1620,6 +1692,7 @@ dist/
                 ? 'Development mode enabled - ensure this is disabled in production'
                 : 'No development mode indicators found',
             fixable: false,
+            guidance: 'Development mode typically disables security features like CSRF protection, strict CORS, and error sanitization, leaving the application exposed in production.',
         });
         // ENV-002: Check for debug flags
         let hasDebugFlags = false;
@@ -1647,6 +1720,7 @@ dist/
                 ? 'Debug flags enabled - may expose sensitive information in logs'
                 : 'No debug flags detected',
             fixable: false,
+            guidance: 'Debug and verbose logging flags can leak internal state, database queries, and credential values into log files or console output.',
         });
         // ENV-003: Check for error verbosity settings
         let verboseErrors = false;
@@ -1674,6 +1748,7 @@ dist/
                 ? 'Verbose error messages enabled - may leak sensitive information'
                 : 'Error verbosity settings are appropriate',
             fixable: false,
+            guidance: 'Verbose error messages expose stack traces, file paths, and internal logic to attackers, making it easier to find exploitable weaknesses.',
         });
         // ENV-004: Check for production environment validation
         let hasEnvValidation = false;
@@ -1693,6 +1768,7 @@ dist/
                 ? 'Environment validation library detected'
                 : 'Consider using env validation (dotenv, envalid) to catch misconfigurations',
             fixable: false,
+            guidance: 'Without environment validation, missing or malformed variables cause silent failures. A missing DB_HOST might fall back to an insecure default rather than failing fast.',
         });
         return findings;
     }
@@ -1716,6 +1792,7 @@ dist/
                 ? 'Structured logging library detected'
                 : 'Consider using structured logging (winston, pino) for better security auditing',
             fixable: false,
+            guidance: 'Unstructured console.log output is hard to filter, search, or redact. Structured logging makes it possible to automatically mask sensitive fields and detect anomalies.',
         });
         // LOG-002: Check for sensitive data in log patterns
         let sensitiveInLogs = false;
@@ -1749,6 +1826,7 @@ dist/
                 ? 'Code may be logging sensitive data - review console.log statements'
                 : 'No obvious sensitive data logging patterns found',
             fixable: false,
+            guidance: 'Passwords, API keys, and tokens logged to console or files persist in log aggregators and crash reports, where they can be harvested by anyone with log access.',
         });
         // LOG-003: Check for log file permissions
         const logFiles = ['app.log', 'error.log', 'debug.log', 'access.log'];
@@ -1775,6 +1853,7 @@ dist/
                 : `World-readable log files: ${worldReadableLogs.join(', ')}`,
             fixable: true,
             fixed: false,
+            guidance: 'World-readable log files let any local user read application logs, which often contain request details, internal errors, and sometimes credentials.',
         });
         // LOG-004: Check for audit logging capability
         let hasAuditLogging = false;
@@ -1794,6 +1873,7 @@ dist/
                 ? 'Audit logging capability detected'
                 : 'Consider implementing audit logging for security events',
             fixable: false,
+            guidance: 'Without audit logging, there is no record of who accessed what or when. Incident response becomes guesswork without a trail of security-relevant events.',
         });
         return findings;
     }
@@ -1829,6 +1909,7 @@ dist/
                 ? 'Dependency lock file present'
                 : 'No lock file found - dependency versions may vary between installs',
             fixable: false,
+            guidance: 'Without a lock file, npm install can resolve to different package versions on different machines, including versions with known vulnerabilities or supply-chain backdoors.',
         });
         // DEP-002: Check for known vulnerable packages
         const vulnerablePackages = ['event-stream', 'flatmap-stream', 'eslint-scope@3.7.2'];
@@ -1854,6 +1935,7 @@ dist/
                 ? 'Potentially vulnerable package detected - run npm audit'
                 : 'No known vulnerable packages in direct dependencies',
             fixable: false,
+            guidance: 'These packages have confirmed supply-chain compromises (e.g., event-stream injected a cryptocurrency-stealing payload). Remove or replace them immediately.',
         });
         // DEP-003: Check for wildcard versions
         let hasWildcardVersions = false;
@@ -1880,6 +1962,7 @@ dist/
                 ? 'Wildcard versions detected - pin dependencies for reproducible builds'
                 : 'All dependency versions are properly specified',
             fixable: false,
+            guidance: 'Wildcard (*) or "latest" versions accept any future release, including ones compromised by supply-chain attacks. Pin versions and use a lock file.',
         });
         // DEP-004: Check for npm scripts security
         let hasDangerousScripts = false;
@@ -1922,6 +2005,7 @@ dist/
                 ? 'Dangerous patterns in npm scripts (curl|sh, eval) - review carefully'
                 : 'npm scripts appear safe',
             fixable: false,
+            guidance: 'Scripts that pipe curl/wget to sh execute arbitrary remote code during npm install. An attacker who compromises the URL controls your build environment.',
         });
         return findings;
     }
@@ -1951,6 +2035,7 @@ dist/
                 ? 'Authentication configuration detected'
                 : 'No authentication library detected - ensure endpoints are protected',
             fixable: false,
+            guidance: 'Without authentication, any network-reachable client can access your API endpoints, including reading data, triggering actions, and modifying state.',
         });
         // AUTH-002: Check for rate limiting
         let hasRateLimiting = false;
@@ -1970,6 +2055,7 @@ dist/
                 ? 'Rate limiting library detected'
                 : 'No rate limiting detected - API may be vulnerable to abuse',
             fixable: false,
+            guidance: 'Without rate limiting, attackers can brute-force credentials, scrape data, or exhaust resources with automated requests at no cost.',
         });
         // AUTH-003: Check for session security
         let hasSecureSessions = false;
@@ -2003,6 +2089,7 @@ dist/
                 ? 'Secure session configuration detected'
                 : 'Ensure sessions use secure, httpOnly cookies',
             fixable: false,
+            guidance: 'Sessions without secure and httpOnly flags are vulnerable to theft via XSS attacks or network sniffing, allowing attackers to hijack authenticated sessions.',
         });
         // AUTH-004: Check for CORS configuration
         let hasCorsConfig = false;
@@ -2022,6 +2109,7 @@ dist/
                 ? 'CORS library detected'
                 : 'No CORS configuration detected - ensure cross-origin requests are properly handled',
             fixable: false,
+            guidance: 'Without explicit CORS configuration, browsers may block legitimate cross-origin requests or, worse, a permissive default may allow malicious sites to make authenticated requests to your API.',
         });
         return findings;
     }
@@ -3817,8 +3905,24 @@ dist/
             existingFiles: [],
             createdFiles: [],
         };
-        // Backup each file that exists
-        for (const file of HardeningScanner.BACKUP_FILES) {
+        // Backup each file that exists (static list + web directory scan)
+        const filesToBackup = [...HardeningScanner.BACKUP_FILES];
+        // Also discover files in web-served directories that --fix may modify
+        const webDirs = ['public', 'static', 'dist', 'build', 'out', 'www', '_site'];
+        const webExts = ['.html', '.htm', '.js', '.jsx', '.tsx', '.css', '.py', '.md'];
+        for (const webDir of webDirs) {
+            const webDirPath = path.join(targetDir, webDir);
+            try {
+                const entries = await fs.readdir(webDirPath, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isFile() && webExts.some(ext => entry.name.endsWith(ext))) {
+                        filesToBackup.push(path.join(webDir, entry.name));
+                    }
+                }
+            }
+            catch { /* dir doesn't exist */ }
+        }
+        for (const file of filesToBackup) {
             const sourcePath = path.join(targetDir, file);
             try {
                 await fs.access(sourcePath);
@@ -4000,7 +4104,8 @@ dist/
                 fixable: true,
                 fixed: skill001Fixed,
                 fixMessage: skill001Fixed ? 'Added SHA-256 signature block to skill file' : undefined,
-                fix: 'Run `hackmyagent fix-all --with-aim` to automatically sign all skill files with a cryptographic identity',
+                fix: 'hackmyagent fix-all --with-aim',
+                guidance: 'Unsigned skills cannot be verified for authenticity or integrity. Sign with a cryptographic identity to enable tamper detection.',
             });
             // SKILL-002: Remote Fetch Pattern
             for (let i = 0; i < lines.length; i++) {
@@ -4020,7 +4125,8 @@ dist/
                             file: relativePath,
                             line: i + 1,
                             fixable: false,
-                            fix: 'Remove curl|sh, wget|sh, and other remote code execution patterns',
+                            fix: 'Remove the curl|sh or wget|sh pattern from this file',
+                            guidance: 'Remote code execution patterns download and execute arbitrary code. Replace with a pinned dependency or vendored script with checksum verification.',
                         });
                         break; // One finding per line
                     }
@@ -4043,7 +4149,8 @@ dist/
                         file: relativePath,
                         line: i + 1,
                         fixable: false,
-                        fix: 'Heartbeats should be configured separately with restricted permissions, not bundled in skills',
+                        fix: 'Move scheduled task configuration to a separate heartbeat config file',
+                        guidance: 'Skills that install heartbeats or cron jobs gain persistent execution beyond the user session. Heartbeats should be configured separately with restricted permissions.',
                     });
                 }
             }
@@ -4079,7 +4186,8 @@ dist/
                         fixable: true,
                         fixed: fixApplied,
                         fixMessage: fixApplied ? 'Restricted filesystem access to sandbox scope' : undefined,
-                        fix: 'Restrict filesystem access to specific directories (e.g., filesystem:./data/*)',
+                        fix: 'hackmyagent secure --fix',
+                        guidance: 'Broad filesystem access (filesystem:* or filesystem:~/) lets skills read/write anywhere. Restrict to specific directories (e.g., filesystem:./data/*).',
                     });
                 }
             }
@@ -4104,7 +4212,8 @@ dist/
                             file: relativePath,
                             line: i + 1,
                             fixable: false,
-                            fix: 'Skills should never access credential files like ~/.ssh, ~/.aws, wallets, or .env files',
+                            fix: 'Remove credential file access patterns from this skill',
+                            guidance: 'Skills accessing ~/.ssh, ~/.aws, wallets, or .env files can exfiltrate credentials. Use npx secretless-ai init to protect credentials from AI tool context.',
                         });
                         break; // One finding per line per check
                     }
@@ -4127,7 +4236,8 @@ dist/
                             file: relativePath,
                             line: i + 1,
                             fixable: false,
-                            fix: 'Remove webhook.site, requestbin, ngrok, and suspicious POST patterns',
+                            fix: 'Remove the exfiltration endpoint from this skill',
+                            guidance: 'Data exfiltration patterns (webhook.site, requestbin, ngrok, suspicious POST) send local data to external servers. Remove or replace with audited, allow-listed endpoints.',
                         });
                         break; // One finding per line per check
                     }
@@ -4150,7 +4260,8 @@ dist/
                             file: relativePath,
                             line: i + 1,
                             fixable: false,
-                            fix: 'Remove social engineering instructions that trick users into copying/pasting commands',
+                            fix: 'Remove the copy/paste instruction block from this skill',
+                            guidance: 'ClickFix social engineering tricks users into copying and pasting malicious commands. This technique was used extensively in the ClawHavoc campaign.',
                         });
                         break; // One finding per line per check
                     }
@@ -4173,7 +4284,8 @@ dist/
                             file: relativePath,
                             line: i + 1,
                             fixable: false,
-                            fix: 'Remove netcat, bash -i, /dev/tcp, and other reverse shell patterns',
+                            fix: 'Remove the reverse shell pattern from this skill',
+                            guidance: 'Reverse shell patterns (netcat, bash -i, /dev/tcp) establish remote command execution. This is a strong indicator of malicious intent.',
                         });
                         break; // One finding per line per check
                     }
@@ -4205,7 +4317,8 @@ dist/
                         message: `Skill name "${skillBasename}" is similar to popular skill "${popular}" (potential typosquatting)`,
                         file: relativePath,
                         fixable: false,
-                        fix: 'Rename the skill to avoid confusion with popular skills, or verify this is intentional',
+                        fix: `hackmyagent check ${relativePath}`,
+                        guidance: 'Typosquatting uses names similar to popular skills to trick users into installing malicious versions. Verify the skill source and rename if unintentional.',
                     });
                     break; // One typosquatting finding per skill file
                 }
@@ -4231,7 +4344,8 @@ dist/
                         file: relativePath,
                         line: i + 1,
                         fixable: false,
-                        fix: 'Skills should not access .env files or environment variables containing secrets',
+                        fix: 'npx secretless-ai init',
+                        guidance: 'Skills accessing .env files or process.env can exfiltrate API keys and secrets. Use Secretless AI to block credential access from AI tool context.',
                     });
                 }
             }
@@ -4256,7 +4370,8 @@ dist/
                         file: relativePath,
                         line: i + 1,
                         fixable: false,
-                        fix: 'Skills should not access browser data, cookies, localStorage, or sessionStorage',
+                        fix: 'Remove browser data access patterns from this skill',
+                        guidance: 'Skills accessing browser data (cookies, localStorage, sessionStorage) can steal session tokens and authentication state.',
                     });
                 }
             }
@@ -4281,7 +4396,8 @@ dist/
                         file: relativePath,
                         line: i + 1,
                         fixable: false,
-                        fix: 'Skills should never access cryptocurrency wallets, seed phrases, or private keys',
+                        fix: 'Remove crypto wallet access patterns from this skill',
+                        guidance: 'Skills accessing wallets, seed phrases, or private keys can drain cryptocurrency funds. No legitimate skill needs this access.',
                     });
                 }
             }
@@ -4325,7 +4441,8 @@ dist/
                         fixable: true,
                         fixed: skill019Fixed,
                         fixMessage: skill019Fixed ? 'Re-computed hash and updated signature block' : undefined,
-                        fix: 'Re-sign the skill to update the hash: hackmyagent secure --fix',
+                        fix: 'hackmyagent secure --fix',
+                        guidance: 'The signature hash no longer matches the file content. This could indicate tampering or a legitimate edit that was not re-signed.',
                     });
                 }
                 // HEARTBEAT-007: Expired Heartbeat (check expires_at in signature block)
@@ -4358,7 +4475,8 @@ dist/
                             fixable: true,
                             fixed: hb007Fixed,
                             fixMessage: hb007Fixed ? 'Updated expiry to 7 days from now and re-signed' : undefined,
-                            fix: 'Re-sign the skill with a new expiry: hackmyagent secure --fix',
+                            fix: 'hackmyagent secure --fix',
+                            guidance: 'Expired signatures mean the skill has not been re-verified since its expiry date. Re-signing renews the validity period and re-verifies content integrity.',
                         });
                     }
                 }
@@ -4463,6 +4581,7 @@ dist/
                         line: i + 1,
                         fixable: false,
                         fix: 'Verify the URL is from a trusted source and add hash pinning for integrity',
+                        guidance: 'Heartbeats that contact external URLs without verification can be redirected to malicious endpoints. Pin the expected hash to detect tampering.',
                     });
                 }
             }
@@ -4482,7 +4601,8 @@ dist/
                     : 'Heartbeat lacks hash pinning - content integrity cannot be verified',
                 file: relativePath,
                 fixable: false,
-                fix: 'Run `hackmyagent fix-all --with-aim` to automatically pin and sign heartbeat files',
+                fix: 'hackmyagent fix-all --with-aim',
+                guidance: 'Without hash pinning, heartbeat content can be modified without detection. Pinning creates a cryptographic fingerprint to verify integrity on each execution.',
             });
             // HEARTBEAT-003: Unsigned Heartbeat
             const hasSignature = content.includes('opena2a_signature:') ||
@@ -4500,7 +4620,8 @@ dist/
                     : 'Heartbeat is unsigned - cannot verify authenticity or integrity',
                 file: relativePath,
                 fixable: false,
-                fix: 'Run `hackmyagent fix-all --with-aim` to automatically sign all heartbeat files with a cryptographic identity',
+                fix: 'hackmyagent fix-all --with-aim',
+                guidance: 'Unsigned heartbeats cannot prove who created them or whether they have been modified. Cryptographic signatures enable authenticity and integrity verification.',
             });
             // HEARTBEAT-004: Dangerous Capabilities
             for (let i = 0; i < lines.length; i++) {
@@ -4519,6 +4640,7 @@ dist/
                             line: i + 1,
                             fixable: false,
                             fix: 'Heartbeats should use minimal capabilities - avoid shell:*, filesystem:*, network:*',
+                            guidance: 'Wildcard capabilities (shell:*, filesystem:*, network:*) give heartbeats unrestricted access. A compromised heartbeat with these permissions can execute arbitrary commands, read any file, or exfiltrate data.',
                         });
                     }
                 }
@@ -4554,6 +4676,7 @@ dist/
                             line: i + 1,
                             fixable: false,
                             fix: 'Increase heartbeat interval to at least 5 minutes to prevent resource exhaustion',
+                            guidance: 'High-frequency heartbeats consume CPU, memory, and network bandwidth. Intervals under 5 minutes can cause resource exhaustion and may mask malicious polling behavior.',
                         });
                     }
                 }
@@ -4576,6 +4699,7 @@ dist/
                 file: relativePath,
                 fixable: false,
                 fix: 'Add activeHours: or schedule: to limit when the heartbeat can run',
+                guidance: 'Unrestricted heartbeats run 24/7 including off-hours when no one monitors them. Time-of-day limits reduce the window for undetected malicious activity.',
             });
         }
         return findings;
@@ -4674,7 +4798,8 @@ dist/
                     fixable: true,
                     fixed: gateway001Fixed,
                     fixMessage: gateway001Fixed ? 'Changed gateway.host from 0.0.0.0 to 127.0.0.1' : undefined,
-                    fix: `Run \`${this.cliName} secure-openclaw --fix\` to bind gateway to 127.0.0.1 for local-only access`,
+                    fix: `${this.cliName} secure-openclaw --fix`,
+                    guidance: 'Binding to 0.0.0.0 exposes the gateway to all network interfaces. Use 127.0.0.1 for local-only access unless remote access is explicitly needed with proper authentication.',
                 });
             }
             // GATEWAY-002: Missing WebSocket Origin Validation (not auto-fixable - requires user to specify allowed origins)
@@ -4692,7 +4817,8 @@ dist/
                     : 'Missing security.websocketOrigins - vulnerable to GHSA-g8p2 cross-origin attacks',
                 file: relativePath,
                 fixable: false,
-                fix: 'Manually add security.websocketOrigins array with your allowed origins (e.g., ["http://localhost:3000"])',
+                fix: 'Add security.websocketOrigins: ["http://localhost:3000"] to the gateway config',
+                guidance: 'Without origin validation, any website can connect to the gateway via WebSocket (GHSA-g8p2). This enables cross-origin command execution attacks.',
             });
             // GATEWAY-003: Token Exposed in Config
             const gatewayAuth = gateway?.auth;
@@ -4730,7 +4856,8 @@ dist/
                     fixable: true,
                     fixed: gateway003Fixed,
                     fixMessage: gateway003Fixed ? 'Replaced plaintext token with ${OPENCLAW_AUTH_TOKEN} env var reference. Set OPENCLAW_AUTH_TOKEN in your environment.' : undefined,
-                    fix: `Run \`${this.cliName} secure-openclaw --fix\` to replace plaintext token with \${OPENCLAW_AUTH_TOKEN} env var reference`,
+                    fix: `${this.cliName} secure-openclaw --fix`,
+                    guidance: 'Plaintext tokens in config files are exposed to anyone with repo access. Use environment variable references so credentials stay outside version control.',
                 });
             }
             // GATEWAY-004: Approval Confirmations Disabled
@@ -4777,7 +4904,8 @@ dist/
                     fixable: true,
                     fixed: gateway004Fixed,
                     fixMessage: gateway004Fixed ? 'Enabled approval confirmations for command execution' : undefined,
-                    fix: `Run \`${this.cliName} secure-openclaw --fix\` to enable approval confirmations for safer command execution`,
+                    fix: `${this.cliName} secure-openclaw --fix`,
+                    guidance: 'Without approval confirmations, commands execute immediately without user review. This removes the last line of defense against malicious or accidental destructive operations.',
                 });
             }
             // GATEWAY-005: Sandbox Disabled
@@ -4806,7 +4934,8 @@ dist/
                     fixable: true,
                     fixed: gateway005Fixed,
                     fixMessage: gateway005Fixed ? 'Enabled sandbox mode for isolated code execution' : undefined,
-                    fix: `Run \`${this.cliName} secure-openclaw --fix\` to enable sandbox mode for safer code execution`,
+                    fix: `${this.cliName} secure-openclaw --fix`,
+                    guidance: 'Without sandbox isolation, executed code has full system access including filesystem, network, and process control. Sandbox mode limits the blast radius of malicious or buggy code.',
                 });
             }
             // GATEWAY-006: Container Escape Risk (not auto-fixable - requires manual review of mount points)
@@ -4834,7 +4963,8 @@ dist/
                     message: `Container escape risk: ${issues.join(', ')}`,
                     file: relativePath,
                     fixable: false,
-                    fix: 'Manually disable privileged mode and remove sensitive host mounts - requires careful review',
+                    fix: 'Disable docker.privileged and remove sensitive mounts (/var/run/docker.sock, /etc/passwd, /:/) from the config',
+                    guidance: 'Privileged mode and sensitive host mounts allow container escape -- the agent can access the host system, other containers, and all their data.',
                 });
             }
             // GATEWAY-007: Open DM Policy with Wildcard
@@ -4869,6 +4999,7 @@ dist/
                     file: relativePath,
                     fixable: false,
                     fix: 'Replace wildcard "*" in allowFrom with specific allowed sender IDs or domains',
+                    guidance: 'An open DM policy with wildcard allows any entity to send messages to the agent. Attackers can use this to inject commands or exfiltrate data via conversation.',
                 });
             }
             // GATEWAY-008: Tailscale Funnel Exposure
@@ -4887,6 +5018,7 @@ dist/
                     file: relativePath,
                     fixable: false,
                     fix: 'Disable Tailscale Funnel unless public access is intentional. Use Tailscale ACLs to restrict access.',
+                    guidance: 'Tailscale Funnel exposes the agent to the public internet, bypassing Tailscale\'s private network protection. Only enable if you explicitly need public access.',
                 });
             }
             // Write modified config back to file if any fixes were applied
@@ -4904,7 +5036,8 @@ dist/
                         message: `Applied ${fixesApplied.length} fix(es): ${fixesApplied.join('; ')}`,
                         file: relativePath,
                         fixable: false,
-                        fix: 'Use `hackmyagent rollback` to undo these changes if needed',
+                        fix: 'hackmyagent rollback',
+                        guidance: 'Auto-fixes were applied to this configuration. Use rollback to revert if any fix caused unexpected behavior.',
                     });
                 }
                 catch (writeError) {
@@ -4919,6 +5052,7 @@ dist/
                         file: relativePath,
                         fixable: false,
                         fix: 'Check file permissions and try again',
+                        guidance: 'The auto-fix could not write changes to the configuration file. Verify the file is not read-only and that you have write permissions.',
                     });
                 }
             }
@@ -5030,6 +5164,7 @@ dist/
                 file: relativePath,
                 fixable: false,
                 fix: 'Move session files outside the project directory or add to .gitignore',
+                guidance: 'Session and token files contain credentials that grant access to messaging platforms. If committed to git, anyone with repo access can hijack these sessions.',
             });
         }
         // CONFIG-002: SOUL.md Injection Vectors
@@ -5073,6 +5208,7 @@ dist/
                         file: relativePath,
                         fixable: false,
                         fix: 'Review and remove suspicious patterns from SOUL.md',
+                        guidance: 'SOUL.md defines agent behavior. Prompt injection patterns embedded here can override safety instructions and make the agent act maliciously.',
                     });
                     break; // Only report first match per file
                 }
@@ -5121,6 +5257,7 @@ dist/
                         file: relativePath,
                         fixable: false,
                         fix: 'Run daemon as non-root user with minimal privileges',
+                        guidance: 'Daemons running as root have unrestricted system access. A compromised root-level daemon can modify any file, install backdoors, or pivot to other systems.',
                     });
                     break; // Only report first match per file
                 }
@@ -5167,6 +5304,7 @@ dist/
                         file: relativePath,
                         fixable: false,
                         fix: 'Use a secrets manager or ensure .env is in .gitignore',
+                        guidance: 'Plaintext API keys in .env files can be accidentally committed. Use a secrets manager for production, and always ensure .env is in .gitignore.',
                     });
                     break; // Only report first match per file
                 }
@@ -5219,6 +5357,7 @@ dist/
                         file: relativePath,
                         fixable: false,
                         fix: 'Review and sanitize memory.json contents',
+                        guidance: 'Agent memory files can be poisoned with prompt injections, eval calls, or base64-encoded payloads that execute when the agent loads its context.',
                     });
                     break; // Only report first match per file
                 }
@@ -5265,6 +5404,7 @@ dist/
                     file: relativePath,
                     fixable: false,
                     fix: 'Disable autoFollow or review moltbook security settings',
+                    guidance: 'Auto-following untrusted agents can expose your agent to malicious instructions, data exfiltration, or prompt injection from compromised peers.',
                 });
             }
             // CONFIG-007: Unrestricted Elevated Execution
@@ -5288,6 +5428,7 @@ dist/
                     file: relativePath,
                     fixable: false,
                     fix: 'Set tools.elevated.defaultLevel to "restricted" and enable exec.approvals',
+                    guidance: 'Unrestricted elevated execution gives tools maximum system privileges without approval gates. This bypasses all safety checks for destructive operations.',
                 });
             }
             // CONFIG-008: Sandbox Disabled
@@ -5309,6 +5450,7 @@ dist/
                     file: relativePath,
                     fixable: false,
                     fix: 'Enable sandbox: set sandbox.enabled to true or tools.exec.sandbox to true',
+                    guidance: 'Without sandbox isolation, tool execution has direct access to the host filesystem, network, and processes. Enable sandboxing to contain potential damage.',
                 });
             }
             // CONFIG-009: Weak Gateway Token
@@ -5329,7 +5471,8 @@ dist/
                     message: `Token is only ${tokenValue.length} characters - minimum 24 recommended`,
                     file: relativePath,
                     fixable: false,
-                    fix: 'Generate a stronger token: openssl rand -base64 32',
+                    fix: 'openssl rand -base64 32',
+                    guidance: 'Short tokens are vulnerable to brute-force attacks. Use at least 24 characters of cryptographically random data for authentication tokens.',
                 });
             }
         }
@@ -5411,7 +5554,8 @@ dist/
                         : 'Skill lacks publisher metadata - cannot verify source',
                 file: relativePath,
                 fixable: false,
-                fix: 'Add publisher: and publisher_verified: true to skill frontmatter after verification',
+                fix: `hackmyagent check ${relativePath}`,
+                guidance: 'Unverified publishers cannot be trusted. Add publisher: and publisher_verified: true to skill frontmatter after DNS TXT record verification.',
             });
             // SUPPLY-002: Skill Not in Registry
             const hasRegistryAttestation = /^registry_attestation:\s*.+$/m.test(frontmatter);
@@ -5427,7 +5571,8 @@ dist/
                     : 'Skill lacks registry_attestation - not listed in trusted registry',
                 file: relativePath,
                 fixable: false,
-                fix: 'Register skill with a trusted registry (e.g., clawhub.io, skillregistry.openclaw.org)',
+                fix: 'Add registry_attestation: to skill frontmatter after registry submission',
+                guidance: 'Unregistered skills have no community trust signal. Register with a trusted registry to enable trust scoring and vulnerability alerts.',
             });
             // SUPPLY-003: Known Malicious Skill Pattern (ClawHavoc campaign)
             let isMaliciousMatch = false;
@@ -5458,7 +5603,8 @@ dist/
                     message: `Skill matches known malicious pattern: "${matchedPattern}"`,
                     file: relativePath,
                     fixable: false,
-                    fix: 'Remove this skill -- it matches known malware from the ClawHavoc campaign',
+                    fix: `rm ${relativePath}`,
+                    guidance: 'This skill matches known malicious patterns from the ClawHavoc campaign. Remove immediately and audit any systems it had access to.',
                 });
             }
             // SUPPLY-004: Version Drift Detection
@@ -5475,7 +5621,8 @@ dist/
                     : 'Skill lacks installed_hash - cannot detect version drift or tampering',
                 file: relativePath,
                 fixable: false,
-                fix: 'Add installed_hash: with SHA-256 hash of the original skill content',
+                fix: 'hackmyagent fix-all --with-aim',
+                guidance: 'Without an installed_hash, modifications to the skill cannot be detected. The hash enables tamper detection on every scan.',
             });
             // SUPPLY-005: ClawHavoc C2 IP
             for (const ip of CLAWHAVOC_C2_IPS) {
@@ -5490,7 +5637,8 @@ dist/
                         message: `Known C2 IP address found: ${ip}`,
                         file: relativePath,
                         fixable: false,
-                        fix: 'Remove this skill -- contains known malware C2 infrastructure',
+                        fix: `rm ${relativePath}`,
+                        guidance: 'This skill contains a known ClawHavoc command-and-control IP address. Remove immediately and check network logs for connections to this IP.',
                     });
                     break;
                 }
@@ -5508,7 +5656,8 @@ dist/
                         message: `Known malware filename referenced: "${filename}"`,
                         file: relativePath,
                         fixable: false,
-                        fix: 'Remove this skill -- references known malware payload',
+                        fix: `rm ${relativePath}`,
+                        guidance: 'This skill references a known ClawHavoc malware payload filename. Remove and scan for other indicators of compromise.',
                     });
                     break;
                 }
@@ -5527,7 +5676,8 @@ dist/
                         message: `ClickFix social engineering pattern detected: "${match[0]}"`,
                         file: relativePath,
                         fixable: false,
-                        fix: 'Review and remove suspicious download/execute instructions',
+                        fix: 'Remove the download/execute instruction from this skill',
+                        guidance: 'ClickFix patterns trick users into downloading and executing malware. This technique is associated with the ClawHavoc campaign.',
                     });
                     break;
                 }
@@ -5545,7 +5695,8 @@ dist/
                     message: `Suspicious archive password pattern: "${archiveMatch[0]}"`,
                     file: relativePath,
                     fixable: false,
-                    fix: 'Investigate password-protected archive reference - common malware distribution technique',
+                    fix: 'Remove the archive password reference from this skill',
+                    guidance: 'Password-protected archives are a common malware distribution technique to bypass antivirus scanning. Investigate the archive source.',
                 });
             }
         }
@@ -5586,7 +5737,8 @@ dist/
                             : `OpenClaw ${openclawVersion} includes CVE-2026-25253 fix`,
                         file: 'package.json',
                         fixable: false,
-                        fix: 'Upgrade openclaw to v2026.1.29 or later: npm install openclaw@latest',
+                        fix: 'npm install openclaw@latest',
+                        guidance: 'CVE-2026-25253 (CVSS 8.8) enables WebSocket hijacking for remote code execution. Upgrade to v2026.1.29 or later which includes the fix.',
                     });
                     // CVE-003: OS Command Injection via SSH Path (same fix version)
                     if (isVulnerable) {
@@ -5600,7 +5752,8 @@ dist/
                             message: `OpenClaw ${openclawVersion} is vulnerable to CVE-2026-25157 - upgrade to v2026.1.29+`,
                             file: 'package.json',
                             fixable: false,
-                            fix: 'Upgrade openclaw to v2026.1.29 or later: npm install openclaw@latest',
+                            fix: 'npm install openclaw@latest',
+                            guidance: 'CVE-2026-25157 (CVSS 7.8) allows OS command injection via unescaped SSH project paths. Upgrade to v2026.1.29 or later which includes the fix.',
                         });
                     }
                     else {
@@ -5629,7 +5782,8 @@ dist/
                             message: `OpenClaw ${openclawVersion} is vulnerable to CVE-2026-24763 - upgrade to v2026.1.29+`,
                             file: 'package.json',
                             fixable: false,
-                            fix: 'Upgrade openclaw to v2026.1.29 or later: npm install openclaw@latest',
+                            fix: 'npm install openclaw@latest',
+                            guidance: 'CVE-2026-24763 (CVSS 8.8) allows command injection through unsafe PATH handling in Docker sandbox. Upgrade to v2026.1.29 or later which includes the fix.',
                         });
                     }
                     else {
@@ -5679,6 +5833,7 @@ dist/
                         file: relativePath,
                         fixable: false,
                         fix: 'Add gateway.controlUi.allowedOrigins with your allowed origins (e.g., ["http://localhost:3000"])',
+                        guidance: 'Without origin restrictions, the control UI can be accessed from any origin. Adding allowedOrigins provides defense-in-depth against cross-origin attacks.',
                     });
                 }
                 else if (hasAuth && hasAllowedOrigins) {
@@ -5816,6 +5971,7 @@ dist/
                         fixable: false,
                         file: memFile,
                         fix: 'Sanitize all memory entries before persistence. Remove __proto__ and constructor keys. Validate $ref URIs.',
+                        guidance: 'Prototype pollution via __proto__ or constructor can alter object behavior. External $ref URIs can load malicious content into agent memory at runtime.',
                     });
                 }
             }
@@ -5844,6 +6000,7 @@ dist/
                             fixable: false,
                             file: cfgFile,
                             fix: 'Enable memory integrity verification: add hash validation or signature checks for persisted context.',
+                            guidance: 'Without integrity checks, an attacker with file access can modify persisted memory to inject malicious instructions that the agent will trust on reload.',
                         });
                     }
                 }
@@ -5872,6 +6029,7 @@ dist/
                             fixable: false,
                             file: cfgFile,
                             fix: 'Set explicit context size limits: maxContextSize, memory.maxEntries, or memory.maxSize.',
+                            guidance: 'Without size limits, an attacker can craft inputs that overflow the context window, pushing safety instructions out of scope and taking over agent behavior.',
                         });
                     }
                 }
@@ -5903,6 +6061,7 @@ dist/
                                 fixable: false,
                                 file: maFile,
                                 fix: 'Enable memory isolation: set sharedMemory.isolation=true or use per-agent memory scopes.',
+                                guidance: 'Shared memory without isolation lets a compromised agent poison context used by all other agents. Use per-agent scopes to prevent cross-agent influence.',
                             });
                         }
                     }
@@ -5939,6 +6098,7 @@ dist/
                                         file: path.relative(targetDir, file),
                                         line: i + 1,
                                         fix: 'Sanitize conversation history before including in system prompts. Strip instruction-like patterns.',
+                                        guidance: 'Unvalidated conversation history concatenated into system prompts enables indirect prompt injection. Attackers can craft messages that inject instructions.',
                                     });
                                     break; // One finding per file
                                 }
@@ -5981,6 +6141,7 @@ dist/
                                 fixable: false,
                                 file: ragFile,
                                 fix: 'Add source verification: set trustedSource=true only for validated endpoints, or enable signatureCheck.',
+                                guidance: 'Unverified RAG sources can be compromised to inject malicious instructions into agent context. Verify sources with signatures or explicit trust markers.',
                             });
                         }
                     }
@@ -6019,6 +6180,7 @@ dist/
                                         file: path.relative(targetDir, file),
                                         line: i + 1,
                                         fix: 'Sanitize retrieved content before including in prompts. Strip instruction-like patterns and markup.',
+                                        guidance: 'Poisoned documents in a vector store can contain prompt injections that override agent behavior when retrieved. Sanitize before including in prompts.',
                                     });
                                     break;
                                 }
@@ -6048,6 +6210,7 @@ dist/
                         fixable: false,
                         file: ragFile,
                         fix: 'Restrict vector store write access. Require authentication for document ingestion.',
+                        guidance: 'Public-writable vector stores let anyone inject poisoned documents. These documents are retrieved by the agent and can influence its responses and behavior.',
                     });
                 }
             }
@@ -6072,6 +6235,7 @@ dist/
                             fixable: false,
                             file: ragFile,
                             fix: 'Enable provenance tracking: set sourceTracking=true to track which source each document came from.',
+                            guidance: 'Without provenance tracking, poisoned content cannot be traced to its source during incident response. Source tracking enables rapid identification and removal.',
                         });
                     }
                 }
@@ -6109,7 +6273,8 @@ dist/
                             message: `${idFile} declares identity without cryptographic key binding`,
                             fixable: false,
                             file: idFile,
-                            fix: 'Run `hackmyagent fix-all --with-aim` to bind identity to an Ed25519 key pair automatically',
+                            fix: 'hackmyagent fix-all --with-aim',
+                            guidance: 'Without cryptographic binding, any agent can impersonate this identity. Ed25519 key pairs provide proof of identity through digital signatures.',
                         });
                     }
                 }
@@ -6127,6 +6292,7 @@ dist/
                             fixable: false,
                             file: idFile,
                             fix: 'Add a verification endpoint: verificationEndpoint URL or oidcIssuer for federated identity.',
+                            guidance: 'Without a verification endpoint, other agents and registries cannot verify identity claims. This enables identity spoofing in multi-agent systems.',
                         });
                     }
                 }
@@ -6150,7 +6316,8 @@ dist/
                         message: 'Agent project has no identity declaration file (agent-card.json, agent.json, aim.json)',
                         fixable: false,
                         file: 'package.json',
-                        fix: 'Run `hackmyagent fix-all --with-aim` to create a cryptographic identity with Ed25519 key pair, audit logging, and trust scoring',
+                        fix: 'hackmyagent fix-all --with-aim',
+                        guidance: 'Without a formal identity declaration, the agent cannot be verified by other agents, registries, or trust frameworks. Creates an Ed25519 key pair with audit logging.',
                     });
                 }
             }
@@ -6188,7 +6355,8 @@ dist/
                         message: `${dnaFile} has no signature or content hash`,
                         fixable: false,
                         file: dnaFile,
-                        fix: 'Run `hackmyagent fix-all --with-aim` to automatically sign behavioral profiles with a cryptographic identity',
+                        fix: 'hackmyagent fix-all --with-aim',
+                        guidance: 'Unsigned behavioral profiles can be silently modified to change agent behavior. Cryptographic signatures enable tamper detection on every load.',
                     });
                 }
                 // DNA-003: No behavioral drift detection
@@ -6204,6 +6372,7 @@ dist/
                         fixable: false,
                         file: dnaFile,
                         fix: 'Enable behavioral drift detection: set baselineHash and driftThreshold for continuous monitoring.',
+                        guidance: 'Without drift detection, gradual behavioral changes (prompt drift, personality shifts) go unnoticed. A baseline hash detects any deviation from expected behavior.',
                     });
                 }
             }
@@ -6237,6 +6406,7 @@ dist/
                         fixable: false,
                         file: foundSoulFile || 'SOUL.md',
                         fix: 'Create agent-dna.json with contentHash of SOUL.md, baselineHash, and signature for integrity verification.',
+                        guidance: 'A behavioral fingerprint enables continuous integrity verification of agent instructions. Without it, modifications to SOUL.md cannot be detected.',
                     });
                 }
             }
@@ -6269,6 +6439,7 @@ dist/
                         fixable: false,
                         file: 'SKILL.md',
                         fix: 'Restrict skill memory access: declare explicit read-only or scoped-write permissions in SKILL.md.',
+                        guidance: 'Skills with unrestricted memory write access can poison agent context, alter future responses, or plant persistent backdoors that survive restarts.',
                     });
                 }
             }
@@ -6297,6 +6468,7 @@ dist/
                                 fixable: false,
                                 file: path.relative(targetDir, file),
                                 fix: 'Add read-only guards or scope memory writes to skill-specific namespaces.',
+                                guidance: 'Unrestricted memory writes from skills can alter agent state across all contexts. Scope writes to skill-specific namespaces to prevent cross-skill interference.',
                             });
                             break; // One per skill dir
                         }
@@ -6454,7 +6626,8 @@ dist/
                     file: relativePath,
                     line: firstLine,
                     fixable: false,
-                    fix: 'Inspect the file with a hex editor (e.g., xxd) to identify and remove invisible Unicode codepoints. Run: xxd ' + shellEscape(relativePath) + ' | grep -iE "e280[8-9a-e]|efbb|efb8|f3a0"',
+                    fix: 'xxd ' + shellEscape(relativePath) + ' | grep -iE "e280[8-9a-e]|efbb|efb8|f3a0"',
+                    guidance: 'Invisible Unicode codepoints (zero-width chars, variation selectors, tag characters, bidi overrides) can hide malicious payloads in source code. This is the GlassWorm attack vector. Inspect with a hex editor and remove all non-functional invisible characters.',
                 });
             }
             // UNICODE-STEGO-002: GlassWorm Decoder Pattern
@@ -6490,7 +6663,8 @@ dist/
                     file: relativePath,
                     line: decoderLine,
                     fixable: false,
-                    fix: 'Review the file for suspicious .codePointAt() logic that decodes hidden data from variation selectors (0xFE00-0xFE0F) or tag characters (0xE0100-0xE01EF). Remove the decoder function and audit the file for tampering.',
+                    fix: 'Review the file for suspicious .codePointAt() logic that decodes hidden data from variation selectors (0xFE00-0xFE0F) or tag characters (0xE0100-0xE01EF). Remove the decoder function.',
+                    guidance: 'The GlassWorm attack encodes malicious payloads in invisible Unicode characters and uses .codePointAt() to decode them at runtime. This is the decoder half of the attack.',
                 });
             }
             // UNICODE-STEGO-003: Eval on Empty String
@@ -6544,7 +6718,8 @@ dist/
                         file: relativePath,
                         line: evalLine,
                         fixable: false,
-                        fix: 'Remove the eval/Function call and inspect the string argument with a hex editor. The string likely contains invisible Unicode characters encoding a malicious payload. Run: node -e "const fs=require(\'fs\'); const s=fs.readFileSync(' + JSON.stringify(relativePath) + ',\'utf8\'); console.log([...s].filter(c=>c.codePointAt(0)>0x200).map(c=>c.codePointAt(0).toString(16)))"',
+                        fix: 'node -e "const fs=require(\'fs\'); const s=fs.readFileSync(' + JSON.stringify(relativePath) + ',\'utf8\'); console.log([...s].filter(c=>c.codePointAt(0)>0x200).map(c=>c.codePointAt(0).toString(16)))"',
+                        guidance: 'eval() or Function() called with mostly invisible characters is a strong indicator of a GlassWorm payload. The string contains hidden Unicode characters encoding malicious code. Remove the eval/Function call and audit the file.',
                     });
                     break; // One finding per file
                 }
@@ -6586,7 +6761,8 @@ dist/
                         file: relativePath,
                         line: tagBlockLine,
                         fixable: false,
-                        fix: 'Inspect the file with a hex editor to identify tag block characters (byte sequence starting with F3 A0). These characters are invisible and have no legitimate use in source code. Run: xxd ' + shellEscape(relativePath) + ' | grep "f3a0"',
+                        fix: 'xxd ' + shellEscape(relativePath) + ' | grep "f3a0"',
+                        guidance: 'Unicode Tag block characters (U+E0000-U+E01EF) are invisible and have no legitimate use in source code. They can encode hidden data or malicious payloads. Remove all tag block characters found.',
                     });
                 }
             }
@@ -6638,7 +6814,8 @@ dist/
                     file: relativePath,
                     line: homoglyphLine,
                     fixable: false,
-                    fix: 'Inspect the file for characters that look like Latin letters but are actually Cyrillic, Greek, or Fullwidth. Replace them with their ASCII equivalents. Run: node -e "const fs=require(\'fs\'); [...fs.readFileSync(' + JSON.stringify(relativePath) + ',\'utf8\')].forEach((c,i)=>{const cp=c.codePointAt(0); if(cp>0x7F && cp<0xFFFF) console.log(i, cp.toString(16), c)})"',
+                    fix: 'node -e "const fs=require(\'fs\'); [...fs.readFileSync(' + JSON.stringify(relativePath) + ',\'utf8\')].forEach((c,i)=>{const cp=c.codePointAt(0); if(cp>0x7F && cp<0xFFFF) console.log(i, cp.toString(16), c)})"',
+                    guidance: 'Homoglyph confusables (Cyrillic/Greek/Fullwidth characters that look like Latin letters) can create variable names that appear identical in code review but reference different values at runtime. Replace with ASCII equivalents.',
                 });
             }
         }
@@ -6689,7 +6866,8 @@ dist/
                                 fixable: false,
                                 file: path.relative(targetDir, file),
                                 line: i + 1,
-                                fix: 'Download to temp file, verify checksum, then execute: curl -o /tmp/install.sh URL && echo "EXPECTED_SHA256 /tmp/install.sh" | sha256sum -c && bash /tmp/install.sh',
+                                fix: 'curl -o /tmp/install.sh URL && echo "EXPECTED_SHA256 /tmp/install.sh" | sha256sum -c && bash /tmp/install.sh',
+                                guidance: 'Piping curl directly to sh executes whatever the remote server returns. A compromised or MITM-ed server can inject arbitrary code. Always download, verify, then execute.',
                             });
                         }
                     }
@@ -6731,7 +6909,8 @@ dist/
                             fixable: false,
                             file: path.relative(targetDir, file),
                             line: i + 1,
-                            fix: 'Require non-empty digest; fail verification if digest is missing. Compute with: sha256sum <artifact>',
+                            fix: 'sha256sum <artifact>',
+                            guidance: 'Empty digest fields bypass integrity verification entirely. Require non-empty digests and fail builds when they are missing, so tampered artifacts cannot pass.',
                         });
                     }
                 }
@@ -6759,6 +6938,7 @@ dist/
                             file: path.relative(targetDir, file),
                             line: i + 1,
                             fix: 'Require non-empty digest; fail verification if digest is missing instead of skipping the check.',
+                            guidance: 'Skipping digest verification when the value is falsy means an attacker can remove the digest field to bypass integrity checks. Treat missing digest as a hard failure.',
                         });
                     }
                 }
@@ -6804,6 +6984,7 @@ dist/
                                 file: path.relative(targetDir, file),
                                 line: i + 1,
                                 fix: 'Gate policy reload behind operator authentication, not agent output or user requests.',
+                                guidance: 'User-reachable policy reload paths allow attackers to modify security policies via crafted requests. Only operators (authenticated admins) should trigger policy changes.',
                             });
                         }
                     }
@@ -6851,6 +7032,7 @@ dist/
                             file: path.relative(targetDir, file),
                             line: i + 1,
                             fix: 'Pass credentials via environment variables or stdin, not command-line arguments.',
+                            guidance: 'CLI arguments are visible in process listings (ps aux), shell history, and log files. Environment variables and stdin are not exposed to other processes.',
                         });
                     }
                 }
@@ -6895,6 +7077,7 @@ dist/
                             file: path.relative(targetDir, file),
                             line: i + 1,
                             fix: 'Use execFile() or spawn() with array arguments instead of exec() with string interpolation.',
+                            guidance: 'exec() passes the entire string to /bin/sh, which interprets shell metacharacters. execFile() and spawn() with arrays bypass the shell entirely, preventing injection.',
                         });
                     }
                 }
@@ -6939,7 +7122,8 @@ dist/
                             fixable: false,
                             file: path.relative(targetDir, file),
                             line: i + 1,
-                            fix: 'Use mktemp for all temporary files; add trap EXIT for cleanup: TMPDIR=$(mktemp -d) && trap "rm -rf $TMPDIR" EXIT',
+                            fix: 'TMPDIR=$(mktemp -d) && trap "rm -rf $TMPDIR" EXIT',
+                            guidance: 'Hardcoded /tmp paths are predictable and enable symlink attacks (CWE-377). An attacker can pre-create a symlink at the expected path to redirect writes to sensitive files.',
                         });
                     }
                 }
@@ -6979,7 +7163,8 @@ dist/
                             fixable: false,
                             file: path.relative(targetDir, file),
                             line: i + 1,
-                            fix: 'Use an explicit env var allowlist instead of spreading process.env: env: { PATH: process.env.PATH, NODE_ENV: process.env.NODE_ENV }',
+                            fix: 'env: { PATH: process.env.PATH, NODE_ENV: process.env.NODE_ENV }',
+                            guidance: 'Spreading process.env leaks all environment variables (including API keys, tokens, database URLs) to child processes. Use an explicit allowlist of only the variables the child needs.',
                         });
                     }
                 }
@@ -7039,6 +7224,7 @@ dist/
                     file: path.relative(targetDir, verify.verifyFile),
                     line: verify.verifyLine,
                     fix: 'Copy artifact to temp dir, verify the copy, execute from the copy (atomic verify-then-execute in the same function).',
+                    guidance: 'When verify and execute are in separate files, an attacker can swap the artifact between verification and use (TOCTOU). Atomic verify-then-execute eliminates this race window.',
                 });
             }
         }
@@ -7077,6 +7263,7 @@ dist/
                             file: path.relative(targetDir, file),
                             line: i + 1,
                             fix: 'Use json.load() or a restricted deserializer instead of pickle for untrusted data.',
+                            guidance: 'pickle.load() can execute arbitrary Python code during deserialization. A crafted pickle payload achieves full remote code execution.',
                         });
                     }
                     if (/yaml\.load\s*\(/.test(line) && !/Loader\s*=\s*SafeLoader/.test(line) && !/safe_load/.test(line)) {
@@ -7093,6 +7280,7 @@ dist/
                             file: path.relative(targetDir, file),
                             line: i + 1,
                             fix: 'Use yaml.safe_load() or yaml.load(data, Loader=yaml.SafeLoader).',
+                            guidance: 'yaml.load() without SafeLoader can construct arbitrary Python objects, including those that execute code. SafeLoader restricts to basic data types.',
                         });
                     }
                     if (/\beval\s*\(/.test(line) || /\bexec\s*\(/.test(line)) {
@@ -7109,6 +7297,7 @@ dist/
                             file: path.relative(targetDir, file),
                             line: i + 1,
                             fix: 'Replace eval/exec with ast.literal_eval() for data parsing, or use a safe DSL.',
+                            guidance: 'eval() and exec() execute arbitrary code. If input originates from untrusted sources (user input, network, files), this is a direct code injection vector.',
                         });
                     }
                 }
@@ -7136,6 +7325,7 @@ dist/
                             file: path.relative(targetDir, file),
                             line: i + 1,
                             fix: 'Use JSON.parse() for data, or a sandboxed evaluator for expressions.',
+                            guidance: 'eval() executes arbitrary JavaScript. If the string comes from user input, network data, or files, an attacker can inject any code.',
                         });
                     }
                     if (/new\s+Function\s*\(/.test(line)) {
@@ -7152,6 +7342,7 @@ dist/
                             file: path.relative(targetDir, file),
                             line: i + 1,
                             fix: 'Use JSON.parse() for data, or a sandboxed evaluator for expressions.',
+                            guidance: 'new Function() is equivalent to eval() -- it creates executable code from strings. If the string source is untrusted, this enables arbitrary code execution.',
                         });
                     }
                     if (/JSON5\.parse/.test(line)) {
@@ -7168,6 +7359,7 @@ dist/
                             file: path.relative(targetDir, file),
                             line: i + 1,
                             fix: 'Use JSON.parse() instead of JSON5.parse() for untrusted data.',
+                            guidance: 'JSON5 accepts comments, trailing commas, and unquoted keys, expanding the parsing surface. For untrusted input, strict JSON.parse() reduces ambiguity and attack surface.',
                         });
                     }
                 }
@@ -7216,6 +7408,7 @@ dist/
                                 file: path.relative(targetDir, file),
                                 line: i + 1,
                                 fix: 'Remove messaging APIs from base sandbox policy; require explicit operator opt-in per deployment.',
+                                guidance: 'Pre-allowed messaging APIs (Telegram, Discord, Slack, webhook.site) enable agents to exfiltrate data without user approval. Require explicit operator opt-in per deployment.',
                             });
                         }
                     }
@@ -7264,33 +7457,38 @@ dist/
                 fixReplacement: '$1127.0.0.1',
                 severity: 'critical',
                 description: 'Ollama server configured to listen on all interfaces. Our research found 294K+ exposed AI services on the internet — many are Ollama instances.',
-                fix: 'Set OLLAMA_HOST=127.0.0.1 to restrict to localhost. If remote access is needed, use a reverse proxy with authentication.' },
+                fix: 'Set OLLAMA_HOST=127.0.0.1 to restrict to localhost. If remote access is needed, use a reverse proxy with authentication.',
+                guidance: 'Our research found 294K+ exposed AI services on the internet. Public Ollama instances allow anyone to run inference, steal models, or use your GPU resources.' },
             { id: 'LLM-001', name: 'Ollama Port Exposed', service: 'Ollama',
                 pattern: /^(?!.*127\.0\.0\.1).*["']?11434["']?\s*:\s*["']?11434["']?/,
                 fixPattern: /(["']?)11434(["']?\s*:\s*["']?11434["']?)/,
                 fixReplacement: '$1127.0.0.1:11434$2',
                 severity: 'high',
                 description: 'Ollama default port (11434) mapped in container config. Without bind restrictions, this exposes the inference API to the network.',
-                fix: 'Map to localhost only: "127.0.0.1:11434:11434" instead of "11434:11434".' },
+                fix: 'Map to localhost only: "127.0.0.1:11434:11434" instead of "11434:11434".',
+                guidance: 'Docker port mappings without host binding expose the port on all interfaces. Prefix with 127.0.0.1: to restrict to localhost only.' },
             { id: 'LLM-002', name: 'vLLM/LocalAI Public Binding', service: 'vLLM/LocalAI',
                 pattern: /--host\s+0\.0\.0\.0|host:\s*["']?0\.0\.0\.0/i,
                 fixPattern: /(--host\s+|host:\s*["']?)0\.0\.0\.0/i,
                 fixReplacement: '$1127.0.0.1',
                 severity: 'critical',
                 description: 'LLM inference server configured to bind to all interfaces.',
-                fix: 'Use --host 127.0.0.1 or bind to localhost. Use a reverse proxy with auth for remote access.' },
+                fix: 'Use --host 127.0.0.1 or bind to localhost. Use a reverse proxy with auth for remote access.',
+                guidance: 'vLLM and LocalAI bound to 0.0.0.0 expose the inference API to all network interfaces. Anyone on the network can query models or abuse GPU resources.' },
             { id: 'LLM-003', name: 'Text Generation WebUI Exposed', service: 'text-generation-webui',
                 pattern: /--listen\s|--share\s|GRADIO_SERVER_NAME\s*=\s*["']?0\.0\.0\.0/i,
                 fixPattern: /\s*--listen\s?|\s*--share\s?|(GRADIO_SERVER_NAME\s*=\s*["']?)0\.0\.0\.0/gi,
                 fixReplacement: '$1127.0.0.1',
                 severity: 'high',
                 description: 'Text generation UI configured for public access with --listen or --share flag.',
-                fix: 'Remove --listen and --share flags. Access via localhost or SSH tunnel.' },
+                fix: 'Remove --listen and --share flags. Access via localhost or SSH tunnel.',
+                guidance: '--listen binds to all interfaces and --share creates a public Gradio URL. Both expose the text generation UI to the internet without authentication.' },
             { id: 'LLM-004', name: 'OpenAI-Compatible API No Auth', service: 'OpenAI-compatible',
                 pattern: /\/v1\/chat\/completions|\/v1\/completions|\/v1\/models/,
                 severity: 'medium',
                 description: 'Project exposes OpenAI-compatible API endpoints. Verify authentication is enforced.',
-                fix: 'Ensure API key or token authentication is required for all inference endpoints.' },
+                fix: 'Ensure API key or token authentication is required for all inference endpoints.',
+                guidance: 'OpenAI-compatible API endpoints without authentication allow anyone to query your models, consume compute resources, and potentially extract training data.' },
         ];
         for (const configDef of llmConfigFiles) {
             const filesToCheck = [configDef.name, ...configDef.altNames];
@@ -7327,6 +7525,7 @@ dist/
                                     fixable: !!check.fixPattern,
                                     fixed,
                                     fix: check.fix,
+                                    guidance: check.guidance,
                                 });
                                 break; // One finding per pattern per file
                             }
@@ -7371,6 +7570,7 @@ dist/
                 severity: 'critical',
                 description: 'Jupyter notebook server configured without authentication or bound to public interface. Our research found exposed Jupyter instances with full code execution on the internet.',
                 fix: 'Set c.NotebookApp.token or c.NotebookApp.password. Bind to 127.0.0.1. Never use --NotebookApp.token=\'\' in production.',
+                guidance: 'Jupyter notebooks allow arbitrary code execution. A publicly accessible instance with no auth gives attackers full shell access on the host machine.',
                 filePatterns: ['jupyter_notebook_config.py', 'jupyter_server_config.py', 'docker-compose.yml', 'docker-compose.yaml', 'Dockerfile'],
                 contentPatterns: [
                     /NotebookApp\.token\s*=\s*['"]{2}/, // Empty token
@@ -7385,6 +7585,7 @@ dist/
                 severity: 'high',
                 description: 'ML demo framework configured for public access. Gradio share links and public Streamlit deployments can expose model inference and data pipelines.',
                 fix: 'Remove share=True from Gradio launch(). For Streamlit, add authentication or use private deployment.',
+                guidance: 'Gradio share links create public URLs that bypass network security. Streamlit on 0.0.0.0 exposes the app to the internet. Both can leak model inference and data pipelines.',
                 filePatterns: ['*.py', 'app.py', 'main.py', 'streamlit_app.py', 'demo.py'],
                 contentPatterns: [
                     /\.launch\s*\([^)]*share\s*=\s*True/, // Gradio share=True
@@ -7397,6 +7598,7 @@ dist/
                 severity: 'high',
                 description: 'MLflow tracking server configured without authentication. Exposed MLflow instances leak experiment data, model artifacts, and parameters.',
                 fix: 'Configure MLflow with --backend-store-uri and authentication. Use a reverse proxy with auth for remote access.',
+                guidance: 'Exposed MLflow instances leak experiment data, model artifacts, hyperparameters, and metrics. Add authentication before exposing to any network.',
                 filePatterns: ['docker-compose.yml', 'docker-compose.yaml', 'Dockerfile', 'Makefile', '*.sh'],
                 contentPatterns: [
                     /mlflow\s+server\s+.*--host\s+0\.0\.0\.0/i,
@@ -7409,6 +7611,7 @@ dist/
                 severity: 'high',
                 description: 'LangChain LangServe endpoint configured for public access. Exposed LangServe instances allow arbitrary chain invocation.',
                 fix: 'Add authentication middleware to LangServe routes. Bind to 127.0.0.1 for local-only access.',
+                guidance: 'LangServe exposes LangChain chains as REST endpoints. Without auth, anyone can invoke arbitrary chain operations, potentially accessing sensitive data or incurring costs.',
                 filePatterns: ['*.py', 'app.py', 'main.py', 'server.py'],
                 contentPatterns: [
                     /add_routes\s*\(/, // LangServe route
@@ -7479,6 +7682,7 @@ dist/
                                         fixable: isFixable,
                                         fixed,
                                         fix: check.fix,
+                                        guidance: check.guidance,
                                     });
                                     break;
                                 }
@@ -7528,6 +7732,7 @@ dist/
                     file: relativePath,
                     fixable: false,
                     fix: 'Add authentication requirements to your agent card. Restrict task submission to authenticated clients.',
+                    guidance: 'A2A agent cards make your agent discoverable on the network. Without authentication requirements, any client can submit tasks and consume resources or access sensitive data.',
                     details: { hasAuth, capabilities: agentCard.capabilities },
                 });
                 break; // Found one, no need to check other paths
@@ -7559,6 +7764,7 @@ dist/
                                 line: i + 1,
                                 fixable: false,
                                 fix: 'Add authentication middleware to /tasks/send and /tasks/get endpoints. Require API key or bearer token.',
+                                guidance: 'Unauthenticated A2A task endpoints allow anyone to submit tasks to your agent. This can lead to resource abuse, data exfiltration, or unauthorized actions.',
                             });
                             break;
                         }
@@ -7604,6 +7810,7 @@ dist/
                     file: relativePath,
                     fixable: false,
                     fix: 'Remove .well-known/mcp from public-facing directories, or restrict access via web server configuration. Never include credentials in discovery files.',
+                    guidance: 'MCP discovery files make servers publicly discoverable. If they contain credentials, those are exposed to anyone who requests the URL. Restrict access or remove from public directories.',
                 });
                 break;
             }
@@ -7685,6 +7892,7 @@ dist/
                                     fixable: true,
                                     fixed,
                                     fix: `Move credentials to server-side environment variables. Never include API keys in client-side code or static assets. Use a backend proxy for API calls.`,
+                                    guidance: 'Credentials in web-served files (HTML, JS, CSS) are visible to anyone who views the page source. API keys in client-side code can be extracted and abused for unauthorized access.',
                                 });
                                 break;
                             }
@@ -7700,6 +7908,768 @@ dist/
         }
         return findings;
     }
+    /**
+     * CODEINJ-001: exec() with template literal interpolation
+     * Detects shell injection via exec/execSync called with template literals.
+     */
+    async checkCodeInjection(targetDir, _autoFix) {
+        const findings = [];
+        const files = await this.walkDirectory(targetDir, ['.ts', '.js', '.mjs'], 0, 2);
+        // Match exec( or execSync( followed by a backtick (template literal)
+        // Do NOT match execFile or execFileSync (those use array args, safe)
+        const pattern = /\b(?<!File)exec(?:Sync)?\s*\(\s*`/g;
+        for (const file of files.slice(0, 100)) {
+            try {
+                const stat = await fs.stat(file);
+                if (stat.size > MAX_FILE_SIZE)
+                    continue;
+                const content = await fs.readFile(file, 'utf-8');
+                const lines = content.split('\n');
+                const relativePath = path.relative(targetDir, file);
+                for (let i = 0; i < lines.length; i++) {
+                    if (lines[i].length > MAX_LINE_LENGTH)
+                        continue;
+                    pattern.lastIndex = 0;
+                    if (pattern.test(lines[i])) {
+                        findings.push({
+                            checkId: 'CODEINJ-001',
+                            name: 'exec() with template literal interpolation',
+                            description: 'exec() or execSync() called with a template literal allows shell injection. User-controlled values in the template can break out of the intended command.',
+                            category: 'code-injection',
+                            severity: 'critical',
+                            passed: false,
+                            message: `Shell injection risk: exec() with template literal in ${relativePath}`,
+                            file: relativePath,
+                            line: i + 1,
+                            fixable: false,
+                            fix: 'Use execFile() or execFileSync() with an array of arguments instead of exec() with string interpolation.',
+                            guidance: 'Template literals in exec() are interpreted by /bin/sh, allowing shell metacharacters in interpolated values to execute arbitrary commands. Array-based APIs bypass the shell.',
+                        });
+                        break; // One finding per file
+                    }
+                }
+            }
+            catch { /* skip unreadable files */ }
+        }
+        return findings;
+    }
+    /**
+     * INSTALL-001: curl|sh without checksum in shell scripts
+     * Detects piped-to-shell install patterns in .sh files.
+     */
+    async checkInstallScripts(targetDir, _autoFix) {
+        const findings = [];
+        const files = await this.walkDirectory(targetDir, ['.sh'], 0, 2);
+        const pattern = /\b(curl|wget)\b[^|]*\|\s*(ba)?sh\b/g;
+        for (const file of files.slice(0, 100)) {
+            try {
+                const stat = await fs.stat(file);
+                if (stat.size > MAX_FILE_SIZE)
+                    continue;
+                const content = await fs.readFile(file, 'utf-8');
+                const lines = content.split('\n');
+                const relativePath = path.relative(targetDir, file);
+                for (let i = 0; i < lines.length; i++) {
+                    if (lines[i].length > MAX_LINE_LENGTH)
+                        continue;
+                    pattern.lastIndex = 0;
+                    if (pattern.test(lines[i])) {
+                        findings.push({
+                            checkId: 'INSTALL-001',
+                            name: 'curl|sh without checksum verification',
+                            description: 'Shell script downloads and executes code via curl|sh or wget|sh without verifying a checksum. A MITM or compromised server can inject arbitrary code.',
+                            category: 'supply-chain',
+                            severity: 'critical',
+                            passed: false,
+                            message: `Unsafe pipe-to-shell install in ${relativePath}`,
+                            file: relativePath,
+                            line: i + 1,
+                            fixable: false,
+                            fix: 'Download the script to a file first, verify its checksum (sha256sum), then execute it.',
+                            guidance: 'Piping directly to sh executes whatever the remote server returns without verification. A compromised or MITM-ed server can inject arbitrary code into your system.',
+                        });
+                        break;
+                    }
+                }
+            }
+            catch { /* skip unreadable files */ }
+        }
+        return findings;
+    }
+    /**
+     * CLIPASS-001: Credentials passed as CLI arguments
+     * Detects --token, --password, --api-key, --secret followed by variable interpolation.
+     */
+    async checkCLICredentialPassthrough(targetDir, _autoFix) {
+        const findings = [];
+        const files = await this.walkDirectory(targetDir, ['.ts', '.js', '.mjs'], 0, 2);
+        const pattern = /--(token|password|api[_-]?key|secret|auth)\s*[=\s]\s*[`$"']\s*\$?\{?|["']--(token|password|api[_-]?key|secret|auth)["']/g;
+        for (const file of files.slice(0, 100)) {
+            try {
+                const stat = await fs.stat(file);
+                if (stat.size > MAX_FILE_SIZE)
+                    continue;
+                const content = await fs.readFile(file, 'utf-8');
+                const lines = content.split('\n');
+                const relativePath = path.relative(targetDir, file);
+                for (let i = 0; i < lines.length; i++) {
+                    if (lines[i].length > MAX_LINE_LENGTH)
+                        continue;
+                    pattern.lastIndex = 0;
+                    if (pattern.test(lines[i])) {
+                        // Verify it's in a spawn/exec context
+                        const contextStart = Math.max(0, i - 5);
+                        const context = lines.slice(contextStart, i + 1).join('\n');
+                        if (/\b(exec\w*|spawn\w*|fork|run)\b/i.test(context)) {
+                            findings.push({
+                                checkId: 'CLIPASS-001',
+                                name: 'Credentials passed as CLI arguments',
+                                description: 'Credentials are passed as command-line arguments (--token, --password, etc.) with variable interpolation. CLI args are visible in process listings (ps aux) and shell history.',
+                                category: 'credential-exposure',
+                                severity: 'high',
+                                passed: false,
+                                message: `Credentials passed as CLI arguments in ${relativePath}`,
+                                file: relativePath,
+                                line: i + 1,
+                                fixable: false,
+                                fix: 'Pass credentials via environment variables, stdin, or a config file instead of CLI arguments.',
+                                guidance: 'CLI arguments are visible to all users via ps aux, logged in shell history, and often captured in audit logs. Environment variables and stdin are not exposed to other processes.',
+                            });
+                            break;
+                        }
+                    }
+                }
+            }
+            catch { /* skip unreadable files */ }
+        }
+        return findings;
+    }
+    /**
+     * INTEGRITY-001: Digest/hash verification bypass on falsy value
+     * Detects patterns like `if (digest &&` or `if (hash &&` where empty value skips check.
+     */
+    async checkIntegrityBypass(targetDir, _autoFix) {
+        const findings = [];
+        const files = await this.walkDirectory(targetDir, ['.ts', '.js', '.mjs'], 0, 2);
+        const pattern = /if\s*\(\s*(digest|hash|checksum|signature|integrity)\s*&&/g;
+        for (const file of files.slice(0, 100)) {
+            try {
+                const stat = await fs.stat(file);
+                if (stat.size > MAX_FILE_SIZE)
+                    continue;
+                const content = await fs.readFile(file, 'utf-8');
+                const lines = content.split('\n');
+                const relativePath = path.relative(targetDir, file);
+                for (let i = 0; i < lines.length; i++) {
+                    if (lines[i].length > MAX_LINE_LENGTH)
+                        continue;
+                    pattern.lastIndex = 0;
+                    if (pattern.test(lines[i])) {
+                        findings.push({
+                            checkId: 'INTEGRITY-001',
+                            name: 'Integrity check bypass on falsy value',
+                            description: 'Integrity verification (digest/hash/checksum) is guarded by a truthiness check. If the value is empty, undefined, or null, the entire integrity check is silently skipped.',
+                            category: 'integrity-bypass',
+                            severity: 'critical',
+                            passed: false,
+                            message: `Integrity check bypass risk in ${relativePath}`,
+                            file: relativePath,
+                            line: i + 1,
+                            fixable: false,
+                            fix: 'Require the integrity value to be present. Throw an error if digest/hash is missing rather than skipping verification.',
+                            guidance: 'A truthiness check on digest/hash silently skips verification when the value is empty. An attacker can remove the digest from a manifest to bypass all integrity checks.',
+                        });
+                        break;
+                    }
+                }
+            }
+            catch { /* skip unreadable files */ }
+        }
+        return findings;
+    }
+    /**
+     * TOCTOU-001: Verify then use without atomic operation
+     * Detects files that verify and then execute on the same path without atomicity.
+     */
+    async checkTOCTOU(targetDir, _autoFix) {
+        const findings = [];
+        const files = await this.walkDirectory(targetDir, ['.ts', '.js', '.mjs'], 0, 2);
+        for (const file of files.slice(0, 100)) {
+            try {
+                const stat = await fs.stat(file);
+                if (stat.size > MAX_FILE_SIZE)
+                    continue;
+                const content = await fs.readFile(file, 'utf-8');
+                const relativePath = path.relative(targetDir, file);
+                // Look for verify/check followed by execute/apply/run on the same path variable
+                const hasVerify = /\b(verify|validate|check)(File|Path|Hash|Integrity|Signature|Digest|Config)?\s*\(/i.test(content);
+                const hasExecute = /\b(execute|apply|run|install|load|import)(File|Path|Module|Script|Plugin|Config)?\s*\(/i.test(content);
+                const hasFilePath = /\b(filePath|targetPath|scriptPath|modulePath|configPath)\b/.test(content);
+                // Also detect inline TOCTOU: multiple readFile/readFileSync calls on the same path variable
+                const readCalls = content.match(/\breadFile(Sync)?\s*\(\s*(\w+)/g) || [];
+                const hasMultipleReads = readCalls.length >= 2;
+                if ((hasVerify && hasExecute && hasFilePath) || (hasMultipleReads && hasFilePath)) {
+                    // Check that there's no file locking or atomic operation (ignore comments)
+                    const codeLines = content.split('\n').filter(l => !l.trimStart().startsWith('//') && !l.trimStart().startsWith('#') && !l.trimStart().startsWith('*'));
+                    const codeContent = codeLines.join('\n');
+                    const hasAtomic = /\b(atomic|lock|flock|rename|O_EXCL|O_CREAT)\b/i.test(codeContent);
+                    if (!hasAtomic) {
+                        // Find the line with verify for reporting
+                        const lines = content.split('\n');
+                        let verifyLine = 0;
+                        const verifyPattern = /\b(verify|validate|check)(File|Path|Hash|Integrity|Signature|Digest|Config)?\s*\(|\breadFileSync?\s*\(/i;
+                        for (let i = 0; i < lines.length; i++) {
+                            if (verifyPattern.test(lines[i])) {
+                                verifyLine = i + 1;
+                                break;
+                            }
+                        }
+                        findings.push({
+                            checkId: 'TOCTOU-001',
+                            name: 'Time-of-check-time-of-use race condition',
+                            description: 'File is verified (checksum/signature) and then used (executed/loaded) in separate operations without file locking. An attacker can replace the file between verify and use.',
+                            category: 'toctou-race',
+                            severity: 'high',
+                            passed: false,
+                            message: `TOCTOU risk: verify-then-use without atomic operation in ${relativePath}`,
+                            file: relativePath,
+                            line: verifyLine,
+                            fixable: false,
+                            fix: 'Use atomic file operations: verify and load in a single locked operation, or copy to a temp location before verification.',
+                            guidance: 'TOCTOU races allow file replacement between verification and use. An attacker can swap a verified file with a malicious one in the time window between the two operations.',
+                        });
+                    }
+                }
+            }
+            catch { /* skip unreadable files */ }
+        }
+        return findings;
+    }
+    /**
+     * TMPPATH-001: Hardcoded /tmp paths without mktemp
+     * Detects writes to /tmp/ with hardcoded paths in shell scripts.
+     */
+    async checkTmpPaths(targetDir, _autoFix) {
+        const findings = [];
+        const files = await this.walkDirectory(targetDir, ['.sh'], 0, 2);
+        const pattern = /(>|>>)\s*\/tmp\/|(-o)\s+\/tmp\/|\s\/tmp\/\S+/g;
+        for (const file of files.slice(0, 100)) {
+            try {
+                const stat = await fs.stat(file);
+                if (stat.size > MAX_FILE_SIZE)
+                    continue;
+                const content = await fs.readFile(file, 'utf-8');
+                const lines = content.split('\n');
+                const relativePath = path.relative(targetDir, file);
+                // Only flag if the script does NOT actually use mktemp (ignore comments)
+                const nonCommentLines = lines.filter(l => !l.trimStart().startsWith('#'));
+                if (/\bmktemp\b/.test(nonCommentLines.join('\n')))
+                    continue;
+                for (let i = 0; i < lines.length; i++) {
+                    if (lines[i].length > MAX_LINE_LENGTH)
+                        continue;
+                    pattern.lastIndex = 0;
+                    if (pattern.test(lines[i])) {
+                        findings.push({
+                            checkId: 'TMPPATH-001',
+                            name: 'Hardcoded /tmp path without mktemp',
+                            description: 'Shell script writes to a hardcoded /tmp/ path. Another user or process can create a symlink at that path to redirect writes (symlink attack).',
+                            category: 'tmppath-attack',
+                            severity: 'high',
+                            passed: false,
+                            message: `Hardcoded /tmp path in ${relativePath}`,
+                            file: relativePath,
+                            line: i + 1,
+                            fixable: false,
+                            fix: 'Use mktemp to create a unique temporary file/directory instead of hardcoded /tmp paths.',
+                            guidance: 'Predictable /tmp paths enable symlink attacks (CWE-377). Another user can create a symlink at the expected path, redirecting writes to sensitive files like /etc/passwd.',
+                        });
+                        break;
+                    }
+                }
+            }
+            catch { /* skip unreadable files */ }
+        }
+        return findings;
+    }
+    /**
+     * DOCKERINJ-001: Docker exec with variable interpolation
+     * Detects docker exec commands with unquoted variable expansion.
+     */
+    async checkDockerInjection(targetDir, _autoFix) {
+        const findings = [];
+        const files = await this.walkDirectory(targetDir, ['.sh'], 0, 2);
+        const pattern = /docker\s+exec\b.*?(\$\{?\w+\}?)/g;
+        for (const file of files.slice(0, 100)) {
+            try {
+                const stat = await fs.stat(file);
+                if (stat.size > MAX_FILE_SIZE)
+                    continue;
+                const content = await fs.readFile(file, 'utf-8');
+                const lines = content.split('\n');
+                const relativePath = path.relative(targetDir, file);
+                for (let i = 0; i < lines.length; i++) {
+                    if (lines[i].length > MAX_LINE_LENGTH)
+                        continue;
+                    const line = lines[i];
+                    // Detect docker exec with any variable interpolation (quoted or not)
+                    if (/docker\s+exec\b/.test(line) && /\$\{?\w+\}?/.test(line)) {
+                        findings.push({
+                            checkId: 'DOCKERINJ-001',
+                            name: 'Docker exec with variable interpolation',
+                            description: 'docker exec command uses shell variable expansion. An attacker who controls the variable value can inject additional docker commands or escape the container context, even when quoted (e.g., in bash -c contexts).',
+                            category: 'code-injection',
+                            severity: 'high',
+                            passed: false,
+                            message: `Variable interpolation in docker exec in ${relativePath}`,
+                            file: relativePath,
+                            line: i + 1,
+                            fixable: false,
+                            fix: 'Avoid passing user-controlled variables to docker exec. Validate and sanitize all inputs, and avoid bash -c with interpolated variables.',
+                            guidance: 'Variable interpolation in docker exec allows command injection. If the variable contains shell metacharacters, an attacker can execute arbitrary commands inside or escape the container.',
+                        });
+                        break;
+                    }
+                }
+            }
+            catch { /* skip unreadable files */ }
+        }
+        return findings;
+    }
+    /**
+     * ENVLEAK-001: process.env spread to child process
+     * Detects passing all environment variables (including secrets) to child processes.
+     */
+    async checkEnvLeak(targetDir, _autoFix) {
+        const findings = [];
+        const files = await this.walkDirectory(targetDir, ['.ts', '.js', '.mjs'], 0, 2);
+        const spreadPattern = /env:\s*\{\s*\.\.\.process\.env/g;
+        const directPattern = /\benv:\s*process\.env\b/g;
+        for (const file of files.slice(0, 100)) {
+            try {
+                const stat = await fs.stat(file);
+                if (stat.size > MAX_FILE_SIZE)
+                    continue;
+                const content = await fs.readFile(file, 'utf-8');
+                const lines = content.split('\n');
+                const relativePath = path.relative(targetDir, file);
+                for (let i = 0; i < lines.length; i++) {
+                    if (lines[i].length > MAX_LINE_LENGTH)
+                        continue;
+                    spreadPattern.lastIndex = 0;
+                    directPattern.lastIndex = 0;
+                    if (spreadPattern.test(lines[i]) || directPattern.test(lines[i])) {
+                        // Verify it's in a spawn/exec context
+                        const contextStart = Math.max(0, i - 5);
+                        const context = lines.slice(contextStart, i + 3).join('\n');
+                        if (/\b(spawn|exec|fork|execFile|execSync|spawnSync)\b/.test(context)) {
+                            findings.push({
+                                checkId: 'ENVLEAK-001',
+                                name: 'process.env spread to child process',
+                                description: 'All environment variables (including secrets like API keys, database passwords) are passed to a child process via env: process.env or { ...process.env }.',
+                                category: 'env-leak',
+                                severity: 'high',
+                                passed: false,
+                                message: `Full environment leaked to child process in ${relativePath}`,
+                                file: relativePath,
+                                line: i + 1,
+                                fixable: false,
+                                fix: 'Pass only the specific environment variables the child process needs: env: { PATH: process.env.PATH, NODE_ENV: process.env.NODE_ENV }.',
+                                guidance: 'Spreading process.env passes all secrets (API keys, DB passwords, tokens) to child processes. A compromised or malicious child can read and exfiltrate these credentials.',
+                            });
+                            break;
+                        }
+                    }
+                }
+            }
+            catch { /* skip unreadable files */ }
+        }
+        return findings;
+    }
+    /**
+     * SANDBOX-005: Messaging API pre-allowed in sandbox policy
+     * Detects pre-allowed URLs for messaging services in sandbox policies.
+     */
+    async checkSandboxMessaging(targetDir, _autoFix) {
+        const findings = [];
+        // Scan YAML/JSON files in policies/ and config/ directories
+        const policyDirs = ['policies', 'config', '.openclaw'];
+        const policyExts = ['.yml', '.yaml', '.json'];
+        for (const dirName of policyDirs) {
+            const dirPath = path.join(targetDir, dirName);
+            try {
+                await fs.access(dirPath);
+            }
+            catch {
+                continue;
+            }
+            const files = await this.walkDirectory(dirPath, policyExts, 0, 2);
+            const messagingPattern = /\b(telegram|slack|discord|webhook\.site|requestbin|pipedream)\b/gi;
+            for (const file of files.slice(0, 50)) {
+                try {
+                    const stat = await fs.stat(file);
+                    if (stat.size > MAX_FILE_SIZE)
+                        continue;
+                    const content = await fs.readFile(file, 'utf-8');
+                    const lines = content.split('\n');
+                    const relativePath = path.relative(targetDir, file);
+                    for (let i = 0; i < lines.length; i++) {
+                        if (lines[i].length > MAX_LINE_LENGTH)
+                            continue;
+                        messagingPattern.lastIndex = 0;
+                        const match = messagingPattern.exec(lines[i]);
+                        if (match) {
+                            // Check if this is in an allow/whitelist context
+                            const contextStart = Math.max(0, i - 3);
+                            const context = lines.slice(contextStart, i + 1).join('\n').toLowerCase();
+                            if (/\b(allow\w*|whitelist\w*|permit\w*|pre[_-]?allow\w*|approved|trusted)\b/.test(context)) {
+                                findings.push({
+                                    checkId: 'SANDBOX-005',
+                                    name: 'Messaging API pre-allowed in sandbox policy',
+                                    description: `Messaging service (${match[1]}) is pre-allowed in sandbox policy. An attacker who gains code execution inside the sandbox can exfiltrate data via this channel without triggering additional permission prompts.`,
+                                    category: 'sandbox-escape',
+                                    severity: 'high',
+                                    passed: false,
+                                    message: `Messaging API (${match[1]}) pre-allowed in ${relativePath}`,
+                                    file: relativePath,
+                                    line: i + 1,
+                                    fixable: false,
+                                    fix: 'Remove messaging services from pre-allowed URLs. Require explicit user approval for outbound messaging.',
+                                    guidance: 'Pre-allowed messaging APIs let sandbox code exfiltrate data silently via Telegram, Slack, or Discord without triggering permission prompts. Require explicit approval for each outbound message.',
+                                });
+                                break;
+                            }
+                        }
+                    }
+                }
+                catch { /* skip unreadable files */ }
+            }
+        }
+        return findings;
+    }
+    /**
+     * WEBEXPOSE-001: CLAUDE.md in web-served directories
+     * WEBEXPOSE-002: .env files in web-served directories
+     * WEBEXPOSE-003: Sensitive config files in web-served directories
+     */
+    async checkWebExposedFiles(targetDir, _autoFix) {
+        const findings = [];
+        const webDirs = ['public', 'static', 'dist', 'build', 'out', 'www'];
+        // Track seen real paths to avoid duplicates on case-insensitive filesystems
+        const seenPaths = new Set();
+        // WEBEXPOSE-001: CLAUDE.md in web directories
+        const claudeFiles = ['CLAUDE.md', 'claude.md'];
+        // WEBEXPOSE-002: .env files in web directories
+        const envFiles = ['.env', '.env.local', '.env.production'];
+        // WEBEXPOSE-003: Sensitive config files in web directories
+        const configFiles = ['mcp.json', 'config.json', 'settings.json', 'openclaw.json'];
+        const configDirs = ['.claude'];
+        for (const webDir of webDirs) {
+            const dirPath = path.join(targetDir, webDir);
+            try {
+                await fs.access(dirPath);
+            }
+            catch {
+                continue;
+            }
+            // WEBEXPOSE-001: CLAUDE.md
+            for (const claudeFile of claudeFiles) {
+                const filePath = path.join(dirPath, claudeFile);
+                try {
+                    await fs.access(filePath);
+                    const realPath = await fs.realpath(filePath);
+                    if (seenPaths.has(realPath))
+                        continue;
+                    seenPaths.add(realPath);
+                    const relativePath = path.relative(targetDir, filePath);
+                    findings.push({
+                        checkId: 'WEBEXPOSE-001',
+                        name: 'CLAUDE.md in web-served directory',
+                        description: 'CLAUDE.md found in a web-served directory. This file often contains system prompts, instructions, and operational details that should not be publicly accessible.',
+                        category: 'web-exposure',
+                        severity: 'high',
+                        passed: false,
+                        message: `CLAUDE.md exposed in web directory: ${relativePath}`,
+                        file: relativePath,
+                        fixable: false,
+                        fix: 'Move CLAUDE.md out of the web-served directory. Add it to .gitignore and your build exclusion list.',
+                        guidance: 'CLAUDE.md contains system prompts and operational instructions. Publicly accessible CLAUDE.md reveals agent behavior, security controls, and attack surface to potential adversaries.',
+                    });
+                }
+                catch { /* file doesn't exist */ }
+            }
+            // WEBEXPOSE-002: .env files
+            for (const envFile of envFiles) {
+                const filePath = path.join(dirPath, envFile);
+                try {
+                    await fs.access(filePath);
+                    const relativePath = path.relative(targetDir, filePath);
+                    findings.push({
+                        checkId: 'WEBEXPOSE-002',
+                        name: '.env file in web-served directory',
+                        description: 'Environment file found in a web-served directory. This file likely contains API keys, database credentials, and other secrets accessible to anyone who visits the site.',
+                        category: 'web-exposure',
+                        severity: 'critical',
+                        passed: false,
+                        message: `Environment file exposed in web directory: ${relativePath}`,
+                        file: relativePath,
+                        fixable: false,
+                        fix: 'Remove .env files from web-served directories immediately. Store environment files in the project root (outside public/) and rotate any exposed credentials.',
+                        guidance: '.env files in web directories are directly downloadable by anyone. All credentials in these files should be considered compromised and rotated immediately.',
+                    });
+                }
+                catch { /* file doesn't exist */ }
+            }
+            // WEBEXPOSE-003: Sensitive config files
+            for (const configFile of configFiles) {
+                const filePath = path.join(dirPath, configFile);
+                try {
+                    await fs.access(filePath);
+                    const relativePath = path.relative(targetDir, filePath);
+                    findings.push({
+                        checkId: 'WEBEXPOSE-003',
+                        name: 'Sensitive config file in web-served directory',
+                        description: `Configuration file (${configFile}) found in a web-served directory. This may expose MCP server configs, API endpoints, or other sensitive operational details.`,
+                        category: 'web-exposure',
+                        severity: 'high',
+                        passed: false,
+                        message: `Config file exposed in web directory: ${relativePath}`,
+                        file: relativePath,
+                        fixable: false,
+                        fix: `Move ${configFile} out of the web-served directory. Serve only the minimal configuration needed by the client.`,
+                        guidance: 'Configuration files in web directories expose MCP server addresses, API endpoints, authentication settings, and other operational details that aid attackers in targeting your infrastructure.',
+                    });
+                }
+                catch { /* file doesn't exist */ }
+            }
+            // WEBEXPOSE-003: Sensitive config directories
+            for (const configDir of configDirs) {
+                const configDirPath = path.join(dirPath, configDir);
+                try {
+                    await fs.access(configDirPath);
+                    const relativePath = path.relative(targetDir, configDirPath);
+                    findings.push({
+                        checkId: 'WEBEXPOSE-003',
+                        name: 'Sensitive config directory in web-served directory',
+                        description: `.claude/ directory found in a web-served directory. This directory contains Claude Code settings and may expose system prompts or tool configurations.`,
+                        category: 'web-exposure',
+                        severity: 'high',
+                        passed: false,
+                        message: `Config directory exposed in web directory: ${relativePath}`,
+                        file: relativePath,
+                        fixable: false,
+                        fix: 'Remove the .claude/ directory from web-served directories. Add it to your build exclusion list.',
+                        guidance: 'The .claude/ directory contains Claude Code settings, tool permissions, and potentially system prompts. Public access reveals your AI tool configuration and attack surface.',
+                    });
+                }
+                catch { /* directory doesn't exist */ }
+            }
+        }
+        return findings;
+    }
+    /**
+     * SOUL-OVERRIDE-001: Skill content can override SOUL.md
+     * Checks if SKILL.md and SOUL.md are loaded into the same prompt context without trust boundaries.
+     */
+    async checkSoulOverride(targetDir, _autoFix) {
+        const findings = [];
+        // Path 1: Look for system-prompt files that load both soul and skill content
+        const promptFiles = await this.walkDirectory(targetDir, ['.ts', '.js', '.mjs'], 0, 2);
+        const targetFiles = promptFiles.filter(f => {
+            const name = path.basename(f).toLowerCase();
+            return name.includes('system-prompt') || name.includes('systemprompt') ||
+                name.includes('prompt-builder') || name.includes('promptbuilder') ||
+                name.includes('context-builder') || name.includes('contextbuilder');
+        });
+        for (const file of targetFiles.slice(0, 20)) {
+            try {
+                const stat = await fs.stat(file);
+                if (stat.size > MAX_FILE_SIZE)
+                    continue;
+                const content = await fs.readFile(file, 'utf-8');
+                const relativePath = path.relative(targetDir, file);
+                const hasSoul = /\b(soul|SOUL\.md|soulContent|soul_content)\b/.test(content);
+                const hasSkill = /\b(skill|SKILL\.md|skillContent|skill_content)\b/.test(content);
+                if (hasSoul && hasSkill) {
+                    // Check for trust boundary markers
+                    const hasBoundary = /\b(trustBoundary|trust_boundary|TRUST_BOUNDARY|sandboxed|isolated|untrusted)\b/.test(content);
+                    if (!hasBoundary) {
+                        const lines = content.split('\n');
+                        let soulLine = 0;
+                        for (let i = 0; i < lines.length; i++) {
+                            if (/\b(soul|SOUL\.md)\b/i.test(lines[i])) {
+                                soulLine = i + 1;
+                                break;
+                            }
+                        }
+                        findings.push({
+                            checkId: 'SOUL-OVERRIDE-001',
+                            name: 'Skill content can override SOUL.md',
+                            description: 'SOUL.md and SKILL.md content are loaded into the same prompt context without trust boundary markers. A malicious skill can include instructions that override the agent\'s core identity and safety rules.',
+                            category: 'soul-injection',
+                            severity: 'high',
+                            passed: false,
+                            message: `Soul and skill content mixed without trust boundaries in ${relativePath}`,
+                            file: relativePath,
+                            line: soulLine,
+                            fixable: false,
+                            fix: 'Add trust boundaries between SOUL.md (trusted) and SKILL.md (untrusted) content. Mark skill content as untrusted and instruct the model to not follow instructions from skill content.',
+                            guidance: 'Without trust boundaries, a malicious SKILL.md can include instructions that override the agent\'s core identity, safety rules, and behavioral constraints defined in SOUL.md.',
+                        });
+                    }
+                }
+            }
+            catch { /* skip unreadable files */ }
+        }
+        // Path 2: Check for co-existing SOUL.md and SKILL.md files
+        // When both exist in the same directory without trust markers in SKILL.md,
+        // a malicious skill can override the agent's core identity
+        if (findings.length === 0) {
+            const soulPath = path.join(targetDir, 'SOUL.md');
+            const skillPath = path.join(targetDir, 'SKILL.md');
+            try {
+                await fs.access(soulPath);
+                await fs.access(skillPath);
+                // Both exist -- check SKILL.md for override patterns
+                const skillContent = await fs.readFile(skillPath, 'utf-8');
+                const hasTrustBoundary = /\b(trustBoundary|trust_boundary|TRUST_BOUNDARY|sandboxed|isolated|untrusted)\b/.test(skillContent);
+                if (!hasTrustBoundary) {
+                    // Check if SKILL.md contains override/injection patterns
+                    const hasOverridePattern = /\b(override|ignore|suspend|bypass|disregard)\b.*\b(rules?|safety|guidelines?|instructions?|prompt)\b/i.test(skillContent);
+                    const hasEscalation = /\b(admin|system|root|debug)\s*(mode|access|privilege)/i.test(skillContent);
+                    if (hasOverridePattern || hasEscalation) {
+                        findings.push({
+                            checkId: 'SOUL-OVERRIDE-001',
+                            name: 'Skill content can override SOUL.md',
+                            description: 'SKILL.md co-exists with SOUL.md and contains instructions that attempt to override safety rules. A malicious skill can include instructions that override the agent\'s core identity and safety rules.',
+                            category: 'soul-injection',
+                            severity: 'high',
+                            passed: false,
+                            message: 'SKILL.md contains override patterns that can bypass SOUL.md safety rules',
+                            file: 'SKILL.md',
+                            line: 1,
+                            fixable: false,
+                            fix: 'Add trust boundaries between SOUL.md (trusted) and SKILL.md (untrusted) content. Mark skill content as untrusted and instruct the model to not follow instructions from skill content.',
+                            guidance: 'SKILL.md contains override/escalation patterns that can bypass SOUL.md safety rules. Mark skill content as untrusted so the model knows not to follow instructions from it.',
+                        });
+                    }
+                }
+            }
+            catch { /* one or both files don't exist */ }
+        }
+        return findings;
+    }
+    /**
+     * MEM-006: Memory store without input sanitization
+     * Detects memory/persistence plugins that store user-provided text without sanitization.
+     */
+    async checkMemoryStoreSanitization(targetDir, _autoFix) {
+        const findings = [];
+        const files = await this.walkDirectory(targetDir, ['.ts', '.js', '.mjs'], 0, 2);
+        // Look for store/save/persist calls with text/content parameter (method or function)
+        const storePattern = /(?:\.|^|\s|\()(store|save|persist|insert|upsert|push)\s*\(\s*\{[^}]*(text|content|message|input)\b/g;
+        for (const file of files.slice(0, 100)) {
+            try {
+                const stat = await fs.stat(file);
+                if (stat.size > MAX_FILE_SIZE)
+                    continue;
+                const content = await fs.readFile(file, 'utf-8');
+                const lines = content.split('\n');
+                const relativePath = path.relative(targetDir, file);
+                // Skip if file has sanitization functions
+                if (/\b(sanitize|sanitise|escapeHtml|htmlEncode|stripTags|DOMPurify|xss)\b/.test(content))
+                    continue;
+                for (let i = 0; i < lines.length; i++) {
+                    if (lines[i].length > MAX_LINE_LENGTH)
+                        continue;
+                    storePattern.lastIndex = 0;
+                    if (storePattern.test(lines[i])) {
+                        // Check surrounding context for validation
+                        const contextStart = Math.max(0, i - 5);
+                        const context = lines.slice(contextStart, i).join('\n');
+                        if (!/\b(validate|sanitize|filter|clean|escape|strip)\b/.test(context)) {
+                            findings.push({
+                                checkId: 'MEM-006',
+                                name: 'Memory store without input sanitization',
+                                description: 'User-provided text is stored in a persistence layer without sanitization. An attacker can inject malicious content (prompt injection, XSS payloads) that persists and affects future sessions.',
+                                category: 'memory-poisoning',
+                                severity: 'high',
+                                passed: false,
+                                message: `Unsanitized input stored in memory/persistence in ${relativePath}`,
+                                file: relativePath,
+                                line: i + 1,
+                                fixable: false,
+                                fix: 'Sanitize all user-provided text before storing. Strip instruction-like patterns and HTML/script content.',
+                                guidance: 'Unsanitized user input persisted to memory can contain prompt injections or XSS payloads that affect future sessions. Sanitize before storage to prevent persistent poisoning.',
+                            });
+                            break;
+                        }
+                    }
+                }
+            }
+            catch { /* skip unreadable files */ }
+        }
+        return findings;
+    }
+    /**
+     * AGENT-CRED-001: No credential output protection in system prompt
+     * Checks system prompts that mention exec/shell but lack credential protection instructions.
+     */
+    async checkAgentCredentialProtection(targetDir, _autoFix) {
+        const findings = [];
+        // System prompt files to check
+        const promptFileNames = ['SOUL.md', 'CLAUDE.md', 'system-prompt.md', 'system-prompt.txt'];
+        const promptFilePatterns = ['system-prompt.ts', 'system-prompt.js', 'systemprompt.ts', 'systemprompt.js'];
+        const allFiles = [];
+        // Check known file names
+        for (const name of promptFileNames) {
+            const filePath = path.join(targetDir, name);
+            try {
+                await fs.access(filePath);
+                allFiles.push({ path: filePath, rel: name });
+            }
+            catch { /* skip */ }
+        }
+        // Check for system-prompt source files
+        const srcFiles = await this.walkDirectory(targetDir, ['.ts', '.js', '.md', '.txt'], 0, 2);
+        for (const file of srcFiles) {
+            const basename = path.basename(file).toLowerCase();
+            if (promptFilePatterns.some(p => basename === p.toLowerCase())) {
+                allFiles.push({ path: file, rel: path.relative(targetDir, file) });
+            }
+        }
+        for (const { path: filePath, rel: relativePath } of allFiles.slice(0, 20)) {
+            try {
+                const stat = await fs.stat(filePath);
+                if (stat.size > MAX_FILE_SIZE)
+                    continue;
+                const content = await fs.readFile(filePath, 'utf-8');
+                // Check if the prompt mentions exec/shell capabilities
+                const hasExecCapability = /\b(exec|execute|shell|command|subprocess|spawn|terminal|bash)\b/i.test(content);
+                if (!hasExecCapability)
+                    continue;
+                // Check if there's credential protection language
+                const hasCredProtection = /\b(credential|secret|api[_\s-]?key|environment[_\s]variable|never\s+(print|echo|output|display|log)\s+(secret|credential|key|token|password))\b/i.test(content);
+                if (!hasCredProtection) {
+                    findings.push({
+                        checkId: 'AGENT-CRED-001',
+                        name: 'No credential output protection in system prompt',
+                        description: 'System prompt grants exec/shell capabilities but does not include instructions to protect credentials from being output. An attacker can craft prompts that cause the agent to echo environment variables or credential files.',
+                        category: 'agent-credential',
+                        severity: 'medium',
+                        passed: false,
+                        message: `System prompt in ${relativePath} grants exec access without credential protection instructions`,
+                        file: relativePath,
+                        fixable: false,
+                        fix: 'Add credential protection instructions to the system prompt: "Never print, echo, or output API keys, tokens, passwords, or environment variable values. Reference credentials only by variable name."',
+                        guidance: 'Agents with exec/shell access can be tricked into echoing environment variables containing API keys and passwords. Explicit instructions in the system prompt add a defense layer.',
+                    });
+                }
+            }
+            catch { /* skip unreadable files */ }
+        }
+        return findings;
+    }
     /** Helper: recursively find files in web-served directories */
     async findWebFiles(dir, extensions, depth, rootDir) {
         if (depth > 3)