shieldcortex 4.4.0 → 4.6.0

package/dist/xray/guidance.d.ts

@@ -0,0 +1,26 @@
+/**
+ * X-Ray Finding Guidance
+ *
+ * Human-readable explanations for each finding category.
+ * Tells users what a finding means, what to do about it,
+ * and whether it's likely a false positive.
+ */
+import type { XRayCategory } from './types.js';
+export interface FindingGuidance {
+    /** Plain-language explanation of what this means */
+    whatItMeans: string;
+    /** What the user should do */
+    whatToDo: string;
+    /** When this is typically a false positive */
+    falsePositiveNote: string;
+    /** How serious this usually is: 'usually-safe' | 'investigate' | 'act-now' */
+    urgency: 'usually-safe' | 'investigate' | 'act-now';
+}
+/**
+ * Get human-readable guidance for a finding.
+ */
+export declare function getGuidance(category: XRayCategory, severity: string): FindingGuidance;
+/**
+ * Check if a file path looks like a system/cache file that commonly triggers false positives.
+ */
+export declare function isLikelySystemFile(filePath: string): boolean;

package/dist/xray/guidance.js

@@ -0,0 +1,180 @@
+/**
+ * X-Ray Finding Guidance
+ *
+ * Human-readable explanations for each finding category.
+ * Tells users what a finding means, what to do about it,
+ * and whether it's likely a false positive.
+ */
+const GUIDANCE = {
+    'prompt-injection': {
+        default: {
+            whatItMeans: 'This file contains text that looks like it\'s trying to override AI instructions — phrases like "ignore previous instructions" or "you are now in developer mode". If an AI agent reads this file, it could be tricked into doing something unintended.',
+            whatToDo: 'If this is a file you wrote or trust, it\'s probably fine (security research, test fixtures, documentation about prompt injection). If it came from an untrusted source — an npm package, a downloaded file, a PR from someone you don\'t know — quarantine it and investigate.',
+            falsePositiveNote: 'Common in security research files, AI safety documentation, and test fixtures that deliberately contain injection examples.',
+            urgency: 'investigate',
+        },
+        bySeverity: {
+            critical: { urgency: 'act-now', whatToDo: 'This contains strong injection patterns. Quarantine immediately if the source is untrusted. Do not let AI agents process this file until you\'ve reviewed it.' },
+        },
+    },
+    'eval-exec': {
+        default: {
+            whatItMeans: 'This file uses dynamic code execution — things like eval(), new Function(), or vm.runInContext(). These can run arbitrary code at runtime, which is how many supply chain attacks work.',
+            whatToDo: 'If this is your own code or a well-known library, it\'s likely intentional (bundlers, template engines, and test frameworks use eval legitimately). If it\'s in an unfamiliar dependency, investigate why it needs to execute code dynamically.',
+            falsePositiveNote: 'Very common in bundlers (webpack, esbuild), template engines (EJS, Handlebars), and testing frameworks. Also appears in legitimate serialisation libraries.',
+            urgency: 'investigate',
+        },
+    },
+    'shell-execution': {
+        default: {
+            whatItMeans: 'This file runs shell commands using child_process, exec, or spawn. It can execute anything your terminal can — install software, delete files, or send data to external servers.',
+            whatToDo: 'If this is a build tool, CLI utility, or dev script you recognise, it\'s expected. If it\'s inside an npm package you didn\'t write, check exactly what commands it runs. Packages should not need shell access at runtime.',
+            falsePositiveNote: 'Normal in CLI tools, build scripts, and developer utilities. Suspicious in libraries that claim to be pure JavaScript (e.g. a "string formatting" package that spawns shells).',
+            urgency: 'investigate',
+        },
+        bySeverity: {
+            critical: { urgency: 'act-now', whatToDo: 'Shell execution in a context where it shouldn\'t be needed. Review the exact commands being run. If this is an npm package, check if the commands make sense for what the package claims to do.' },
+        },
+    },
+    'network-beacon': {
+        default: {
+            whatItMeans: 'This file makes network requests (fetch, http.get, XMLHttpRequest) at load time — not when called by your code, but as soon as the file is imported. This is how data exfiltration works: the package phones home the moment it\'s installed.',
+            whatToDo: 'If this is an analytics SDK, telemetry module, or API client, it may be intentional. If it\'s a utility library that shouldn\'t need network access, this is a red flag. Check where the requests go.',
+            falsePositiveNote: 'Expected in analytics SDKs, telemetry, update checkers, and API clients. Suspicious in utility libraries, parsers, or formatting tools.',
+            urgency: 'investigate',
+        },
+        bySeverity: {
+            critical: { urgency: 'act-now', whatToDo: 'Network requests at module load time are the #1 supply chain attack pattern. Check the destination URL immediately. If it points anywhere you don\'t recognise, quarantine this file.' },
+        },
+    },
+    'obfuscation': {
+        default: {
+            whatItMeans: 'This file contains code that\'s been deliberately made hard to read — hex-encoded strings, base64 decoding chains, String.fromCharCode sequences, or extremely long single lines. Legitimate code is rarely obfuscated this way.',
+            whatToDo: 'If this is a minified production bundle (like a .min.js file), it\'s normal — minification looks like obfuscation to a scanner. If this is source code that should be readable, it\'s suspicious. Check if there\'s a readable version elsewhere in the package.',
+            falsePositiveNote: 'Very common in minified bundles, compiled WASM, production builds, and binary data files. Also triggers on long JSON files and machine-generated code.',
+            urgency: 'usually-safe',
+        },
+        bySeverity: {
+            high: { urgency: 'investigate', whatToDo: 'Heavy obfuscation beyond simple minification. Check if this file has a source map or unminified equivalent. If not, investigate what it does.' },
+        },
+    },
+    'steganography': {
+        default: {
+            whatItMeans: 'This file appears to contain hidden data — extra bytes after the end of an image, data embedded in metadata, or content disguised as a different file type. Attackers sometimes hide payloads this way.',
+            whatToDo: 'If this is a system log, browser cache file, or macOS diagnostic file, it\'s almost certainly a false positive — these file formats naturally contain multiple data sections that look like different formats. If this is an image or document from an untrusted source, investigate further.',
+            falsePositiveNote: 'Very common false positive on system files, browser caches, macOS .tracev3 logs, Outlook cache files, and any binary file that contains compressed data sections.',
+            urgency: 'usually-safe',
+        },
+        bySeverity: {
+            critical: { urgency: 'investigate', whatToDo: 'Multiple format signatures detected. This could be a polyglot file designed to bypass security filters. If this is a system file, it\'s safe to ignore. If it came from an external source, quarantine and examine.' },
+        },
+    },
+    'unicode-trick': {
+        default: {
+            whatItMeans: 'This file contains invisible Unicode characters — zero-width spaces, right-to-left overrides, or homoglyph characters that look identical to normal letters but aren\'t. These can make code appear to do one thing while actually doing another.',
+            whatToDo: 'This is almost never legitimate in source code. Check the file in a hex editor to see the actual characters. If they\'re in comments or strings, someone may be trying to hide instructions from human reviewers while keeping them visible to AI agents.',
+            falsePositiveNote: 'Can appear in files with international text (Arabic, Hebrew), copy-pasted content from web pages, or markdown with special formatting.',
+            urgency: 'investigate',
+        },
+        bySeverity: {
+            critical: { urgency: 'act-now', whatToDo: 'Multiple invisible characters in source code. This is the classic prompt injection steganography attack. Quarantine this file and inspect in a hex editor before allowing any AI agent to read it.' },
+        },
+    },
+    'metadata-exploit': {
+        default: {
+            whatItMeans: 'This file\'s metadata (package.json fields, image EXIF data, document properties) contains text that looks like AI instructions. Attackers embed directives in metadata because AI agents often read it without the user noticing.',
+            whatToDo: 'Check the metadata fields manually. If description, keywords, or author fields contain instructions ("ignore", "execute", "override"), that\'s a supply chain injection attempt. If it\'s normal descriptive text, it\'s fine.',
+            falsePositiveNote: 'Can trigger on packages with detailed descriptions that happen to use instructional language.',
+            urgency: 'investigate',
+        },
+    },
+    'persistence-hook': {
+        default: {
+            whatItMeans: 'This package has lifecycle scripts (postinstall, preinstall, prepare) that run automatically when you install it. Most packages don\'t need these — they\'re the most common vector for supply chain attacks.',
+            whatToDo: 'Check what the scripts actually do. Legitimate uses: native module compilation (like node-gyp), husky git hooks, or initial setup. Suspicious uses: downloading files, running encoded commands, or making network requests.',
+            falsePositiveNote: 'Common in packages with native bindings (better-sqlite3, sharp, node-canvas) and developer tooling (husky, lint-staged).',
+            urgency: 'investigate',
+        },
+    },
+    'covert-channel': {
+        default: {
+            whatItMeans: 'This file appears to use hidden communication channels — DNS exfiltration, steganographic data encoding, or other methods to send data without obvious network calls.',
+            whatToDo: 'This is rarely a false positive. Review the code carefully to understand what data is being sent and where. If you can\'t explain why this code exists, quarantine the file.',
+            falsePositiveNote: 'Rare false positive. May trigger on DNS libraries, image processing code, or encoding utilities.',
+            urgency: 'act-now',
+        },
+    },
+    'dependency-risk': {
+        default: {
+            whatItMeans: 'This package has risky dependency patterns — wildcard version ranges (\"*\"), git URLs instead of registry versions, multiple suspicious lifecycle hooks, or an unusual number of recent version bumps.',
+            whatToDo: 'Check if the dependency versions are pinned. Wildcard ranges mean you could get a compromised version without realising. Git URLs bypass npm\'s security scanning. Consider locking to specific versions.',
+            falsePositiveNote: 'Common in early-stage packages, monorepo setups, and packages that depend on pre-release versions.',
+            urgency: 'usually-safe',
+        },
+        bySeverity: {
+            high: { urgency: 'investigate', whatToDo: 'Multiple dependency risk signals combined. This package has an unusual dependency profile — review each flagged dependency individually.' },
+        },
+    },
+    'ai-directive': {
+        default: {
+            whatItMeans: 'This file contains text that looks like instructions meant for an AI agent — phrases like "you must", "system prompt", "assistant instructions", or role-play directives. If an agent reads this file, it could alter its behaviour.',
+            whatToDo: 'If this is a .cursorrules, CLAUDE.md, or similar AI configuration file, it\'s expected. If it\'s inside an npm package, a data file, or somewhere AI instructions shouldn\'t be, it\'s a prompt injection attempt. Quarantine and review.',
+            falsePositiveNote: 'Expected in AI agent configuration files (CLAUDE.md, .cursorrules, system prompts). Suspicious in library code, data files, or package metadata.',
+            urgency: 'investigate',
+        },
+        bySeverity: {
+            critical: { urgency: 'act-now', whatToDo: 'Strong AI directive patterns in a file that shouldn\'t contain them. This looks like a deliberate prompt injection. Quarantine immediately and do not let AI agents process this file.' },
+        },
+    },
+};
+/**
+ * Get human-readable guidance for a finding.
+ */
+export function getGuidance(category, severity) {
+    const entry = GUIDANCE[category];
+    if (!entry) {
+        return {
+            whatItMeans: 'An unusual pattern was detected in this file.',
+            whatToDo: 'Review the file manually to determine if this is expected behaviour.',
+            falsePositiveNote: 'May be a false positive depending on the file type and context.',
+            urgency: 'investigate',
+        };
+    }
+    const base = entry.default;
+    const override = entry.bySeverity?.[severity];
+    if (!override)
+        return base;
+    return {
+        ...base,
+        ...override,
+    };
+}
+/**
+ * Check if a file path looks like a system/cache file that commonly triggers false positives.
+ */
+export function isLikelySystemFile(filePath) {
+    const lower = filePath.toLowerCase();
+    const systemPatterns = [
+        '/library/caches/',
+        '/library/application support/',
+        '/library/group containers/',
+        '/library/logs/',
+        '/library/preferences/',
+        '/library/saved application state/',
+        '/private/var/',
+        '/var/db/',
+        '/var/log/',
+        '/var/folders/',
+        '/.shieldcortex/',
+        '/.npm/',
+        '/.cache/',
+        '/cache_data/',
+        '/code cache/',
+        '/gpucache/',
+        '/serviceworker/',
+        '.tracev3',
+        '.diagnostics',
+        '.plist',
+    ];
+    return systemPatterns.some(p => lower.includes(p));
+}

