shieldcortex 4.4.1 → 4.6.0

package/dist/xray/activity.js

@@ -0,0 +1,256 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+const XRAY_DIR = path.join(os.homedir(), '.shieldcortex');
+const HISTORY_FILE = path.join(XRAY_DIR, 'xray-history.json');
+const ACTIVITY_FILE = path.join(XRAY_DIR, 'xray-activity.jsonl');
+const WATCH_SESSIONS_FILE = path.join(XRAY_DIR, 'xray-watch-sessions.json');
+const HISTORY_LIMIT = 25;
+const ACTIVITY_LIMIT = 100;
+const WATCH_SESSION_LIMIT = 20;
+const ACTIVE_WATCH_THRESHOLD_MS = 90 * 1000;
+const STALE_WATCH_RETENTION_MS = 24 * 60 * 60 * 1000;
+const ENDED_WATCH_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+function ensureXRayDir() {
+    if (!fs.existsSync(XRAY_DIR)) {
+        fs.mkdirSync(XRAY_DIR, { recursive: true });
+    }
+}
+function makeId() {
+    return `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export function serializeXRayResult(result) {
+    return {
+        target: result.target,
+        trustScore: result.trustScore,
+        riskLevel: result.riskLevel,
+        findings: result.findings,
+        filesScanned: result.filesScanned,
+        scannedAt: result.scannedAt.toISOString(),
+        deepScan: result.deepScan,
+    };
+}
+export function createHistoryEntry(result, targetType) {
+    return {
+        id: makeId(),
+        target: result.target,
+        targetType,
+        deepScan: result.deepScan,
+        trustScore: result.trustScore,
+        riskLevel: result.riskLevel,
+        filesScanned: result.filesScanned,
+        findingCount: result.findings.length,
+        scannedAt: result.scannedAt.toISOString(),
+        result: serializeXRayResult(result),
+    };
+}
+export function readHistory() {
+    try {
+        const raw = fs.readFileSync(HISTORY_FILE, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function getHistoryEntry(id) {
+    return readHistory().find((entry) => entry.id === id) ?? null;
+}
+export function appendHistory(entry) {
+    ensureXRayDir();
+    const existing = readHistory();
+    fs.writeFileSync(HISTORY_FILE, JSON.stringify([entry, ...existing].slice(0, HISTORY_LIMIT), null, 2));
+}
+export function appendActivity(entry) {
+    ensureXRayDir();
+    const fullEntry = { id: makeId(), ...entry };
+    fs.appendFileSync(ACTIVITY_FILE, `${JSON.stringify(fullEntry)}\n`);
+    return fullEntry;
+}
+export function readActivity(limit = 25) {
+    try {
+        const lines = fs.readFileSync(ACTIVITY_FILE, 'utf-8')
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .slice(-ACTIVITY_LIMIT);
+        const entries = lines
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((entry) => entry !== null);
+        return entries.reverse().slice(0, limit);
+    }
+    catch {
+        return [];
+    }
+}
+function normalizeWatchSession(entry) {
+    const heartbeatAge = Date.now() - new Date(entry.lastHeartbeatAt).getTime();
+    const active = entry.active && heartbeatAge <= ACTIVE_WATCH_THRESHOLD_MS && entry.endedAt === null;
+    const state = entry.endedAt
+        ? 'ended'
+        : active
+            ? 'active'
+            : 'stale';
+    return {
+        ...entry,
+        active,
+        state,
+    };
+}
+function loadWatchSessions() {
+    try {
+        const raw = fs.readFileSync(WATCH_SESSIONS_FILE, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.map((entry) => entry);
+    }
+    catch {
+        return [];
+    }
+}
+function writeWatchSessions(entries) {
+    ensureXRayDir();
+    fs.writeFileSync(WATCH_SESSIONS_FILE, JSON.stringify(entries.slice(0, WATCH_SESSION_LIMIT), null, 2));
+}
+function shouldRetainWatchSession(entry) {
+    const now = Date.now();
+    if (entry.state === 'active')
+        return true;
+    if (entry.state === 'stale') {
+        return now - new Date(entry.lastHeartbeatAt).getTime() <= STALE_WATCH_RETENTION_MS;
+    }
+    if (entry.state === 'ended' && entry.endedAt) {
+        return now - new Date(entry.endedAt).getTime() <= ENDED_WATCH_RETENTION_MS;
+    }
+    return false;
+}
+function cleanupWatchSessions(entries) {
+    return entries
+        .map((entry) => normalizeWatchSession(entry))
+        .filter((entry) => shouldRetainWatchSession(entry))
+        .slice(0, WATCH_SESSION_LIMIT);
+}
+export function readWatchSessions() {
+    const cleaned = cleanupWatchSessions(loadWatchSessions());
+    if (cleaned.length > 0 || fs.existsSync(WATCH_SESSIONS_FILE)) {
+        writeWatchSessions(cleaned);
+    }
+    return cleaned;
+}
+export function startWatchSession(root, deepScan) {
+    const now = new Date().toISOString();
+    const entry = {
+        id: makeId(),
+        root,
+        deepScan,
+        startedAt: now,
+        lastHeartbeatAt: now,
+        endedAt: null,
+        active: true,
+        state: 'active',
+        changesDetected: 0,
+        findingsDetected: 0,
+        highestRiskLevel: 'SAFE',
+        lastEventAt: null,
+        lastEventSummary: null,
+    };
+    const existing = readWatchSessions().filter((session) => session.root !== root || !session.active);
+    writeWatchSessions([entry, ...existing]);
+    return entry;
+}
+function updateWatchSessionEntry(sessionId, updater) {
+    let updated = null;
+    const next = readWatchSessions().map((entry) => {
+        if (entry.id !== sessionId)
+            return entry;
+        updated = normalizeWatchSession(updater(entry));
+        return updated;
+    });
+    if (updated) {
+        writeWatchSessions(next);
+    }
+    return updated;
+}
+export function heartbeatWatchSession(sessionId) {
+    return updateWatchSessionEntry(sessionId, (entry) => ({
+        ...entry,
+        active: true,
+        state: 'active',
+        lastHeartbeatAt: new Date().toISOString(),
+        endedAt: null,
+    }));
+}
+const RISK_RANK = {
+    SAFE: 0,
+    LOW: 1,
+    MEDIUM: 2,
+    HIGH: 3,
+    CRITICAL: 4,
+};
+export function recordWatchSessionEvent(sessionId, payload) {
+    return updateWatchSessionEntry(sessionId, (entry) => {
+        const nextRisk = RISK_RANK[payload.riskLevel] > RISK_RANK[entry.highestRiskLevel]
+            ? payload.riskLevel
+            : entry.highestRiskLevel;
+        return {
+            ...entry,
+            active: true,
+            state: 'active',
+            lastHeartbeatAt: new Date().toISOString(),
+            changesDetected: entry.changesDetected + 1,
+            findingsDetected: entry.findingsDetected + payload.findingsDetected,
+            highestRiskLevel: nextRisk,
+            lastEventAt: payload.scannedAt ?? new Date().toISOString(),
+            lastEventSummary: payload.summary,
+        };
+    });
+}
+export function endWatchSession(sessionId) {
+    const now = new Date().toISOString();
+    return updateWatchSessionEntry(sessionId, (entry) => ({
+        ...entry,
+        active: false,
+        state: 'ended',
+        lastHeartbeatAt: now,
+        endedAt: now,
+    }));
+}
+// ── Watch IPC (JSONL file for cross-process broadcast) ───────
+export const DETECTION_EVENTS_FILE = path.join(XRAY_DIR, 'xray-detection-events.jsonl');
+const MAX_EVENTS_FILE_SIZE = 512 * 1024;
+export function emitDetectionEvent(event) {
+    try {
+        const stat = fs.statSync(DETECTION_EVENTS_FILE);
+        if (stat.size > MAX_EVENTS_FILE_SIZE) {
+            fs.writeFileSync(DETECTION_EVENTS_FILE, '');
+        }
+    }
+    catch { /* File doesn't exist yet */ }
+    const line = JSON.stringify({ ...event, timestamp: new Date().toISOString() }) + '\n';
+    fs.appendFileSync(DETECTION_EVENTS_FILE, line);
+}
+export function readAndClearDetectionEvents() {
+    try {
+        if (!fs.existsSync(DETECTION_EVENTS_FILE))
+            return [];
+        const tmp = DETECTION_EVENTS_FILE + '.processing';
+        fs.renameSync(DETECTION_EVENTS_FILE, tmp);
+        const data = fs.readFileSync(tmp, 'utf-8').trim();
+        fs.unlinkSync(tmp);
+        if (!data)
+            return [];
+        return data.split('\n').filter(Boolean).map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/xray/dir-scanner.js

@@ -13,13 +13,56 @@ import { calculateTrustScore } from './trust-score.js';
 const SKIP_DIRS = new Set([
     'node_modules', '.git', '.svn', '.hg', 'dist', 'build', '.next',
     '__pycache__', '.tox', '.venv', 'venv', '.cache', 'coverage',
+    'Caches', 'CacheStorage', 'IndexedDB', 'GPUCache',
 ]);
+/** Absolute path prefixes to never scan — system/OS files that always produce false positives. */
+const SKIP_PATH_PREFIXES = [
+    '/System/',
+    '/Library/',
+    '/usr/',
+    '/bin/',
+    '/sbin/',
+    '/private/var/',
+    '/System/Volumes/Preboot/',
+    '/System/Volumes/Data/private/',
+];
+/** Path segments that indicate non-code data we should skip. */
+const SKIP_PATH_SEGMENTS = [
+    '/Library/Caches/',
+    '/Library/Application Support/Google/Chrome/',
+    '/Library/Application Support/Firefox/',
+    '/Library/Application Support/Arc/',
+    '/Library/Containers/',
+    '/Library/News/',
+    '/Library/Mail/',
+    '/Library/Messages/',
+    '/Library/Safari/',
+    '/Library/Cookies/',
+    '/Library/Saved Application State/',
+    '/Library/WebKit/',
+    '/.Trash/',
+];
 /** Maximum number of files to scan per directory. */
 const MAX_FILES = 5000;
+/** Check if a full file path should be excluded from scanning. */
+function isExcludedPath(filePath) {
+    for (const prefix of SKIP_PATH_PREFIXES) {
+        if (filePath.startsWith(prefix))
+            return true;
+    }
+    for (const segment of SKIP_PATH_SEGMENTS) {
+        if (filePath.includes(segment))
+            return true;
+    }
+    return false;
+}
 // ── Directory walker ────────────────────────────────────────
 function walkDir(dirPath, files, depth = 0) {
     if (depth > 20 || files.length >= MAX_FILES)
         return;
+    // Skip entire system/cache directory trees early
+    if (isExcludedPath(dirPath + '/'))
+        return;
     let entries;
     try {
         entries = fs.readdirSync(dirPath, { withFileTypes: true });
@@ -30,13 +73,16 @@ function walkDir(dirPath, files, depth = 0) {
     for (const entry of entries) {
         if (files.length >= MAX_FILES)
             break;
+        const fullPath = path.join(dirPath, entry.name);
         if (entry.isDirectory()) {
             if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
-                walkDir(path.join(dirPath, entry.name), files, depth + 1);
+                walkDir(fullPath, files, depth + 1);
             }
         }
         else if (entry.isFile()) {
-            files.push(path.join(dirPath, entry.name));
+            if (!isExcludedPath(fullPath)) {
+                files.push(fullPath);
+            }
         }
     }
 }

package/dist/xray/file-scanner.js

@@ -41,7 +41,9 @@ function hasZeroWidthUnicode(content) {
     };
 }
 function checkPolyglot(buf) {
-    // Check for multiple magic byte signatures in a single file
+    // Only check magic bytes at file start (first 8 bytes) to avoid false positives
+    // from coincidental byte sequences in large binary files
+    const head = buf.subarray(0, 8);
     const signatures = [
         { name: 'PDF', magic: Buffer.from('%PDF') },
         { name: 'ZIP/JAR', magic: Buffer.from([0x50, 0x4b, 0x03, 0x04]) },
@@ -49,20 +51,39 @@ function checkPolyglot(buf) {
         { name: 'PE/EXE', magic: Buffer.from([0x4d, 0x5a]) },
         { name: 'GZIP', magic: Buffer.from([0x1f, 0x8b]) },
     ];
-    const matched = [];
+    // Identify the primary format from the file header
+    let primaryFormat = null;
     for (const sig of signatures) {
-        // Check at start and also embedded
-        if (buf.includes(sig.magic)) {
-            matched.push(sig.name);
+        if (head.subarray(0, sig.magic.length).equals(sig.magic)) {
+            primaryFormat = sig.name;
+            break;
         }
     }
-    if (matched.length >= 2) {
+    if (!primaryFormat)
+        return null;
+    // Check for a SECOND format signature embedded after the first 64 bytes
+    // (a real polyglot embeds another format, not just coincidental bytes)
+    const searchStart = 64;
+    if (buf.length < searchStart + 4)
+        return null;
+    const rest = buf.subarray(searchStart);
+    const embedded = [];
+    for (const sig of signatures) {
+        if (sig.name === primaryFormat)
+            continue;
+        // Look for the signature at a plausible offset (not random noise)
+        const idx = rest.indexOf(sig.magic);
+        if (idx >= 0 && idx < 1024) {
+            embedded.push(sig.name);
+        }
+    }
+    if (embedded.length > 0) {
         return {
             severity: 'high',
             category: 'steganography',
             title: 'Polyglot file detected',
-            description: `File contains multiple format signatures (${matched.join(', ')}), indicating a polyglot that may hide payloads.`,
-            evidence: matched.join(', '),
+            description: `File starts as ${primaryFormat} but also contains ${embedded.join(', ')} signatures, indicating a polyglot that may hide payloads.`,
+            evidence: `${primaryFormat} + ${embedded.join(', ')}`,
         };
     }
     return null;
@@ -309,17 +330,19 @@ export async function scanFile(filePath, deep) {
                     });
                 }
             }
-            // Long single-line detection — common in minified/obfuscated code
-            const lines = content.split('\n');
-            const longLines = lines.filter(l => l.length > 2000);
-            if (longLines.length > 0 && lines.length < 10) {
-                findings.push({
-                    category: 'obfuscation',
-                    title: `Minified/packed code (${longLines.length} lines over 2000 chars)`,
-                    description: 'File appears to contain minified or packed code which may hide malicious content',
-                    severity: 'low',
-                    file: filePath,
-                });
+            // Long single-line detection — only for code/JSON files (binary blobs always have long "lines")
+            if (CODE_EXTENSIONS.has(ext) || JSON_EXTENSIONS.has(ext)) {
+                const lines = content.split('\n');
+                const longLines = lines.filter(l => l.length > 2000);
+                if (longLines.length > 0 && lines.length < 10) {
+                    findings.push({
+                        category: 'obfuscation',
+                        title: `Minified/packed code (${longLines.length} lines over 2000 chars)`,
+                        description: 'File appears to contain minified or packed code which may hide malicious content',
+                        severity: 'low',
+                        file: filePath,
+                    });
+                }
             }
         }
         catch {

package/dist/xray/findings-store.d.ts

@@ -0,0 +1,56 @@
+/**
+ * X-Ray Findings Store
+ *
+ * Persistent storage for actionable X-Ray findings.
+ * Tracks finding lifecycle: new -> reviewed -> ignored/resolved/quarantined
+ */
+import type { XRayFinding, ActionableXRayFinding, FindingStatus } from './types.js';
+export interface FindingsStore {
+    addFindings(sourceId: string, sourceKind: 'scan' | 'watch', target: string, rawFindings: XRayFinding[]): ActionableXRayFinding[];
+    getFinding(id: string): ActionableXRayFinding | null;
+    listFindings(filters?: {
+        status?: FindingStatus;
+        target?: string;
+        severity?: string;
+        limit?: number;
+    }): ActionableXRayFinding[];
+    updateFindingStatus(id: string, status: FindingStatus, note?: string): ActionableXRayFinding | null;
+    deleteFinding(id: string): boolean;
+    quarantineFile(id: string, note?: string): {
+        moved: boolean;
+        quarantinePath?: string;
+        error?: string;
+    };
+    getStats(): {
+        total: number;
+        new: number;
+        reviewed: number;
+        ignored: number;
+        resolved: number;
+        quarantined: number;
+    };
+}
+export declare function createFindingsStore(basePath?: string): FindingsStore;
+export declare const addFindings: (sourceId: string, sourceKind: "scan" | "watch", target: string, rawFindings: XRayFinding[]) => ActionableXRayFinding[];
+export declare const getFinding: (id: string) => ActionableXRayFinding | null;
+export declare const listFindings: (filters?: {
+    status?: FindingStatus;
+    target?: string;
+    severity?: string;
+    limit?: number;
+}) => ActionableXRayFinding[];
+export declare const updateFindingStatus: (id: string, status: FindingStatus, note?: string) => ActionableXRayFinding | null;
+export declare const deleteFinding: (id: string) => boolean;
+export declare const quarantineFile: (id: string, note?: string) => {
+    moved: boolean;
+    quarantinePath?: string;
+    error?: string;
+};
+export declare const getStats: () => {
+    total: number;
+    new: number;
+    reviewed: number;
+    ignored: number;
+    resolved: number;
+    quarantined: number;
+};

package/dist/xray/findings-store.js

@@ -0,0 +1,173 @@
+/**
+ * X-Ray Findings Store
+ *
+ * Persistent storage for actionable X-Ray findings.
+ * Tracks finding lifecycle: new -> reviewed -> ignored/resolved/quarantined
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+const MAX_FINDINGS = 500;
+const CLEANUP_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+function defaultBasePath() {
+    return path.join(os.homedir(), '.shieldcortex');
+}
+function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+}
+function findingDedupeKey(target, f) {
+    return `${target}|${f.category}|${f.title}|${f.file ?? ''}|${f.line ?? ''}`;
+}
+export function createFindingsStore(basePath) {
+    const base = basePath ?? defaultBasePath();
+    const findingsFile = path.join(base, 'xray-findings.json');
+    const quarantineDir = path.join(base, 'quarantine', 'files');
+    function readFindings() {
+        try {
+            const data = fs.readFileSync(findingsFile, 'utf-8');
+            return JSON.parse(data);
+        }
+        catch {
+            return [];
+        }
+    }
+    function writeFindings(findings) {
+        ensureDir(base);
+        // Atomic write: write to temp file then rename (prevents corruption on crash)
+        const tmp = findingsFile + '.tmp';
+        fs.writeFileSync(tmp, JSON.stringify(findings.slice(0, MAX_FINDINGS), null, 2));
+        fs.renameSync(tmp, findingsFile);
+    }
+    return {
+        addFindings(sourceId, sourceKind, target, rawFindings) {
+            const now = new Date().toISOString();
+            const existing = readFindings();
+            const existingKeys = new Set(existing.filter((f) => f.status === 'new').map((f) => findingDedupeKey(f.target, f)));
+            const newFindings = [];
+            for (const f of rawFindings) {
+                const key = findingDedupeKey(target, f);
+                if (existingKeys.has(key))
+                    continue;
+                existingKeys.add(key);
+                newFindings.push({
+                    ...f,
+                    id: crypto.randomUUID(),
+                    sourceId,
+                    sourceKind,
+                    target,
+                    status: 'new',
+                    detectedAt: now,
+                    updatedAt: now,
+                });
+            }
+            // Cleanup: remove resolved/ignored findings older than 30 days
+            const cutoff = Date.now() - CLEANUP_AGE_MS;
+            const cleaned = existing.filter((f) => {
+                if (f.status === 'new' || f.status === 'reviewed')
+                    return true;
+                return new Date(f.updatedAt).getTime() > cutoff;
+            });
+            const merged = [...newFindings, ...cleaned].slice(0, MAX_FINDINGS);
+            writeFindings(merged);
+            return newFindings;
+        },
+        getFinding(id) {
+            return readFindings().find((f) => f.id === id) ?? null;
+        },
+        listFindings(filters) {
+            let results = readFindings();
+            if (filters?.status)
+                results = results.filter((f) => f.status === filters.status);
+            if (filters?.target)
+                results = results.filter((f) => f.target.includes(filters.target));
+            if (filters?.severity)
+                results = results.filter((f) => f.severity === filters.severity);
+            if (filters?.limit)
+                results = results.slice(0, filters.limit);
+            return results;
+        },
+        updateFindingStatus(id, status, note) {
+            const findings = readFindings();
+            const idx = findings.findIndex((f) => f.id === id);
+            if (idx === -1)
+                return null;
+            findings[idx].status = status;
+            findings[idx].updatedAt = new Date().toISOString();
+            if (note)
+                findings[idx].resolutionNote = note;
+            writeFindings(findings);
+            return findings[idx];
+        },
+        deleteFinding(id) {
+            const findings = readFindings();
+            const filtered = findings.filter((f) => f.id !== id);
+            if (filtered.length === findings.length)
+                return false;
+            writeFindings(filtered);
+            return true;
+        },
+        quarantineFile(id, note) {
+            const finding = this.getFinding(id);
+            if (!finding)
+                return { moved: false, error: 'Finding not found' };
+            if (!finding.file)
+                return { moved: false, error: 'Finding has no file path' };
+            const sourcePath = path.isAbsolute(finding.file)
+                ? finding.file
+                : path.resolve(finding.target, finding.file);
+            // Path traversal guard: resolved path must be under the scan target directory
+            let resolvedSource;
+            try {
+                resolvedSource = fs.realpathSync(sourcePath);
+            }
+            catch {
+                resolvedSource = path.resolve(sourcePath);
+            }
+            const resolvedTarget = path.resolve(finding.target);
+            if (!resolvedSource.startsWith(resolvedTarget) && !path.isAbsolute(finding.file)) {
+                return { moved: false, error: 'Path traversal blocked — file is outside the scan target directory' };
+            }
+            // Block quarantining system-critical files
+            const blocked = ['/etc/', '/usr/', '/System/', '/bin/', '/sbin/', '/.ssh/', '/private/etc/'];
+            if (blocked.some(p => resolvedSource.includes(p))) {
+                return { moved: false, error: 'Cannot quarantine system files' };
+            }
+            if (!fs.existsSync(sourcePath)) {
+                this.updateFindingStatus(id, 'quarantined', note || 'File not found — marked as quarantined');
+                return { moved: false, error: 'Source file does not exist' };
+            }
+            const destName = `${Date.now()}-${path.basename(sourcePath)}`;
+            const destPath = path.join(quarantineDir, destName);
+            try {
+                ensureDir(quarantineDir);
+                fs.renameSync(sourcePath, destPath);
+                this.updateFindingStatus(id, 'quarantined', note || `Moved to ${destPath}`);
+                return { moved: true, quarantinePath: destPath };
+            }
+            catch (err) {
+                return { moved: false, error: err.message };
+            }
+        },
+        getStats() {
+            const findings = readFindings();
+            return {
+                total: findings.length,
+                new: findings.filter((f) => f.status === 'new').length,
+                reviewed: findings.filter((f) => f.status === 'reviewed').length,
+                ignored: findings.filter((f) => f.status === 'ignored').length,
+                resolved: findings.filter((f) => f.status === 'resolved').length,
+                quarantined: findings.filter((f) => f.status === 'quarantined').length,
+            };
+        },
+    };
+}
+// Default singleton for convenience — uses ~/.shieldcortex/
+const defaultStore = createFindingsStore();
+export const addFindings = defaultStore.addFindings.bind(defaultStore);
+export const getFinding = defaultStore.getFinding.bind(defaultStore);
+export const listFindings = defaultStore.listFindings.bind(defaultStore);
+export const updateFindingStatus = defaultStore.updateFindingStatus.bind(defaultStore);
+export const deleteFinding = defaultStore.deleteFinding.bind(defaultStore);
+export const quarantineFile = defaultStore.quarantineFile.bind(defaultStore);
+export const getStats = defaultStore.getStats.bind(defaultStore);

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;