shieldcortex 4.31.2 → 4.32.1

package/dist/worker/brain-worker.js

@@ -9,7 +9,7 @@
  *
  * This transforms the memory system from reactive to continuously organic.
  */
-import { DEFAULT_WORKER_CONFIG, MCP_LIGHT_TICK_INTERVAL_MS, } from './types.js';
+import { DEFAULT_WORKER_CONFIG, MCP_LIGHT_TICK_INTERVAL_MS, MCP_RETRY_QUEUE_BUDGET, } from './types.js';
 import { getDatabase } from '../database/init.js';
 import { pruneActivationCache } from '../memory/activation.js';
 import { getMemoryStats } from '../memory/store.js';
@@ -21,22 +21,51 @@ import { emitWorkerLightTick, emitWorkerMediumTick, emitPredictiveConsolidation,
 import { processRetryQueue, purgeOldEntries } from '../cloud/sync-queue.js';
 import { sendHeartbeat } from '../cloud/sync.js';
 import { refreshCloudIronDome, applyCachedCloudPatterns } from '../cloud/iron-dome-sync.js';
+import { purgeOldAuditEntries, purgeAuditUnderSizePressure } from '../defence/audit/retention.js';
 import { isFeatureEnabled } from '../license/gate.js';
-import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 const WORKER_STATE_DIR = join(homedir(), '.shieldcortex', 'state');
 const WORKER_STATE_FILE = join(WORKER_STATE_DIR, 'worker.json');
-function persistWorkerState(profile, lastLightTick) {
+// Audit retention runs in the light tick (which fires every 5–15 min) but is
+// throttled to ~once per day — a daily purge is plenty to keep defence_audit
+// bounded, and running it every tick would be wasteful.
+const AUDIT_PURGE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+function persistWorkerState(profile, lastLightTick, lastAuditPurge) {
     try {
         if (!existsSync(WORKER_STATE_DIR))
             mkdirSync(WORKER_STATE_DIR, { recursive: true });
-        writeFileSync(WORKER_STATE_FILE, JSON.stringify({ pid: process.pid, profile, lastLightTick: lastLightTick.toISOString() }, null, 2), 'utf-8');
+        writeFileSync(WORKER_STATE_FILE, JSON.stringify({
+            pid: process.pid,
+            profile,
+            lastLightTick: lastLightTick.toISOString(),
+            lastAuditPurge: lastAuditPurge ? lastAuditPurge.toISOString() : null,
+        }, null, 2), 'utf-8');
     }
     catch {
         // Best-effort: doctor will warn if the file is stale or missing
     }
 }
+/**
+ * Read the persisted lastAuditPurge timestamp so the 24h throttle survives
+ * process restarts — MCP servers restart frequently (one per Claude Code
+ * window), and without this every restart would trigger a fresh purge.
+ */
+function readPersistedAuditPurge() {
+    try {
+        const raw = JSON.parse(readFileSync(WORKER_STATE_FILE, 'utf-8'));
+        if (raw.lastAuditPurge) {
+            const d = new Date(raw.lastAuditPurge);
+            if (!Number.isNaN(d.getTime()))
+                return d;
+        }
+    }
+    catch {
+        // No prior state — treat as never purged.
+    }
+    return null;
+}
 /**
  * Brain Worker Class
  *
@@ -59,6 +88,9 @@ export class BrainWorker {
     lastLightTick = null;
     lastMediumTick = null;
     lastConsolidation = null;
+    // Seeded from persisted state so the 24h audit-purge throttle survives
+    // frequent MCP-server restarts.
+    lastAuditPurge = readPersistedAuditPurge();
     /**
      * Create a new BrainWorker
      *
@@ -181,20 +213,51 @@ export class BrainWorker {
                     result: result.predictiveConsolidation,
                 });
             }
-            // 3-5: cloud sync (retry queue, heartbeat, Iron Dome) — full profile only.
-            // Skipped under MCP profile so we don't fan out N concurrent network calls
-            // from N open Claude Code windows.
-            if (this.config.profile === 'full') {
-                try {
-                    const retryResult = await processRetryQueue();
-                    if (retryResult.processed > 0) {
-                        console.log(`[BrainWorker] Sync retry queue: processed ${retryResult.processed} ` +
-                            `(${retryResult.succeeded} ok, ${retryResult.failed} retry, ${retryResult.permanentlyFailed} failed)`);
+            // 3. Audit retention — runs on BOTH profiles (MCP-only installs scan
+            // tool responses too, so their defence_audit also grows unbounded; the
+            // sync-queue purge being worker-only left an analogous gap we deliberately
+            // don't repeat here). The pressure valve is a cheap size check, so it runs
+            // every tick; the age-based purge is throttled to ~once per 24h.
+            try {
+                const pressurePurged = purgeAuditUnderSizePressure();
+                if (pressurePurged > 0) {
+                    console.log(`[BrainWorker] Audit size-pressure valve purged ${pressurePurged} rows`);
+                }
+                const now = result.timestamp.getTime();
+                const dueForPurge = this.lastAuditPurge === null ||
+                    now - this.lastAuditPurge.getTime() >= AUDIT_PURGE_INTERVAL_MS;
+                if (dueForPurge) {
+                    const purged = purgeOldAuditEntries();
+                    this.lastAuditPurge = result.timestamp;
+                    if (purged > 0) {
+                        console.log(`[BrainWorker] Audit retention purged ${purged} entries older than 90d`);
                     }
                 }
-                catch (retryError) {
-                    console.error('[BrainWorker] Sync retry queue failed:', retryError);
+            }
+            catch (auditErr) {
+                console.error('[BrainWorker] Audit retention failed:', auditErr);
+            }
+            // 4. Sync retry queue — drains on BOTH profiles. MCP-only installs have
+            // no full worker, so if this stayed full-only their queued audits/
+            // memories would age out unsent (the same gap we closed for audit
+            // retention above). The MCP path is BUDGETED (one process per Claude Code
+            // window) so it doesn't do unbounded network work each tick; full keeps
+            // its historical unbudgeted cadence. processRetryQueue itself no-ops
+            // cheaply when cloud is disabled (no API key), so this is safe to call
+            // unconditionally — no extra gate needed.
+            try {
+                const retryResult = await processRetryQueue(this.config.profile === 'mcp' ? { maxRows: MCP_RETRY_QUEUE_BUDGET } : {});
+                if (retryResult.processed > 0) {
+                    console.log(`[BrainWorker] Sync retry queue: processed ${retryResult.processed} ` +
+                        `(${retryResult.succeeded} ok, ${retryResult.failed} retry, ${retryResult.permanentlyFailed} failed)`);
                 }
+            }
+            catch (retryError) {
+                console.error('[BrainWorker] Sync retry queue failed:', retryError);
+            }
+            // 5-6: heartbeat + Iron Dome — full profile only. Skipped under MCP so we
+            // don't fan out N concurrent network calls from N open Claude Code windows.
+            if (this.config.profile === 'full') {
                 if (isFeatureEnabled('cloud_sync')) {
                     try {
                         sendHeartbeat();
@@ -216,7 +279,7 @@ export class BrainWorker {
             this.lastLightTick = result.timestamp;
             this.stats.lightTicks++;
             // Persist worker freshness for `shieldcortex doctor` to detect stalls.
-            persistWorkerState(this.config.profile, result.timestamp);
+            persistWorkerState(this.config.profile, result.timestamp, this.lastAuditPurge);
             // Emit light tick event
             emitWorkerLightTick(result);
             // Log summary

package/dist/worker/types.d.ts

@@ -51,6 +51,14 @@ export declare const DEFAULT_WORKER_CONFIG: WorkerConfig;
  * background work in check across many windows.
  */
 export declare const MCP_LIGHT_TICK_INTERVAL_MS: number;
+/**
+ * Per-tick budget for the sync retry queue under the MCP profile. MCP-only
+ * installs have no full worker, so they MUST drain their own queue or queued
+ * audits/memories age out unsent — but one MCP process runs per Claude Code
+ * window, so we cap the network work each does per light tick. The full
+ * (dashboard) profile keeps its historical unbudgeted cadence.
+ */
+export declare const MCP_RETRY_QUEUE_BUDGET = 25;
 /**
  * Result of a light tick operation
  */

package/dist/worker/types.js

@@ -26,3 +26,11 @@ export const DEFAULT_WORKER_CONFIG = {
  * background work in check across many windows.
  */
 export const MCP_LIGHT_TICK_INTERVAL_MS = 15 * 60 * 1000;
+/**
+ * Per-tick budget for the sync retry queue under the MCP profile. MCP-only
+ * installs have no full worker, so they MUST drain their own queue or queued
+ * audits/memories age out unsent — but one MCP process runs per Claude Code
+ * window, so we cap the network work each does per light tick. The full
+ * (dashboard) profile keeps its historical unbudgeted cadence.
+ */
+export const MCP_RETRY_QUEUE_BUDGET = 25;

package/dist/xray/dir-scanner.d.ts

@@ -5,6 +5,24 @@
  * and aggregates findings into a single XRayResult.
  */
 import type { XRayResult } from './types.js';
+/**
+ * Hidden directories worth scanning. These hold agent-instruction and CI
+ * surfaces (skills, slash commands, settings hooks, workflow YAML, editor
+ * tasks) — the primary prompt-injection / persistence vectors in an AI-agent
+ * codebase. By default `walkDir` skips ALL dot-directories; this allow-list
+ * carves out the ones X-Ray must inspect. `SKIP_DIRS` always wins, so `.git`
+ * et al. stay excluded even though they're hidden.
+ *
+ * Shared with watch mode (`watch.ts` imports this) so a scan and a watch agree
+ * on exactly which hidden dirs are in scope — one source of truth.
+ */
+export declare const ALLOW_HIDDEN_DIRS: Set<string>;
+/**
+ * Whether to descend into a directory while walking. Recurse when it's not in
+ * the skip-list AND it's either not hidden or explicitly allow-listed. Exported
+ * so watch mode mirrors the identical rule.
+ */
+export declare function shouldWalkDir(name: string): boolean;
 /**
  * Scan an entire directory for X-Ray findings.
  *

package/dist/xray/dir-scanner.js

@@ -15,6 +15,28 @@ const SKIP_DIRS = new Set([
     '__pycache__', '.tox', '.venv', 'venv', '.cache', 'coverage',
     'Caches', 'CacheStorage', 'IndexedDB', 'GPUCache',
 ]);
+/**
+ * Hidden directories worth scanning. These hold agent-instruction and CI
+ * surfaces (skills, slash commands, settings hooks, workflow YAML, editor
+ * tasks) — the primary prompt-injection / persistence vectors in an AI-agent
+ * codebase. By default `walkDir` skips ALL dot-directories; this allow-list
+ * carves out the ones X-Ray must inspect. `SKIP_DIRS` always wins, so `.git`
+ * et al. stay excluded even though they're hidden.
+ *
+ * Shared with watch mode (`watch.ts` imports this) so a scan and a watch agree
+ * on exactly which hidden dirs are in scope — one source of truth.
+ */
+export const ALLOW_HIDDEN_DIRS = new Set([
+    '.github', '.claude', '.cursor', '.codex', '.vscode', '.agents', '.openclaw',
+]);
+/**
+ * Whether to descend into a directory while walking. Recurse when it's not in
+ * the skip-list AND it's either not hidden or explicitly allow-listed. Exported
+ * so watch mode mirrors the identical rule.
+ */
+export function shouldWalkDir(name) {
+    return !SKIP_DIRS.has(name) && (!name.startsWith('.') || ALLOW_HIDDEN_DIRS.has(name));
+}
 /** Absolute path prefixes to never scan — system/OS files that always produce false positives. */
 const SKIP_PATH_PREFIXES = [
     '/System/',
@@ -75,7 +97,7 @@ function walkDir(dirPath, files, depth = 0) {
             break;
         const fullPath = path.join(dirPath, entry.name);
         if (entry.isDirectory()) {
-            if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+            if (shouldWalkDir(entry.name)) {
                 walkDir(fullPath, files, depth + 1);
             }
         }

package/dist/xray/file-scanner.js

@@ -246,9 +246,16 @@ export async function scanFile(filePath, deep) {
     if (!stat.isFile() || stat.size > MAX_FILE_SIZE) {
         return findings;
     }
+    // Read the file body AT MOST ONCE. Each branch records what it read so deep
+    // mode (below) can reuse it instead of re-reading from disk. Previously a
+    // deep scan read every file a second time (and on every other-text file,
+    // walked the same content twice) — pure wasted IO for large trees.
+    let fileBuffer = null;
+    let textContent = null;
     // Route by extension
     if (IMAGE_EXTENSIONS.has(ext)) {
         const buf = fs.readFileSync(filePath);
+        fileBuffer = buf;
         findings.push(...scanImage(filePath, buf));
         // Polyglot check
         const polyglot = checkPolyglot(buf);
@@ -259,6 +266,7 @@ export async function scanFile(filePath, deep) {
     }
     else if (JSON_EXTENSIONS.has(ext)) {
         const content = fs.readFileSync(filePath, 'utf-8');
+        textContent = content;
         findings.push(...scanJson(filePath, content));
         // Zero-width unicode check
         const zw = hasZeroWidthUnicode(content);
@@ -269,6 +277,7 @@ export async function scanFile(filePath, deep) {
     }
     else if (CODE_EXTENSIONS.has(ext)) {
         const content = fs.readFileSync(filePath, 'utf-8');
+        textContent = content;
         findings.push(...detectPatterns(content, filePath));
         // Zero-width unicode check
         const zw = hasZeroWidthUnicode(content);
@@ -281,6 +290,7 @@ export async function scanFile(filePath, deep) {
         // For any other text-like file, try reading as text
         try {
             const buf = fs.readFileSync(filePath);
+            fileBuffer = buf;
             // Check if it's mostly text
             let nonPrintable = 0;
             const sampleSize = Math.min(buf.length, 8192);
@@ -293,6 +303,7 @@ export async function scanFile(filePath, deep) {
             if (nonPrintable / sampleSize < 0.1) {
                 // Treat as text
                 const content = buf.toString('utf-8');
+                textContent = content;
                 findings.push(...detectPatterns(content, filePath));
                 const zw = hasZeroWidthUnicode(content);
                 if (zw) {
@@ -316,7 +327,11 @@ export async function scanFile(filePath, deep) {
     // Deep mode: additional analysis (Pro feature)
     if (deep && stat.size > 0) {
         try {
-            const content = fs.readFileSync(filePath, 'utf-8');
+            // Reuse the content already read above. Derive text from a buffer the
+            // image/binary branch read (no re-read); only hit disk if nothing was
+            // captured (a branch that didn't read, e.g. an early-skipped path).
+            const content = textContent ??
+                (fileBuffer ? fileBuffer.toString('utf-8') : fs.readFileSync(filePath, 'utf-8'));
             // Entropy analysis — detect packed/obfuscated code
             if (CODE_EXTENSIONS.has(ext) || ext === '.js' || ext === '.mjs') {
                 const entropy = shannonEntropy(content);

package/dist/xray/findings-store.js

@@ -43,7 +43,15 @@ export function createFindingsStore(basePath) {
         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)));
+            // Dedupe against EVERY retained finding regardless of status (Phase 17
+            // B5). Previously only `status === 'new'` findings seeded the dedupe set,
+            // so a finding the user had already triaged — ignored, resolved,
+            // reviewed or quarantined — resurfaced as a brand-new duplicate on every
+            // re-scan, undoing their decision. Matching across all statuses respects
+            // the prior triage. (Findings aged past the 30-day cleanup window below
+            // are no longer retained, so they may legitimately reappear — that's the
+            // intended TTL behaviour, not a dedupe miss.)
+            const existingKeys = new Set(existing.map((f) => findingDedupeKey(f.target, f)));
             const newFindings = [];
             for (const f of rawFindings) {
                 const key = findingDedupeKey(target, f);

package/dist/xray/index.d.ts

@@ -18,6 +18,8 @@ export { watchDirectory } from './watch.js';
 export { handlePreinstallCheck } from './preinstall.js';
 export { xrayMemoryContent } from './memory-guard.js';
 export type { MemoryGuardResult } from './memory-guard.js';
+export { toSarif } from './sarif.js';
+export type { SarifLog } from './sarif.js';
 /**
  * Handle the `shieldcortex xray` CLI command.
  */

package/dist/xray/index.js

@@ -16,6 +16,7 @@ import { scanDirectory } from './dir-scanner.js';
 import { inspectNpmPackage } from './npm-inspector.js';
 import { calculateTrustScore } from './trust-score.js';
 import { formatXRayReport, formatXRayMarkdown } from './report.js';
+import { toSarif } from './sarif.js';
 import { watchDirectory } from './watch.js';
 import { appendActivity, appendHistory, createHistoryEntry } from './activity.js';
 export { calculateTrustScore } from './trust-score.js';
@@ -27,6 +28,7 @@ export { formatXRayReport, formatXRayMarkdown } from './report.js';
 export { watchDirectory } from './watch.js';
 export { handlePreinstallCheck } from './preinstall.js';
 export { xrayMemoryContent } from './memory-guard.js';
+export { toSarif } from './sarif.js';
 // ── Usage tracking ──────────────────────────────────────────
 const USAGE_FILE = path.join(os.homedir(), '.shieldcortex', 'xray-usage.json');
 const FREE_DAILY_LIMIT = 5;
@@ -84,6 +86,7 @@ export async function handleXRayCommand(args) {
     const deep = flags.has('--deep');
     const jsonOutput = flags.has('--json');
     const markdownOutput = flags.has('--markdown');
+    const sarifOutput = flags.has('--sarif') || args.includes('--format=sarif');
     const ciMode = flags.has('--ci');
     const watchMode = flags.has('--watch');
     const ciThreshold = (() => {
@@ -100,6 +103,7 @@ export async function handleXRayCommand(args) {
         console.error('  --deep      Deep scan with full analysis (Pro)');
         console.error('  --json      Output JSON result');
         console.error('  --markdown  Output markdown report');
+        console.error('  --sarif     Output SARIF 2.1.0 (GitHub Code Scanning)');
         console.error('  --ci        CI/CD mode: exit code 1 if risk >= threshold');
         console.error('  --threshold=LEVEL  Risk threshold for --ci (CRITICAL|HIGH|MEDIUM|LOW, default: HIGH)');
         console.error('  --watch     Watch directory for changes and scan incrementally');
@@ -201,7 +205,12 @@ export async function handleXRayCommand(args) {
             : `${result.findings.length} findings across ${result.filesScanned} files`,
     });
     // Output
-    if (jsonOutput) {
+    if (sarifOutput) {
+        // Pure SARIF JSON on stdout — nothing else, so the file can be uploaded
+        // straight to GitHub Code Scanning.
+        console.log(JSON.stringify(toSarif(result.findings), null, 2));
+    }
+    else if (jsonOutput) {
         console.log(JSON.stringify(result, null, 2));
     }
     else if (markdownOutput) {

package/dist/xray/npm-inspector.d.ts

@@ -6,6 +6,37 @@
  * Uses only Node.js built-ins (https module) — no new dependencies.
  */
 import type { XRayResult } from './types.js';
+/**
+ * Decide whether another redirect hop may be followed. Returns the remaining
+ * budget for the next hop, or `null` when the cap is exhausted. Pure + exported
+ * so the redirect bound can be unit-tested without standing up a TLS server.
+ */
+export declare function nextRedirectBudget(redirectsLeft: number): number | null;
+/**
+ * Simple HTTPS GET returning the response body as a string.
+ *
+ * Bounds redirect following (max MAX_REDIRECTS hops) and applies a socket
+ * timeout so a hostile / mis-configured registry cannot loop or hang us.
+ */
+export declare function httpsGet(url: string, redirectsLeft?: number): Promise<string>;
+/**
+ * A minimal readable-stream shape: emits `data` (Buffer), then `end`, or
+ * `error`. Lets the decompressed-size guard be unit-tested against a tiny fake
+ * stream without producing a real 100 MB tarball.
+ */
+export interface DecompressStream {
+    on(event: 'data', listener: (chunk: Buffer) => void): unknown;
+    on(event: 'end', listener: () => void): unknown;
+    on(event: 'error', listener: (err: Error) => void): unknown;
+    destroy?(err?: Error): unknown;
+}
+/**
+ * Accumulate a decompressed stream into a single Buffer, aborting if the total
+ * exceeds `maxBytes`. This is the gzip-bomb guard: a hostile .tgz can be tiny
+ * on disk yet decompress to gigabytes, so we cap the INFLATED size, not just
+ * the download. Pure (no fs/network) so it can be tested with a fake stream.
+ */
+export declare function collectDecompressed(stream: DecompressStream, maxBytes?: number): Promise<Buffer>;
 /**
  * Inspect an npm package for hidden risk.
  *

package/dist/xray/npm-inspector.js

@@ -14,6 +14,22 @@ import { detectPatterns } from './patterns.js';
 import { calculateTrustScore } from './trust-score.js';
 import { scanFile } from './file-scanner.js';
 // ── Constants ───────────────────────────────────────────────
+/**
+ * DoS caps for the deep tarball scan. A hostile package can ship a tiny .tgz
+ * that decompresses to gigabytes (a zip/gzip "bomb"), redirect a fetch in an
+ * endless loop, or hang a socket open forever. These bounds keep the scanner
+ * from OOMing or stalling on adversarial input.
+ */
+/** Max bytes we will download for a tarball (compressed, on the wire). */
+const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024; // 50 MB
+/** Max bytes a tarball may decompress to before we abort (gzip-bomb guard). */
+const MAX_DECOMPRESSED_BYTES = 100 * 1024 * 1024; // 100 MB
+/** Max number of entries we will extract from a single tarball. */
+const MAX_TARBALL_ENTRIES = 10_000;
+/** Max HTTP redirect hops to follow before giving up. */
+const MAX_REDIRECTS = 5;
+/** Per-request network timeout (no response / stalled socket). */
+const FETCH_TIMEOUT_MS = 30_000;
 /** Popular npm packages for typosquat comparison. */
 const POPULAR_PACKAGES = [
     'react', 'express', 'lodash', 'axios', 'chalk', 'commander', 'debug',
@@ -26,14 +42,33 @@ const POPULAR_PACKAGES = [
     'redis', 'mongodb', 'sequelize', 'prisma', 'graphql', 'apollo',
 ];
 // ── Helpers ─────────────────────────────────────────────────
+/**
+ * Decide whether another redirect hop may be followed. Returns the remaining
+ * budget for the next hop, or `null` when the cap is exhausted. Pure + exported
+ * so the redirect bound can be unit-tested without standing up a TLS server.
+ */
+export function nextRedirectBudget(redirectsLeft) {
+    if (redirectsLeft <= 0)
+        return null;
+    return redirectsLeft - 1;
+}
 /**
  * Simple HTTPS GET returning the response body as a string.
+ *
+ * Bounds redirect following (max MAX_REDIRECTS hops) and applies a socket
+ * timeout so a hostile / mis-configured registry cannot loop or hang us.
  */
-function httpsGet(url) {
+export function httpsGet(url, redirectsLeft = MAX_REDIRECTS) {
     return new Promise((resolve, reject) => {
-        https.get(url, { headers: { 'Accept': 'application/json' } }, (res) => {
+        const req = 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);
+                res.resume(); // drain the redirect response so the socket can be reused/freed
+                const budget = nextRedirectBudget(redirectsLeft);
+                if (budget === null) {
+                    reject(new Error(`Too many redirects (>${MAX_REDIRECTS}) for ${url}`));
+                    return;
+                }
+                httpsGet(res.headers.location, budget).then(resolve, reject);
                 return;
             }
             if (res.statusCode !== 200) {
@@ -45,75 +80,146 @@ function httpsGet(url) {
             res.on('data', (chunk) => chunks.push(chunk));
             res.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
             res.on('error', reject);
-        }).on('error', reject);
+        });
+        req.setTimeout(FETCH_TIMEOUT_MS, () => {
+            req.destroy(new Error(`Request timed out after ${FETCH_TIMEOUT_MS}ms for ${url}`));
+        });
+        req.on('error', reject);
     });
 }
 /**
  * Download a tarball to a temp file and return the path.
+ *
+ * Bounds redirect following, applies a socket timeout, and caps the number of
+ * downloaded bytes (MAX_DOWNLOAD_BYTES) so an attacker cannot fill the disk or
+ * stream forever. The compressed cap is a first line of defence; the
+ * decompressed cap in extractTarball is the gzip-bomb guard.
  */
 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) => {
+        let settled = false;
+        const fail = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            file.destroy();
+            fs.rm(tmpFile, { force: true }, () => reject(err));
+        };
+        const doGet = (targetUrl, redirectsLeft) => {
+            const req = https.get(targetUrl, (res) => {
                 if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-                    doGet(res.headers.location);
+                    res.resume();
+                    if (redirectsLeft <= 0) {
+                        fail(new Error(`Too many redirects (>${MAX_REDIRECTS}) downloading tarball`));
+                        return;
+                    }
+                    doGet(res.headers.location, redirectsLeft - 1);
                     return;
                 }
                 if (res.statusCode !== 200) {
-                    reject(new Error(`HTTP ${res.statusCode} downloading tarball`));
                     res.resume();
+                    fail(new Error(`HTTP ${res.statusCode} downloading tarball`));
                     return;
                 }
+                let downloaded = 0;
+                res.on('data', (chunk) => {
+                    downloaded += chunk.length;
+                    if (downloaded > MAX_DOWNLOAD_BYTES) {
+                        req.destroy();
+                        fail(new Error(`Tarball exceeds ${MAX_DOWNLOAD_BYTES} byte download cap`));
+                    }
+                });
                 res.pipe(file);
                 file.on('finish', () => {
+                    if (settled)
+                        return;
+                    settled = true;
                     file.close();
                     resolve(tmpFile);
                 });
-            }).on('error', reject);
+                res.on('error', fail);
+            });
+            req.setTimeout(FETCH_TIMEOUT_MS, () => {
+                req.destroy(new Error(`Tarball download timed out after ${FETCH_TIMEOUT_MS}ms`));
+            });
+            req.on('error', fail);
         };
-        doGet(url);
+        file.on('error', fail);
+        doGet(url, MAX_REDIRECTS);
     });
 }
 /**
- * Extract a .tgz to a temp directory using Node built-ins (zlib + tar parsing).
- * Returns path to the extracted directory.
+ * Accumulate a decompressed stream into a single Buffer, aborting if the total
+ * exceeds `maxBytes`. This is the gzip-bomb guard: a hostile .tgz can be tiny
+ * on disk yet decompress to gigabytes, so we cap the INFLATED size, not just
+ * the download. Pure (no fs/network) so it can be tested with a fake stream.
  */
-async function extractTarball(tgzPath) {
-    const extractDir = path.join(os.tmpdir(), `shieldcortex-xray-extract-${Date.now()}`);
-    fs.mkdirSync(extractDir, { recursive: true });
+export function collectDecompressed(stream, maxBytes = MAX_DECOMPRESSED_BYTES) {
     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);
+        let total = 0;
+        let aborted = false;
+        stream.on('data', (chunk) => {
+            if (aborted)
+                return;
+            total += chunk.length;
+            if (total > maxBytes) {
+                aborted = true;
+                stream.destroy?.(new Error('aborted: decompressed size cap exceeded'));
+                reject(new Error(`Decompressed tarball exceeds ${maxBytes} byte cap (possible gzip bomb)`));
+                return;
             }
+            chunks.push(chunk);
+        });
+        stream.on('end', () => {
+            if (aborted)
+                return;
+            resolve(Buffer.concat(chunks));
+        });
+        stream.on('error', (err) => {
+            if (aborted)
+                return;
+            reject(err);
         });
-        gunzip.on('error', reject);
-        input.on('error', reject);
     });
 }
+/**
+ * Extract a .tgz to a temp directory using Node built-ins (zlib + tar parsing).
+ * Returns path to the extracted directory.
+ *
+ * Enforces the decompressed-size cap (gzip-bomb guard) while inflating and the
+ * entry-count cap while parsing the tar.
+ */
+async function extractTarball(tgzPath) {
+    const extractDir = path.join(os.tmpdir(), `shieldcortex-xray-extract-${Date.now()}`);
+    fs.mkdirSync(extractDir, { recursive: true });
+    const gunzip = createGunzip();
+    const input = fs.createReadStream(tgzPath);
+    input.on('error', (err) => gunzip.destroy(err));
+    input.pipe(gunzip);
+    const tarData = await collectDecompressed(gunzip);
+    extractTarBuffer(tarData, extractDir);
+    return extractDir;
+}
 /**
  * Minimal tar extraction from a buffer. Handles ustar format.
  */
 function extractTarBuffer(buf, outDir) {
     let offset = 0;
+    let entries = 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;
+        // Entry-count cap: a hostile tarball can pack millions of tiny entries to
+        // exhaust inodes / fd churn even within the decompressed-size cap.
+        if (++entries > MAX_TARBALL_ENTRIES) {
+            throw new Error(`Tarball exceeds ${MAX_TARBALL_ENTRIES} entry cap`);
+        }
         // 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');

package/dist/xray/patterns.d.ts

@@ -4,7 +4,7 @@
  * 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
+ *   - Overlapping windowed scanning to bound per-regex work (ReDOS guard)
  *   - PatternGroup style with weighted confidence
  *   - One match per group is enough (break after first)
  */