package/dist/xray/index.js

@@ -17,6 +17,7 @@ import { inspectNpmPackage } from './npm-inspector.js';
 import { calculateTrustScore } from './trust-score.js';
 import { formatXRayReport, formatXRayMarkdown } from './report.js';
 import { watchDirectory } from './watch.js';
+import { appendActivity, appendHistory, createHistoryEntry } from './activity.js';
 export { calculateTrustScore } from './trust-score.js';
 export { detectPatterns, detectFilenameDirectives } from './patterns.js';
 export { scanFile } from './file-scanner.js';
@@ -111,17 +112,7 @@ export async function handleXRayCommand(args) {
         process.exit(1);
     }
     const target = positional[0];
-    // Watch mode — delegate to watchDirectory
-    if (watchMode) {
-        const resolved = path.resolve(target);
-        if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
-            console.error(`--watch requires a directory target: ${resolved}`);
-            process.exit(1);
-        }
-        await watchDirectory(resolved, deep, { json: jsonOutput });
-        return;
-    }
-    // Deep scan requires Pro
+    // Deep scan requires Pro (checked before watch mode to prevent bypass)
     if (deep) {
         try {
             requireFeature('xray_deep');
@@ -131,13 +122,24 @@ export async function handleXRayCommand(args) {
             process.exit(1);
         }
     }
-    // Check free tier limit
+    // Check free tier limit (checked before watch mode to prevent bypass)
     if (!checkFreeLimit()) {
         console.error('Daily scan limit reached. Upgrade to Pro for unlimited scans.');
         console.error('  https://shieldcortex.ai/pricing');
         process.exit(1);
     }
+    // Watch mode — delegate to watchDirectory (after license/usage gates)
+    if (watchMode) {
+        const resolved = path.resolve(target);
+        if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+            console.error(`--watch requires a directory target: ${resolved}`);
+            process.exit(1);
+        }
+        await watchDirectory(resolved, deep, { json: jsonOutput });
+        return;
+    }
     let result;
