shieldcortex 4.2.5 → 4.3.0

package/dist/xray/npm-inspector.js

@@ -0,0 +1,380 @@
+/**
+ * X-Ray NPM Package Inspector
+ *
+ * Downloads package metadata from registry.npmjs.org, analyses it for risk
+ * signals, and optionally scans the tarball contents (Pro/deep scan).
+ * Uses only Node.js built-ins (https module) — no new dependencies.
+ */
+import https from 'https';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { createGunzip } from 'zlib';
+import { detectPatterns } from './patterns.js';
+import { calculateTrustScore } from './trust-score.js';
+import { scanFile } from './file-scanner.js';
+// ── Constants ───────────────────────────────────────────────
+/** Popular npm packages for typosquat comparison. */
+const POPULAR_PACKAGES = [
+    'react', 'express', 'lodash', 'axios', 'chalk', 'commander', 'debug',
+    'webpack', 'typescript', 'next', 'vue', 'angular', 'moment', 'request',
+    'underscore', 'async', 'bluebird', 'uuid', 'dotenv', 'cors', 'ws',
+    'body-parser', 'mongoose', 'yargs', 'inquirer', 'glob', 'rimraf',
+    'eslint', 'prettier', 'jest', 'mocha', 'chai', 'sinon', 'nodemon',
+    'babel', 'rollup', 'vite', 'esbuild', 'fastify', 'koa', 'hapi',
+    'socket.io', 'passport', 'jsonwebtoken', 'bcrypt', 'mysql', 'pg',
+    'redis', 'mongodb', 'sequelize', 'prisma', 'graphql', 'apollo',
+];
+// ── Helpers ─────────────────────────────────────────────────
+/**
+ * Simple HTTPS GET returning the response body as a string.
+ */
+function httpsGet(url) {
+    return new Promise((resolve, reject) => {
+        https.get(url, { headers: { 'Accept': 'application/json' } }, (res) => {
+            if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+                httpsGet(res.headers.location).then(resolve, reject);
+                return;
+            }
+            if (res.statusCode !== 200) {
+                reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+                res.resume();
+                return;
+            }
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+            res.on('error', reject);
+        }).on('error', reject);
+    });
+}
+/**
+ * Download a tarball to a temp file and return the path.
+ */
+function downloadTarball(url) {
+    return new Promise((resolve, reject) => {
+        const tmpFile = path.join(os.tmpdir(), `shieldcortex-xray-${Date.now()}.tgz`);
+        const file = fs.createWriteStream(tmpFile);
+        const doGet = (targetUrl) => {
+            https.get(targetUrl, (res) => {
+                if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+                    doGet(res.headers.location);
+                    return;
+                }
+                if (res.statusCode !== 200) {
+                    reject(new Error(`HTTP ${res.statusCode} downloading tarball`));
+                    res.resume();
+                    return;
+                }
+                res.pipe(file);
+                file.on('finish', () => {
+                    file.close();
+                    resolve(tmpFile);
+                });
+            }).on('error', reject);
+        };
+        doGet(url);
+    });
+}
+/**
+ * Extract a .tgz to a temp directory using Node built-ins (zlib + tar parsing).
+ * Returns path to the extracted directory.
+ */
+async function extractTarball(tgzPath) {
+    const extractDir = path.join(os.tmpdir(), `shieldcortex-xray-extract-${Date.now()}`);
+    fs.mkdirSync(extractDir, { recursive: true });
+    return new Promise((resolve, reject) => {
+        const gunzip = createGunzip();
+        const input = fs.createReadStream(tgzPath);
+        const chunks = [];
+        input.pipe(gunzip);
+        gunzip.on('data', (chunk) => chunks.push(chunk));
+        gunzip.on('end', () => {
+            try {
+                const tarData = Buffer.concat(chunks);
+                extractTarBuffer(tarData, extractDir);
+                resolve(extractDir);
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+        gunzip.on('error', reject);
+        input.on('error', reject);
+    });
+}
+/**
+ * Minimal tar extraction from a buffer. Handles ustar format.
+ */
+function extractTarBuffer(buf, outDir) {
+    let offset = 0;
+    while (offset < buf.length - 512) {
+        // Read header (512 bytes)
+        const header = buf.subarray(offset, offset + 512);
+        // Check for empty block (end of archive)
+        if (header.every(b => b === 0))
+            break;
+        // Extract filename (0-100 bytes, null-terminated)
+        const nameEnd = header.indexOf(0, 0);
+        const name = header.subarray(0, Math.min(nameEnd, 100)).toString('utf-8');
+        // Extract file size (octal, bytes 124-136)
+        const sizeStr = header.subarray(124, 136).toString('utf-8').trim();
+        const size = parseInt(sizeStr, 8) || 0;
+        // Extract type flag (byte 156)
+        const typeFlag = header[156];
+        // Prefix field for ustar (bytes 345-500)
+        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);
+        offset += 512; // Move past header
+        if (typeFlag === 48 || typeFlag === 0) { // Regular file ('0' or null)
+            if (size > 0) {
+                const dir = path.dirname(filePath);
+                fs.mkdirSync(dir, { recursive: true });
+                const fileData = buf.subarray(offset, offset + size);
+                fs.writeFileSync(filePath, fileData);
+            }
+        }
+        else if (typeFlag === 53) { // Directory ('5')
+            fs.mkdirSync(filePath, { recursive: true });
+        }
+        // Advance past data blocks (rounded up to 512 boundary)
+        offset += Math.ceil(size / 512) * 512;
+    }
+}
+/**
+ * Levenshtein edit distance between two strings.
+ */
+function editDistance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1]
+                ? dp[i - 1][j - 1]
+                : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+// ── Public API ──────────────────────────────────────────────
+/**
+ * Inspect an npm package for hidden risk.
+ *
+ * @param packageName - npm package name (e.g. "lodash", "@scope/pkg")
+ * @param deep - If true, downloads and scans the tarball (Pro feature)
+ */
+export async function inspectNpmPackage(packageName, deep = false) {
+    const startTime = Date.now();
+    const findings = [];
+    let filesScanned = 0;
+    // Fetch package metadata
+    const encodedName = packageName.startsWith('@')
+        ? `@${encodeURIComponent(packageName.slice(1))}`
+        : encodeURIComponent(packageName);
+    let meta;
+    try {
+        const raw = await httpsGet(`https://registry.npmjs.org/${encodedName}`);
+        meta = JSON.parse(raw);
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        findings.push({
+            severity: 'info',
+            category: 'dependency-risk',
+            title: 'Failed to fetch package metadata',
+            description: `Could not fetch metadata from npm registry: ${errMsg}`,
+        });
+        const { score, riskLevel } = calculateTrustScore(findings);
+        return {
+            target: packageName,
+            trustScore: score,
+            riskLevel,
+            findings,
+            filesScanned: 0,
+            scannedAt: new Date(),
+            deepScan: deep,
+        };
+    }
+    // Check maintainer count
+    const maintainers = meta.maintainers;
+    if (maintainers && maintainers.length === 1) {
+        findings.push({
+            severity: 'low',
+            category: 'dependency-risk',
+            title: 'Single maintainer',
+            description: 'Package has only one maintainer, increasing bus factor risk.',
+        });
+    }
+    // Check publish frequency / time
+    const time = meta.time;
+    if (time) {
+        const versions = Object.keys(time).filter(k => k !== 'created' && k !== 'modified');
+        const created = new Date(time.created || '');
+        const lastPublish = versions.length > 0 ? new Date(time[versions[versions.length - 1]]) : null;
+        // Recently created with very few versions — potential typosquat
+        if (lastPublish && versions.length <= 2) {
+            const ageMs = Date.now() - created.getTime();
+            const ageDays = ageMs / (1000 * 60 * 60 * 24);
+            if (ageDays < 30) {
+                findings.push({
+                    severity: 'medium',
+                    category: 'dependency-risk',
+                    title: 'Very new package with few versions',
+                    description: `Package was created ${Math.round(ageDays)} days ago with only ${versions.length} version(s).`,
+                });
+            }
+        }
+    }
+    // Check latest version metadata
+    const distTags = meta['dist-tags'];
+    const latestVersion = distTags?.latest;
+    const versions = meta.versions;
+    const latestMeta = latestVersion && versions ? versions[latestVersion] : null;
+    if (latestMeta) {
+        // Check scripts
+        const scripts = latestMeta.scripts;
+        if (scripts) {
+            for (const hook of ['preinstall', 'install', 'postinstall']) {
+                if (scripts[hook]) {
+                    const val = scripts[hook];
+                    findings.push({
+                        severity: 'medium',
+                        category: 'persistence-hook',
+                        title: `Has ${hook} script`,
+                        description: `Package defines a "${hook}" lifecycle script.`,
+                        evidence: val.slice(0, 120),
+                    });
+                    if (/curl|wget|node\s+-e|bash\s+-c|powershell|https?:\/\/|eval|exec/i.test(val)) {
+                        findings.push({
+                            severity: 'high',
+                            category: 'persistence-hook',
+                            title: `Suspicious ${hook} script`,
+                            description: `The "${hook}" script executes potentially dangerous commands.`,
+                            evidence: val.slice(0, 120),
+                        });
+                    }
+                }
+            }
+        }
+        // Check description/keywords for AI directives
+        const description = latestMeta.description;
+        if (description) {
+            const descFindings = detectPatterns(JSON.stringify({ description }));
+            findings.push(...descFindings);
+        }
+        const keywords = latestMeta.keywords;
+        if (keywords) {
+            const kwFindings = detectPatterns(JSON.stringify({ keywords }));
+            findings.push(...kwFindings);
+        }
+        // Check dependency count
+        const deps = latestMeta.dependencies;
+        if (deps && Object.keys(deps).length > 50) {
+            findings.push({
+                severity: 'low',
+                category: 'dependency-risk',
+                title: 'High dependency count',
+                description: `Package has ${Object.keys(deps).length} direct dependencies, increasing attack surface.`,
+            });
+        }
+    }
+    // Typosquatting check
+    const baseName = packageName.replace(/^@[^/]+\//, '');
+    for (const popular of POPULAR_PACKAGES) {
+        if (baseName === popular)
+            break; // It IS the popular package
+        const dist = editDistance(baseName, popular);
+        if (dist > 0 && dist <= 2) {
+            findings.push({
+                severity: 'high',
+                category: 'dependency-risk',
+                title: 'Possible typosquat',
+                description: `Package name "${packageName}" is ${dist} edit(s) from popular package "${popular}".`,
+                evidence: `edit distance: ${dist}`,
+            });
+            break;
+        }
+    }
+    // Deep scan: download and scan tarball
+    if (deep && latestMeta) {
+        const dist = latestMeta.dist;
+        if (dist?.tarball) {
+            try {
+                const tgzPath = await downloadTarball(dist.tarball);
+                try {
+                    const extractDir = await extractTarball(tgzPath);
+                    try {
+                        // Walk and scan extracted files
+                        const extractedFiles = walkExtracted(extractDir);
+                        filesScanned = extractedFiles.length;
+                        for (const file of extractedFiles) {
+                            const fileFindings = await scanFile(file, true);
+                            for (const f of fileFindings) {
+                                // Make file paths relative to package
+                                f.file = f.file ? path.relative(extractDir, f.file) : f.file;
+                                findings.push(f);
+                            }
+                        }
+                    }
+                    finally {
+                        // Clean up extracted dir
+                        fs.rmSync(extractDir, { recursive: true, force: true });
+                    }
+                }
+                finally {
+                    // Clean up tarball
+                    fs.unlinkSync(tgzPath);
+                }
+            }
+            catch {
+                findings.push({
+                    severity: 'info',
+                    category: 'dependency-risk',
+                    title: 'Tarball scan failed',
+                    description: 'Could not download or extract the package tarball for deep scanning.',
+                });
+            }
+        }
+    }
+    const { score, riskLevel } = calculateTrustScore(findings);
+    return {
+        target: packageName,
+        trustScore: score,
+        riskLevel,
+        findings,
+        filesScanned,
+        scannedAt: new Date(),
+        deepScan: deep,
+    };
+}
+/**
+ * Walk an extracted tarball directory and collect file paths.
+ */
+function walkExtracted(dir, files = []) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return files;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name !== 'node_modules') {
+                walkExtracted(full, files);
+            }
+        }
+        else if (entry.isFile()) {
+            files.push(full);
+        }
+    }
+    return files;
+}