+    let targetType = 'file';
     if (isNpmPackageName(target)) {
         // NPM package inspection
         if (!isFeatureEnabled('xray_deep')) {
@@ -146,6 +148,7 @@ export async function handleXRayCommand(args) {
             console.error('  Upgrade: https://shieldcortex.ai/pricing');
             process.exit(1);
         }
+        targetType = 'npm';
         result = await inspectNpmPackage(target, deep);
     }
     else {
@@ -157,9 +160,11 @@ export async function handleXRayCommand(args) {
         }
         const stat = fs.statSync(resolved);
         if (stat.isDirectory()) {
+            targetType = 'dir';
             result = await scanDirectory(resolved, deep);
         }
         else if (stat.isFile()) {
+            targetType = 'file';
             const findings = await scanFile(resolved, deep);
             const { score, riskLevel } = calculateTrustScore(findings);
             result = {
@@ -179,6 +184,22 @@ export async function handleXRayCommand(args) {
     }
     // Track usage
     incrementUsage();
+    appendHistory(createHistoryEntry(result, targetType));
+    appendActivity({
+        kind: 'scan',
+        status: result.findings.length === 0 ? 'pass' : result.riskLevel === 'LOW' ? 'warn' : 'detected',
+        target: result.target,
+        targetType,
+        deepScan: result.deepScan,
+        trustScore: result.trustScore,
+        riskLevel: result.riskLevel,
+        filesScanned: result.filesScanned,
+        findingCount: result.findings.length,
+        scannedAt: result.scannedAt.toISOString(),
+        summary: result.findings.length === 0
+            ? 'No findings detected'
+            : `${result.findings.length} findings across ${result.filesScanned} files`,
+    });
     // Output
     if (jsonOutput) {
         console.log(JSON.stringify(result, null, 2));

package/dist/xray/memory-guard.d.ts

@@ -19,7 +19,7 @@ export interface MemoryGuardResult {
  * @param content - The memory content to scan
  * @param title - Optional title/name for the memory entry
  * @returns { allowed, findings, riskLevel }
- *   - allowed: true if trust score >= 40 (MEDIUM or better)
+ *   - allowed: true if trust score >= 60 (LOW risk or better)
  *   - findings: all detected X-Ray findings
  *   - riskLevel: SAFE | LOW | MEDIUM | HIGH | CRITICAL
  */

package/dist/xray/memory-guard.js

@@ -15,7 +15,7 @@ import { calculateTrustScore } from './trust-score.js';
  * @param content - The memory content to scan
  * @param title - Optional title/name for the memory entry
  * @returns { allowed, findings, riskLevel }
- *   - allowed: true if trust score >= 40 (MEDIUM or better)
+ *   - allowed: true if trust score >= 60 (LOW risk or better)
  *   - findings: all detected X-Ray findings
  *   - riskLevel: SAFE | LOW | MEDIUM | HIGH | CRITICAL
  */
@@ -29,7 +29,7 @@ export function xrayMemoryContent(content, title) {
     }
     const { score, riskLevel } = calculateTrustScore(findings);
     return {
-        allowed: score >= 40,
+        allowed: score >= 60,
         findings,
         riskLevel,
     };

package/dist/xray/npm-inspector.js

@@ -126,7 +126,14 @@ function extractTarBuffer(buf, outDir) {
         const prefixEnd = header.indexOf(0, 345);
         const prefix = header.subarray(345, Math.min(prefixEnd, 500)).toString('utf-8');
         const fullName = prefix ? `${prefix}/${name}` : name;
-        const filePath = path.join(outDir, fullName);
+        // Path traversal protection: resolve and verify the target stays within outDir
+        const filePath = path.resolve(outDir, fullName);
+        const resolvedOutDir = path.resolve(outDir);
+        if (!filePath.startsWith(resolvedOutDir + path.sep) && filePath !== resolvedOutDir) {
+            // Malicious entry trying to escape extraction directory — skip it
+            offset += 512 + Math.ceil(size / 512) * 512;
+            continue;
+        }
         offset += 512; // Move past header
         if (typeFlag === 48 || typeFlag === 0) { // Regular file ('0' or null)
             if (size > 0) {

package/dist/xray/preinstall.js

@@ -11,6 +11,7 @@ import fs from 'fs';
 import path from 'path';
 import { detectPatterns } from './patterns.js';
 import { calculateTrustScore } from './trust-score.js';
+import { appendActivity } from './activity.js';
 // ── Constants ───────────────────────────────────────────────
 const SEVERITY_RANK = {
     critical: 4,
@@ -30,6 +31,19 @@ export async function handlePreinstallCheck() {
     const pkgJsonPath = path.join(cwd, 'package.json');
     if (!fs.existsSync(pkgJsonPath)) {
         console.log('ShieldCortex X-Ray pre-install check: PASS (no package.json found)');
+        appendActivity({
+            kind: 'preinstall',
+            status: 'pass',
+            target: pkgJsonPath,
+            targetType: 'file',
+            deepScan: false,
+            trustScore: 100,
+            riskLevel: 'SAFE',
+            filesScanned: 0,
+            findingCount: 0,
+            scannedAt: new Date().toISOString(),
+            summary: 'Skipped: no package.json found',
+        });
         process.exit(0);
     }
     let pkgContent;
@@ -38,6 +52,19 @@ export async function handlePreinstallCheck() {
     }
     catch {
         console.log('ShieldCortex X-Ray pre-install check: PASS (could not read package.json)');
+        appendActivity({
+            kind: 'preinstall',
+            status: 'warn',
+            target: pkgJsonPath,
+            targetType: 'file',
+            deepScan: false,
+            trustScore: 100,
+            riskLevel: 'SAFE',
+            filesScanned: 0,
+            findingCount: 0,
+            scannedAt: new Date().toISOString(),
+            summary: 'Skipped: could not read package.json',
+        });
         process.exit(0);
     }
     let pkg;
@@ -46,6 +73,19 @@ export async function handlePreinstallCheck() {
     }
     catch {
         console.log('ShieldCortex X-Ray pre-install check: PASS (invalid package.json)');
+        appendActivity({
+            kind: 'preinstall',
+            status: 'warn',
+            target: pkgJsonPath,
+            targetType: 'file',
+            deepScan: false,
+            trustScore: 100,
+            riskLevel: 'SAFE',
+            filesScanned: 0,
+            findingCount: 0,
+            scannedAt: new Date().toISOString(),
+            summary: 'Skipped: invalid package.json',
+        });
         process.exit(0);
     }
     // Scan scripts section only (lightweight, fast)
@@ -70,6 +110,19 @@ export async function handlePreinstallCheck() {
         : path.basename(cwd);
     if (allFindings.length === 0) {
         console.log(`ShieldCortex X-Ray pre-install check: PASS — ${label} (score: ${score})`);
+        appendActivity({
+            kind: 'preinstall',
+            status: 'pass',
+            target: pkgJsonPath,
+            targetType: 'file',
+            deepScan: false,
+            trustScore: score,
+            riskLevel,
+            filesScanned: 1,
+            findingCount: 0,
+            scannedAt: new Date().toISOString(),
+            summary: `Preinstall check passed for ${label}`,
+        });
         process.exit(0);
     }
     // Print findings
@@ -87,9 +140,35 @@ export async function handlePreinstallCheck() {
     // HIGH or CRITICAL → block
     if (maxSeverity >= SEVERITY_RANK.high) {
         console.log('ShieldCortex X-Ray pre-install check: FAIL — blocking install due to HIGH+ risk findings');
+        appendActivity({
+            kind: 'preinstall',
+            status: 'blocked',
+            target: pkgJsonPath,
+            targetType: 'file',
+            deepScan: false,
+            trustScore: score,
+            riskLevel,
+            filesScanned: 1,
+            findingCount: allFindings.length,
+            scannedAt: new Date().toISOString(),
+            summary: `Blocked install for ${label}`,
+        });
         process.exit(1);
     }
     // MEDIUM or below → warn but allow
     console.log('ShieldCortex X-Ray pre-install check: PASS (warnings found, but below blocking threshold)');
+    appendActivity({
+        kind: 'preinstall',
+        status: 'warn',
+        target: pkgJsonPath,
+        targetType: 'file',
+        deepScan: false,
+        trustScore: score,
+        riskLevel,
+        filesScanned: 1,
+        findingCount: allFindings.length,
+        scannedAt: new Date().toISOString(),
+        summary: `Warnings detected for ${label}`,
+    });
     process.exit(0);
 }

package/dist/xray/trust-score.js

@@ -5,10 +5,10 @@
  */
 // ── Penalty weights ─────────────────────────────────────────
 const SEVERITY_PENALTY = {
-    critical: 25,
-    high: 15,
-    medium: 8,
-    low: 3,
+    critical: 60,
+    high: 35,
+    medium: 15,
+    low: 5,
     info: 0,
 };
 // ── Risk level thresholds ───────────────────────────────────

package/dist/xray/types.d.ts

@@ -27,3 +27,22 @@ export interface XRayResult {
     scannedAt: Date;
     deepScan: boolean;
 }
+export type FindingStatus = 'new' | 'reviewed' | 'ignored' | 'resolved' | 'quarantined';
+export interface ActionableXRayFinding extends XRayFinding {
+    /** Unique ID for this finding instance */
+    id: string;
+    /** Which scan/watch session produced this finding */
+    sourceId: string;
+    /** Source type: manual scan or watch detection */
+    sourceKind: 'scan' | 'watch';
+    /** Full path to the target that was scanned */
+    target: string;
+    /** Current lifecycle status */
+    status: FindingStatus;
+    /** When the finding was first detected */
+    detectedAt: string;
+    /** When status was last changed */
+    updatedAt: string;
+    /** Optional note from user when resolving/ignoring */
+    resolutionNote?: string;
+}

package/dist/xray/watch.js

@@ -5,18 +5,54 @@
  * only the changed files, printing new findings as they appear.
  */
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import crypto from 'crypto';
 import { scanFile } from './file-scanner.js';
 import { calculateTrustScore } from './trust-score.js';
+import { appendActivity, emitDetectionEvent, endWatchSession, heartbeatWatchSession, recordWatchSessionEvent, startWatchSession, } from './activity.js';
+import { addFindings } from './findings-store.js';
 // ── Constants ───────────────────────────────────────────────
 const DEBOUNCE_MS = 500;
 const MAX_FILE_SIZE = 10 * 1024 * 1024;
-const IGNORE_DIRS = new Set(['node_modules', '.git', 'dist', 'build']);
+const IGNORE_DIRS = new Set([
+    'node_modules', '.git', '.next', 'dist', 'build', '.cache', '.turbo', '__pycache__', '.venv',
+    '.shieldcortex', 'Library', 'Caches', 'Cache_Data', 'GPUCache', 'Code Cache',
+    'Application Support', 'Group Containers', 'Saved Application State',
+    'Containers', '.Trash', '.npm', '.nvm', '.local',
+]);
+/** Paths that should never be watched — too broad or trigger OS permission dialogs */
+const IGNORE_PATH_PATTERNS = [
+    '/private/var/',
+    '/var/db/',
+    '/var/log/',
+    '/var/folders/',
+    '/System/',
+    '/Applications/',
+    '/usr/',
+    '/Library/', // system Library
+    '/tmp/com.apple.',
+];
 // ── Helpers ─────────────────────────────────────────────────
 function shouldIgnore(filePath) {
     const parts = filePath.split(path.sep);
-    return parts.some(p => IGNORE_DIRS.has(p));
+    if (parts.some(p => IGNORE_DIRS.has(p)))
+        return true;
+    // Resolve symlinks to check the real path
+    let abs;
+    try {
+        abs = fs.realpathSync(path.resolve(filePath));
+    }
+    catch {
+        abs = path.resolve(filePath);
+    }
+    if (IGNORE_PATH_PATTERNS.some(p => abs.includes(p)))
+        return true;
+    // Also check the real path's directory components (symlink may land in ignored dir)
+    const realParts = abs.split(path.sep);
+    if (realParts.some(p => IGNORE_DIRS.has(p)))
+        return true;
+    return false;
 }
 function findingHash(f) {
     const key = `${f.file || ''}|${f.category}|${f.title}`;
@@ -48,10 +84,23 @@ function severityColour(severity) {
  */
 export async function watchDirectory(dirPath, deep, options) {
     const resolved = path.resolve(dirPath);
+    // Block overly broad paths that trigger macOS permission dialogs
+    const homedir = os.homedir();
+    const dangerousPaths = ['/', '/Users', '/tmp', '/private', '/var', '/System', '/Applications', homedir];
+    if (dangerousPaths.includes(resolved)) {
+        console.error(`${c.red}${c.bold}Error:${c.reset} Watching "${resolved}" is too broad — it would scan system files and trigger OS permission dialogs.`);
+        console.error(`${c.dim}Watch a specific project directory instead, e.g.:${c.reset}`);
+        console.error(`  shieldcortex xray ${homedir}/Development/my-project --watch`);
+        process.exit(1);
+    }
     const seenHashes = new Set();
     const json = options?.json ?? false;
+    const session = startWatchSession(resolved, deep);
     // Debounce map: filePath → timeout
     const pending = new Map();
+    const heartbeat = setInterval(() => {
+        heartbeatWatchSession(session.id);
+    }, 30_000);
     console.log(`${c.cyan}${c.bold}Watching ${resolved} for changes... (Ctrl+C to stop)${c.reset}`);
     async function handleChange(filePath) {
         const abs = path.resolve(resolved, filePath);
@@ -78,18 +127,45 @@ export async function watchDirectory(dirPath, deep, options) {
         }
         if (newFindings.length === 0)
             return;
+        const { score, riskLevel } = calculateTrustScore(newFindings);
+        const scannedAt = new Date().toISOString();
+        addFindings(session.id, 'watch', abs, newFindings);
+        appendActivity({
+            kind: 'watch',
+            status: 'detected',
+            target: abs,
+            targetType: 'file',
+            deepScan: deep,
+            trustScore: score,
+            riskLevel,
+            filesScanned: 1,
+            findingCount: newFindings.length,
+            scannedAt,
+            summary: `${newFindings.length} new findings detected in watch mode`,
+        });
+        recordWatchSessionEvent(session.id, {
+            findingsDetected: newFindings.length,
+            riskLevel,
+            summary: `${path.basename(abs)} triggered ${newFindings.length} new findings`,
+            scannedAt,
+        });
+        emitDetectionEvent({
+            target: abs,
+            findingCount: newFindings.length,
+            riskLevel,
+            severity: newFindings[0]?.severity ?? 'info',
+            summary: `${newFindings.length} new finding${newFindings.length === 1 ? '' : 's'} in ${path.basename(abs)}`,
+        });
         if (json) {
-            const { score, riskLevel } = calculateTrustScore(newFindings);
             console.log(JSON.stringify({
                 file: abs,
                 trustScore: score,
                 riskLevel,
                 findings: newFindings,
-                detectedAt: new Date().toISOString(),
+                detectedAt: scannedAt,
             }));
         }
         else {
-            const { score, riskLevel } = calculateTrustScore(newFindings);
             console.log('');
             console.log(`${c.bold}[${new Date().toLocaleTimeString()}]${c.reset} ${c.cyan}${abs}${c.reset}  (score: ${score}, risk: ${riskLevel})`);
             for (const f of newFindings) {
@@ -117,7 +193,9 @@ export async function watchDirectory(dirPath, deep, options) {
     // Keep the process alive until Ctrl+C
     return new Promise((resolve) => {
         process.on('SIGINT', () => {
+            clearInterval(heartbeat);
             watcher.close();
+            endWatchSession(session.id);
             console.log(`\n${c.dim}Watch stopped.${c.reset}`);
             resolve();
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shieldcortex",
-  "version": "4.4.0",
+  "version": "4.6.0",
   "description": "Trustworthy memory and security for AI agents. Recall debugging, review queue, OpenClaw session capture, and memory poisoning defence for Claude Code, Codex, OpenClaw, LangChain, and MCP agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",