package/dist/xray/patterns.d.ts

@@ -0,0 +1,20 @@
+/**
+ * X-Ray Pattern Detection
+ *
+ * Comprehensive pattern groups for detecting hidden risk in packages, files,
+ * and metadata. Follows the same conventions as skill-scanner/patterns.ts:
+ *   - safeRegexTest wrapper for every test
+ *   - MAX_SCAN_LENGTH truncation to prevent ReDOS
+ *   - PatternGroup style with weighted confidence
+ *   - One match per group is enough (break after first)
+ */
+import type { XRayFinding } from './types.js';
+/**
+ * Run all X-Ray pattern groups against content and return matched findings.
+ * Optionally tag findings with a file path and compute line numbers.
+ */
+export declare function detectPatterns(content: string, filePath?: string): XRayFinding[];
+/**
+ * Check if a filename itself contains AI directive patterns.
+ */
+export declare function detectFilenameDirectives(filename: string): XRayFinding[];

package/dist/xray/patterns.js

@@ -0,0 +1,271 @@
+/**
+ * X-Ray Pattern Detection
+ *
+ * Comprehensive pattern groups for detecting hidden risk in packages, files,
+ * and metadata. Follows the same conventions as skill-scanner/patterns.ts:
+ *   - safeRegexTest wrapper for every test
+ *   - MAX_SCAN_LENGTH truncation to prevent ReDOS
+ *   - PatternGroup style with weighted confidence
+ *   - One match per group is enough (break after first)
+ */
+// ── Constants ───────────────────────────────────────────────────────────────
+/** Maximum content length to analyse (prevents ReDOS on very long inputs). */
+const MAX_SCAN_LENGTH = 50000;
+// ── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Safely test a regex against content with a length limit.
+ */
+function safeRegexTest(pattern, text) {
+    const truncated = text.length > MAX_SCAN_LENGTH ? text.slice(0, MAX_SCAN_LENGTH) : text;
+    return pattern.test(truncated);
+}
+// ── Pattern Groups ──────────────────────────────────────────────────────────
+const XRAY_PATTERN_GROUPS = [
+    // 1. eval/exec with dynamic input
+    {
+        name: 'eval_exec',
+        category: 'eval-exec',
+        severity: 'critical',
+        title: 'Dynamic code execution detected',
+        description: 'Code uses eval(), new Function(), or vm.runIn* which can execute arbitrary code.',
+        patterns: [
+            /\beval\s*\(\s*[^)'"]/,
+            /\beval\s*\(\s*['"`]\s*\+/,
+            /\bnew\s+Function\s*\(/,
+            /\bvm\.runIn(ThisContext|NewContext|Context)\s*\(/,
+            /\bvm\.compileFunction\s*\(/,
+            /\bvm\.Script\s*\(/,
+        ],
+    },
+    // 2. Shell execution
+    {
+        name: 'shell_execution',
+        category: 'shell-execution',
+        severity: 'critical',
+        title: 'Shell command execution detected',
+        description: 'Code executes shell commands via child_process or similar APIs.',
+        patterns: [
+            /child_process\.(exec|execSync|spawn|spawnSync|fork)\s*\(/,
+            /require\s*\(\s*['"]child_process['"]\s*\)/,
+            /import\s+.*from\s+['"]child_process['"]/,
+            /\bexecSync\s*\(\s*[`'"]/,
+            /\bspawn\s*\([^)]*shell\s*:\s*true/,
+            /\bexec\s*\(\s*['"`](?:bash|sh|cmd|powershell)/i,
+        ],
+    },
+    // 3. Suspicious postinstall hooks
+    {
+        name: 'postinstall_hook',
+        category: 'persistence-hook',
+        severity: 'high',
+        title: 'Suspicious lifecycle script detected',
+        description: 'Package.json contains postinstall/preinstall/install scripts that may execute arbitrary code.',
+        patterns: [
+            /"(?:post|pre)?install"\s*:\s*"[^"]*(?:curl|wget|node\s+-e|bash|sh\s+-c|powershell)/i,
+            /"(?:post|pre)?install"\s*:\s*"[^"]*(?:https?:\/\/|eval|exec)/i,
+            /"(?:post|pre)?install"\s*:\s*"[^"]*\|\s*(?:bash|sh|node)/i,
+        ],
+    },
+    // 4. Network beacons on import
+    {
+        name: 'network_beacon',
+        category: 'network-beacon',
+        severity: 'high',
+        title: 'Network beacon on load detected',
+        description: 'Code makes network requests at the top level (on import/require), potentially phoning home.',
+        patterns: [
+            /^(?:const|let|var|import)[\s\S]{0,200}(?:fetch|http\.get|https\.get|http\.request|https\.request)\s*\(/m,
+            /^(?:const|let|var)[\s\S]{0,50}require\s*\(\s*['"](?:http|https|node-fetch|axios)['"]\s*\)[\s\S]{0,200}\.(?:get|post|request)\s*\(/m,
+            /\bnew\s+WebSocket\s*\(\s*['"`]/,
+            /\bdns\.(?:lookup|resolve|resolve4|resolve6)\s*\(/,
+            /\bnet\.connect\s*\(/,
+            /\bdgram\.createSocket\s*\(/,
+        ],
+    },
+    // 5. Obfuscation techniques
+    {
+        name: 'obfuscation',
+        category: 'obfuscation',
+        severity: 'high',
+        title: 'Code obfuscation detected',
+        description: 'Code uses obfuscation techniques such as hex-encoded strings, fromCharCode arrays, or atob/btoa chains.',
+        patterns: [
+            // Hex-encoded strings > 50 chars
+            /['"]\\x[0-9a-f]{2}(?:\\x[0-9a-f]{2}){24,}['"]/i,
+            // Long hex literal strings
+            /['"][0-9a-f]{50,}['"]/i,
+            // atob/btoa chains
+            /\batob\s*\(\s*(?:atob|btoa)\s*\(/,
+            /\batob\s*\(\s*['"][A-Za-z0-9+/=]{20,}['"]\s*\)/,
+            // String.fromCharCode arrays
+            /String\.fromCharCode\s*\(\s*(?:\d+\s*,\s*){10,}/,
+            // Buffer.from with hex/base64 for code execution
+            /Buffer\.from\s*\(\s*['"][A-Za-z0-9+/=]{40,}['"]\s*,\s*['"](?:base64|hex)['"]\s*\)[\s\S]{0,50}\.toString\s*\(/,
+            // _0x variable naming pattern (common obfuscator output)
+            /\b_0x[0-9a-f]{4,}\b/i,
+        ],
+    },
+    // 6. AI directive patterns (modelled on ST3GG INJECTION_TEMPLATES)
+    {
+        name: 'ai_directive',
+        category: 'ai-directive',
+        severity: 'critical',
+        title: 'AI directive injection detected',
+        description: 'Content contains patterns designed to manipulate AI model behaviour — prompt injection, jailbreak, or hidden instructions.',
+        patterns: [
+            // Direct AI instruction patterns
+            /ignore\s+(all\s+)?(previous|prior|above)\s+(instructions?|prompts?|context)/i,
+            /disregard\s+(all\s+)?(previous|prior|above)\s+(instructions?|prompts?|rules?)/i,
+            /override\s+(previous|prior|all)\s+(instructions?|rules?|constraints?)/i,
+            /you\s+are\s+now\s+(?:in\s+)?(?:developer|god|admin|root|unrestricted)\s+mode/i,
+            /enter\s+(?:developer|god|admin|DAN|jailbreak)\s+mode/i,
+            /(?:system|hidden|secret)\s*(?:prompt|instruction|directive)\s*:/i,
+            // Instruction boundary attacks
+            /\[SYSTEM\]\s*:/i,
+            /\[INST\]/i,
+            /<\|(?:system|user|assistant|im_start|im_end)\|>/i,
+            // Encoded/hidden instruction markers
+            /(?:decode|execute|follow)\s+(?:the\s+)?hidden\s+(?:instructions?|payload|message)/i,
+            /(?:hidden|embedded|encoded)\s+(?:instructions?|directive|command)\s+(?:in|within|inside)/i,
+            // LSB steganography references
+            /(?:LSB|least\s+significant\s+bit)\s+(?:encoding|steganography|injection|extraction)/i,
+            /extract\s+(?:the\s+)?(?:hidden|embedded)\s+(?:data|message|payload)\s+from\s+(?:the\s+)?image/i,
+            // Filename-based directive patterns
+            /ignore_previous/i,
+            /decode_hidden/i,
+            /execute_instructions/i,
+            /override_previous/i,
+            /developer_mode/i,
+        ],
+    },
+    // 7. Unicode tricks
+    {
+        name: 'unicode_trick',
+        category: 'unicode-trick',
+        severity: 'medium',
+        title: 'Suspicious Unicode characters detected',
+        description: 'Content contains zero-width characters, homoglyphs, or bidirectional overrides that may hide malicious content.',
+        patterns: [
+            // Zero-width characters (multiple in sequence suggest intentional hiding)
+            /[\u200b\u200c\u200d\ufeff\u2060]{2,}/,
+            // RTL/LTR override characters
+            /[\u202a-\u202e\u2066-\u2069]/,
+            // Tag characters (U+E0001-U+E007F) — used for invisible text
+            /[\u{E0001}-\u{E007F}]/u,
+            // Combining characters abuse (>3 combining marks in a row)
+            /[\u0300-\u036f]{4,}/,
+        ],
+    },
+    // 8. Prompt injection in metadata
+    {
+        name: 'metadata_injection',
+        category: 'metadata-exploit',
+        severity: 'high',
+        title: 'Prompt injection in metadata',
+        description: 'Package metadata (description, keywords, author) contains AI instruction fragments designed to manipulate model behaviour.',
+        patterns: [
+            /"description"\s*:\s*"[^"]*(?:ignore\s+previous|you\s+are\s+now|system\s+prompt|execute\s+the\s+following|run\s+this\s+command)[^"]*"/i,
+            /"keywords"\s*:\s*\[[^\]]*"(?:ignore|override|execute|system.?prompt|jailbreak|DAN)[^"]*"[^\]]*\]/i,
+            /"author"\s*:\s*"[^"]*(?:ignore\s+previous|execute|system\s+prompt)[^"]*"/i,
+        ],
+    },
+    // 9. Covert channels
+    {
+        name: 'covert_channel',
+        category: 'covert-channel',
+        severity: 'high',
+        title: 'Potential covert communication channel',
+        description: 'Code establishes hidden communication channels using DNS, WebSocket, or encoded data exfiltration.',
+        patterns: [
+            // DNS-based exfiltration
+            /dns\.resolve[\s\S]{0,50}\.(?:concat|join)\s*\(/,
+            /\.replace\s*\([^)]+\)[\s\S]{0,50}dns\.(?:lookup|resolve)/,
+            // Steganographic data hiding
+            /\.(?:getImageData|putImageData)\s*\([\s\S]{0,200}(?:charCodeAt|fromCharCode)/,
+            // Data encoded in HTTP headers
+            /headers\s*[\[.]\s*['"](?:X-|Cookie)[\s\S]{0,100}(?:encode|btoa|Buffer\.from)/i,
+        ],
+    },
+    // 10. Dependency risk signals
+    {
+        name: 'dependency_risk',
+        category: 'dependency-risk',
+        severity: 'medium',
+        title: 'Dependency risk indicator',
+        description: 'Package exhibits characteristics associated with supply-chain attacks: wildcard versions, git dependencies, or excessive install scripts.',
+        patterns: [
+            // Wildcard or latest version
+            /"dependencies"\s*:\s*\{[^}]*"[^"]+"\s*:\s*"(?:\*|latest|>=)"/,
+            // Git URL dependencies
+            /"dependencies"\s*:\s*\{[^}]*"[^"]+"\s*:\s*"(?:git\+|github:|https:\/\/github\.com)/,
+            // Multiple lifecycle scripts
+            /"(?:preinstall|postinstall|preuninstall|postuninstall)"\s*:\s*"[^"]+"/,
+        ],
+    },
+];
+// ── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Run all X-Ray pattern groups against content and return matched findings.
+ * Optionally tag findings with a file path and compute line numbers.
+ */
+export function detectPatterns(content, filePath) {
+    const findings = [];
+    const truncated = content.length > MAX_SCAN_LENGTH ? content.slice(0, MAX_SCAN_LENGTH) : content;
+    for (const group of XRAY_PATTERN_GROUPS) {
+        for (const pattern of group.patterns) {
+            if (safeRegexTest(pattern, truncated)) {
+                const match = pattern.exec(truncated);
+                let line;
+                let evidence;
+                if (match) {
+                    // Calculate line number from match index
+                    const before = truncated.slice(0, match.index);
+                    line = (before.match(/\n/g) || []).length + 1;
+                    evidence = match[0].slice(0, 120);
+                }
+                findings.push({
+                    severity: group.severity,
+                    category: group.category,
+                    title: group.title,
+                    description: group.description,
+                    file: filePath,
+                    line,
+                    evidence,
+                });
+                break; // one match per group is enough
+            }
+        }
+    }
+    return findings;
+}
+/**
+ * Check if a filename itself contains AI directive patterns.
+ */
+export function detectFilenameDirectives(filename) {
+    const findings = [];
+    const suspiciousPatterns = [
+        /ignore_previous/i,
+        /decode_hidden/i,
+        /execute_instructions/i,
+        /override_previous/i,
+        /developer_mode/i,
+        /system_prompt/i,
+        /jailbreak/i,
+        /\[SYSTEM\]/i,
+        /\[INST\]/i,
+    ];
+    for (const pattern of suspiciousPatterns) {
+        if (pattern.test(filename)) {
+            findings.push({
+                severity: 'critical',
+                category: 'ai-directive',
+                title: 'AI directive in filename',
+                description: `Filename "${filename}" contains an AI directive pattern designed to manipulate model behaviour.`,
+                file: filename,
+                evidence: filename,
+            });
+            break; // one finding per filename is enough
+        }
+    }
+    return findings;
+}

package/dist/xray/report.d.ts

@@ -0,0 +1,16 @@
+/**
+ * X-Ray Report Formatter
+ *
+ * Beautiful terminal output for X-Ray scan results.
+ * Follows the same ANSI colour style as src/audit/report-formatter.ts
+ * and src/cli/stats-banner.ts.
+ */
+import type { XRayResult } from './types.js';
+/**
+ * Format an X-Ray result for terminal display.
+ */
+export declare function formatXRayReport(result: XRayResult): string;
+/**
+ * Format an X-Ray result as markdown.
+ */
+export declare function formatXRayMarkdown(result: XRayResult): string;