muaddib-scanner 2.1.0 → 2.1.1

package/bin/muaddib.js

@@ -561,7 +561,10 @@ if (command === 'version' || command === '--version' || command === '-v') {
   } else {
     // Start full monitor
     const { startMonitor } = require('../src/monitor.js');
-    startMonitor().catch(err => {
+    const monitorOpts = {
+      verbose: options.includes('--verbose')
+    };
+    startMonitor(monitorOpts).catch(err => {
       console.error('[ERROR]', err.message);
       process.exit(1);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muaddib-scanner",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Supply-chain threat detection & response for npm & PyPI/Python",
   "main": "src/index.js",
   "bin": {

package/src/index.js

@@ -723,15 +723,12 @@ async function run(targetPath, options = {}) {
         const countStr = t.count > 1 ? ` (x${t.count})` : '';
         console.log(`  ${i + 1}. [${t.severity}] ${t.type}${countStr}`);
         console.log(`     ${t.message}`);
-        console.log(`     File: ${t.file}\n`);
-      });
-
-      console.log('[RESPONSE] Recommendations:\n');
-      deduped.forEach(t => {
+        console.log(`     File: ${t.file}`);
         const playbook = getPlaybook(t.type);
         if (playbook) {
-          console.log(`  -> ${playbook}\n`);
+          console.log(`     \u2192 ${playbook}`);
         }
+        console.log('');
       });
     }
 

package/src/ioc/scraper.js

@@ -1,10 +1,12 @@
 const https = require('https');
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const AdmZip = require('adm-zip');
 
 const IOC_FILE = path.join(__dirname, 'data/iocs.json');
 const COMPACT_IOC_FILE = path.join(__dirname, 'data/iocs-compact.json');
+const HOME_IOC_FILE = path.join(os.homedir(), '.muaddib', 'data', 'iocs.json');
 const STATIC_IOCS_FILE = path.join(__dirname, '../../data/static-iocs.json');
 const { generateCompactIOCs } = require('./updater.js');
 const { Spinner } = require('../utils.js');
@@ -623,11 +625,11 @@ async function scrapeOSSFMaliciousPackages(knownIds) {
       return packages;
     }
 
-    // Incremental: compare tree SHA
+    // Incremental: compare tree SHA (stored in ~/.muaddib/data/ to persist across npm updates)
     const treeSha = data.sha;
-    const dataDir = path.join(__dirname, 'data');
-    if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
-    const shaFile = path.join(dataDir, '.ossf-tree-sha');
+    const homeDir = path.dirname(HOME_IOC_FILE);
+    if (!fs.existsSync(homeDir)) fs.mkdirSync(homeDir, { recursive: true });
+    const shaFile = path.join(homeDir, '.ossf-tree-sha');
     let lastSha = null;
     try { lastSha = fs.readFileSync(shaFile, 'utf8').trim(); } catch {}
 
@@ -1004,9 +1006,18 @@ async function runScraper() {
     throw new Error(`Data directory is not writable: ${dataDir}`);
   }
 
-  // Load existing IOCs
+  // Load existing IOCs (check ~/.muaddib/data/ first, then local)
   let existingIOCs = { packages: [], pypi_packages: [], hashes: [], markers: [], files: [] };
-  if (fs.existsSync(IOC_FILE)) {
+  if (fs.existsSync(HOME_IOC_FILE)) {
+    try {
+      existingIOCs = JSON.parse(fs.readFileSync(HOME_IOC_FILE, 'utf8'));
+      if (!existingIOCs.pypi_packages) existingIOCs.pypi_packages = [];
+      console.log('[INFO] Loaded existing IOCs from ' + HOME_IOC_FILE);
+    } catch {
+      console.log('[WARN] Home IOCs file corrupted, trying local...');
+    }
+  }
+  if (existingIOCs.packages.length === 0 && fs.existsSync(IOC_FILE)) {
     try {
       existingIOCs = JSON.parse(fs.readFileSync(IOC_FILE, 'utf8'));
       if (!existingIOCs.pypi_packages) existingIOCs.pypi_packages = [];
@@ -1186,7 +1197,21 @@ async function runScraper() {
   const tmpCompactFile = COMPACT_IOC_FILE + '.tmp';
   fs.writeFileSync(tmpCompactFile, JSON.stringify(compactIOCs));
   fs.renameSync(tmpCompactFile, COMPACT_IOC_FILE);
-  saveSpinner.succeed('Saved IOCs + compact format');
+
+  // Persist to ~/.muaddib/data/ (survives npm update)
+  saveSpinner.update('Persisting to home directory...');
+  const homeDir = path.dirname(HOME_IOC_FILE);
+  if (!fs.existsSync(homeDir)) {
+    fs.mkdirSync(homeDir, { recursive: true });
+  }
+  try {
+    const tmpHomeFile = HOME_IOC_FILE + '.tmp';
+    fs.writeFileSync(tmpHomeFile, JSON.stringify(existingIOCs, null, 2));
+    fs.renameSync(tmpHomeFile, HOME_IOC_FILE);
+    saveSpinner.succeed('Saved IOCs + compact format + home directory');
+  } catch (e) {
+    saveSpinner.succeed('Saved IOCs + compact format (home dir write failed: ' + e.message + ')');
+  }
 
   // Display summary
   console.log('\n' + '='.repeat(60));

package/src/ioc/updater.js

@@ -1,8 +1,9 @@
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 
-const CACHE_PATH = path.join(__dirname, '../../.muaddib-cache');
-const CACHE_IOC_FILE = path.join(CACHE_PATH, 'iocs.json');
+const HOME_DATA_PATH = path.join(os.homedir(), '.muaddib', 'data');
+const CACHE_IOC_FILE = path.join(HOME_DATA_PATH, 'iocs.json');
 const LOCAL_IOC_FILE = path.join(__dirname, 'data/iocs.json');
 const LOCAL_COMPACT_FILE = path.join(__dirname, 'data/iocs-compact.json');
 const { loadYAMLIOCs } = require('./yaml-loader.js');
@@ -56,16 +57,16 @@ async function updateIOCs() {
   mergeIOCs(baseIOCs, githubIOCs);
   console.log('     +' + shaiHulud.packages.length + ' GenSecAI, +' + datadog.packages.length + ' DataDog');
 
-  // Step 4: Merge and save to cache
-  if (!fs.existsSync(CACHE_PATH)) {
-    fs.mkdirSync(CACHE_PATH, { recursive: true });
+  // Step 4: Merge and save to cache (~/.muaddib/data/ — persists across npm updates)
+  if (!fs.existsSync(HOME_DATA_PATH)) {
+    fs.mkdirSync(HOME_DATA_PATH, { recursive: true });
   }
 
   // Verify write permission before attempting save (CROSS-001)
   try {
-    fs.accessSync(CACHE_PATH, fs.constants.W_OK);
+    fs.accessSync(HOME_DATA_PATH, fs.constants.W_OK);
   } catch {
-    console.log('[WARN] Cache directory is not writable: ' + CACHE_PATH);
+    console.log('[WARN] Cache directory is not writable: ' + HOME_DATA_PATH);
     console.log('[WARN] IOCs loaded in memory but not persisted to disk.');
     return { total: baseIOCs.packages.length, totalPyPI: (baseIOCs.pypi_packages || []).length };
   }

package/src/monitor.js

@@ -2,7 +2,6 @@ const https = require('https');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { execSync } = require('child_process');
 const { run } = require('./index.js');
 const { runSandbox, isDockerAvailable } = require('./sandbox.js');
 const { sendWebhook } = require('./webhook.js');
@@ -10,13 +9,14 @@ const { detectSuddenLifecycleChange } = require('./temporal-analysis.js');
 const { detectSuddenAstChanges } = require('./temporal-ast-diff.js');
 const { detectPublishAnomaly } = require('./publish-anomaly.js');
 const { detectMaintainerChange } = require('./maintainer-change.js');
+const { downloadToFile, extractTarGz, sanitizePackageName } = require('./shared/download.js');
+const { MAX_TARBALL_SIZE } = require('./shared/constants.js');
 
 const STATE_FILE = path.join(__dirname, '..', 'data', 'monitor-state.json');
 const ALERTS_FILE = path.join(__dirname, '..', 'data', 'monitor-alerts.json');
 const DETECTIONS_FILE = path.join(__dirname, '..', 'data', 'detections.json');
 const SCAN_STATS_FILE = path.join(__dirname, '..', 'data', 'scan-stats.json');
 const POLL_INTERVAL = 60_000;
-const MAX_TARBALL_SIZE = 50 * 1024 * 1024; // 50MB
 const SCAN_TIMEOUT_MS = 180_000; // 3 minutes per package
 
 // --- Stats counters ---
@@ -93,6 +93,35 @@ function hasHighOrCritical(result) {
   return result.summary.critical > 0 || result.summary.high > 0;
 }
 
+// --- Verbose mode (--verbose sends ALL alerts including temporal/publish/maintainer) ---
+
+let verboseMode = false;
+
+function isVerboseMode() {
+  if (verboseMode) return true;
+  const env = process.env.MUADDIB_MONITOR_VERBOSE;
+  return env !== undefined && env.toLowerCase() === 'true';
+}
+
+function setVerboseMode(value) {
+  verboseMode = !!value;
+}
+
+// --- IOC match types (these are the only static-analysis types that warrant a webhook) ---
+
+const IOC_MATCH_TYPES = new Set([
+  'known_malicious_package',
+  'known_malicious_hash',
+  'pypi_malicious_package',
+  'shai_hulud_marker',
+  'shai_hulud_backdoor'
+]);
+
+function hasIOCMatch(result) {
+  if (!result || !result.threats) return false;
+  return result.threats.some(t => IOC_MATCH_TYPES.has(t.type));
+}
+
 // --- Webhook alerting ---
 
 function getWebhookUrl() {
@@ -107,9 +136,10 @@ function shouldSendWebhook(result, sandboxResult) {
     return sandboxResult.score > 0;
   }
 
-  // No sandbox — fall back to static analysis thresholds
-  if (result.summary.critical > 0) return true;
-  if (result.summary.high > 0 && computeRiskScore(result.summary) >= 25) return true;
+  // No sandbox — only send webhook for confirmed IOC matches
+  // (known_malicious_package, known_malicious_hash, pypi_malicious_package, etc.)
+  if (hasIOCMatch(result)) return true;
+
   return false;
 }
 
@@ -223,13 +253,17 @@ function buildTemporalWebhookEmbed(temporalResult) {
 }
 
 async function tryTemporalAlert(temporalResult) {
+  // Temporal anomalies are logged only — no webhook unless --verbose
+  console.log(`[MONITOR] ANOMALY (logged only): temporal lifecycle change for ${temporalResult.packageName}`);
+  if (!isVerboseMode()) return;
+
   const url = getWebhookUrl();
   if (!url) return;
 
   const payload = buildTemporalWebhookEmbed(temporalResult);
   try {
     await sendWebhook(url, payload, { rawPayload: true });
-    console.log(`[MONITOR] Temporal webhook sent for ${temporalResult.packageName}`);
+    console.log(`[MONITOR] Temporal webhook sent for ${temporalResult.packageName} (verbose mode)`);
   } catch (err) {
     console.error(`[MONITOR] Temporal webhook failed for ${temporalResult.packageName}: ${err.message}`);
   }
@@ -276,13 +310,17 @@ function buildTemporalAstWebhookEmbed(astResult) {
 }
 
 async function tryTemporalAstAlert(astResult) {
+  // AST anomalies are logged only — no webhook unless --verbose
+  console.log(`[MONITOR] ANOMALY (logged only): AST change for ${astResult.packageName}`);
+  if (!isVerboseMode()) return;
+
   const url = getWebhookUrl();
   if (!url) return;
 
   const payload = buildTemporalAstWebhookEmbed(astResult);
   try {
     await sendWebhook(url, payload, { rawPayload: true });
-    console.log(`[MONITOR] Temporal AST webhook sent for ${astResult.packageName}`);
+    console.log(`[MONITOR] Temporal AST webhook sent for ${astResult.packageName} (verbose mode)`);
   } catch (err) {
     console.error(`[MONITOR] Temporal AST webhook failed for ${astResult.packageName}: ${err.message}`);
   }
@@ -370,13 +408,17 @@ function buildPublishAnomalyWebhookEmbed(publishResult) {
 }
 
 async function tryTemporalPublishAlert(publishResult) {
+  // Publish anomalies are logged only — no webhook unless --verbose
+  console.log(`[MONITOR] ANOMALY (logged only): publish frequency for ${publishResult.packageName}`);
+  if (!isVerboseMode()) return;
+
   const url = getWebhookUrl();
   if (!url) return;
 
   const payload = buildPublishAnomalyWebhookEmbed(publishResult);
   try {
     await sendWebhook(url, payload, { rawPayload: true });
-    console.log(`[MONITOR] Publish anomaly webhook sent for ${publishResult.packageName}`);
+    console.log(`[MONITOR] Publish anomaly webhook sent for ${publishResult.packageName} (verbose mode)`);
   } catch (err) {
     console.error(`[MONITOR] Publish anomaly webhook failed for ${publishResult.packageName}: ${err.message}`);
   }
@@ -467,13 +509,17 @@ function buildMaintainerChangeWebhookEmbed(maintainerResult) {
 }
 
 async function tryTemporalMaintainerAlert(maintainerResult) {
+  // Maintainer changes are logged only — no webhook unless --verbose
+  console.log(`[MONITOR] ANOMALY (logged only): maintainer change for ${maintainerResult.packageName}`);
+  if (!isVerboseMode()) return;
+
   const url = getWebhookUrl();
   if (!url) return;
 
   const payload = buildMaintainerChangeWebhookEmbed(maintainerResult);
   try {
     await sendWebhook(url, payload, { rawPayload: true });
-    console.log(`[MONITOR] Maintainer change webhook sent for ${maintainerResult.packageName}`);
+    console.log(`[MONITOR] Maintainer change webhook sent for ${maintainerResult.packageName} (verbose mode)`);
   } catch (err) {
     console.error(`[MONITOR] Maintainer change webhook failed for ${maintainerResult.packageName}: ${err.message}`);
   }
@@ -618,81 +664,6 @@ function httpsGet(url, timeoutMs = 30_000) {
   });
 }
 
-// --- Download & extraction helpers ---
-
-function downloadToFile(url, destPath, timeoutMs = 30_000) {
-  return new Promise((resolve, reject) => {
-    const doRequest = (requestUrl) => {
-      const req = https.get(requestUrl, { timeout: timeoutMs }, (res) => {
-        if (res.statusCode === 301 || res.statusCode === 302) {
-          res.resume();
-          const location = res.headers.location;
-          if (!location) return reject(new Error(`Redirect without Location for ${requestUrl}`));
-          return doRequest(location);
-        }
-        if (res.statusCode < 200 || res.statusCode >= 300) {
-          res.resume();
-          return reject(new Error(`HTTP ${res.statusCode} for ${requestUrl}`));
-        }
-        const contentLength = parseInt(res.headers['content-length'], 10);
-        if (contentLength && contentLength > MAX_TARBALL_SIZE) {
-          res.resume();
-          return reject(new Error(`Package too large: ${contentLength} bytes (max ${MAX_TARBALL_SIZE})`));
-        }
-        const fileStream = fs.createWriteStream(destPath);
-        let downloadedBytes = 0;
-        res.on('data', (chunk) => {
-          downloadedBytes += chunk.length;
-          if (downloadedBytes > MAX_TARBALL_SIZE) {
-            res.destroy();
-            fileStream.destroy();
-            try { fs.unlinkSync(destPath); } catch {}
-            reject(new Error(`Package too large: ${downloadedBytes}+ bytes (max ${MAX_TARBALL_SIZE})`));
-          }
-        });
-        res.pipe(fileStream);
-        fileStream.on('finish', () => resolve(downloadedBytes));
-        fileStream.on('error', (err) => {
-          try { fs.unlinkSync(destPath); } catch {}
-          reject(err);
-        });
-        res.on('error', (err) => {
-          fileStream.destroy();
-          try { fs.unlinkSync(destPath); } catch {}
-          reject(err);
-        });
-      });
-      req.on('error', reject);
-      req.on('timeout', () => {
-        req.destroy();
-        reject(new Error(`Timeout downloading ${requestUrl}`));
-      });
-    };
-    doRequest(url);
-  });
-}
-
-function extractTarGz(tgzPath, destDir) {
-  // Use cwd + relative paths so C: never appears in tar arguments
-  // (GNU tar treats C: as remote host, bsdtar doesn't support --force-local)
-  const tgzDir = path.dirname(path.resolve(tgzPath));
-  const tgzName = path.basename(tgzPath);
-  const relDest = path.relative(tgzDir, path.resolve(destDir)) || '.';
-  execSync(`tar xzf "${tgzName}" -C "${relDest}"`, { cwd: tgzDir, timeout: 60_000, stdio: 'pipe' });
-  // npm tarballs extract into a package/ subdirectory; detect it
-  const packageSubdir = path.join(destDir, 'package');
-  if (fs.existsSync(packageSubdir) && fs.statSync(packageSubdir).isDirectory()) {
-    return packageSubdir;
-  }
-  // Otherwise return destDir itself (PyPI sdists vary)
-  const entries = fs.readdirSync(destDir);
-  if (entries.length === 1) {
-    const single = path.join(destDir, entries[0]);
-    if (fs.statSync(single).isDirectory()) return single;
-  }
-  return destDir;
-}
-
 // --- Tarball URL helpers ---
 
 function getNpmTarballUrl(pkgData) {
@@ -702,7 +673,12 @@ function getNpmTarballUrl(pkgData) {
 async function getPyPITarballUrl(packageName) {
   const url = `https://pypi.org/pypi/${encodeURIComponent(packageName)}/json`;
   const body = await httpsGet(url);
-  const data = JSON.parse(body);
+  let data;
+  try {
+    data = JSON.parse(body);
+  } catch (e) {
+    throw new Error(`Invalid JSON from PyPI for ${packageName}: ${e.message}`);
+  }
   const version = (data.info && data.info.version) || '';
   const urls = data.urls || [];
   // Prefer sdist (.tar.gz)
@@ -871,7 +847,7 @@ async function scanPackage(name, version, ecosystem, tarballUrl) {
   const startTime = Date.now();
   const tmpBase = path.join(os.tmpdir(), 'muaddib-monitor');
   if (!fs.existsSync(tmpBase)) fs.mkdirSync(tmpBase, { recursive: true });
-  const tmpDir = fs.mkdtempSync(path.join(tmpBase, `${name.replace(/\//g, '_')}-`));
+  const tmpDir = fs.mkdtempSync(path.join(tmpBase, `${sanitizePackageName(name)}-`));
 
   try {
     const tgzPath = path.join(tmpDir, 'package.tar.gz');
@@ -1134,7 +1110,12 @@ function parseNpmRss(xml) {
 async function getNpmLatestTarball(packageName) {
   const url = `https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`;
   const body = await httpsGet(url);
-  const data = JSON.parse(body);
+  let data;
+  try {
+    data = JSON.parse(body);
+  } catch (e) {
+    throw new Error(`Invalid JSON from npm registry for ${packageName}: ${e.message}`);
+  }
   const version = data.version || '';
   const tarball = (data.dist && data.dist.tarball) || null;
   return { version, tarball };
@@ -1259,7 +1240,11 @@ async function pollPyPI(state) {
 
 // --- Main loop ---
 
-async function startMonitor() {
+async function startMonitor(options) {
+  if (options && options.verbose) {
+    setVerboseMode(true);
+  }
+
   console.log(`
 ╔════════════════════════════════════════════╗
 ║     MUAD'DIB - Registry Monitor           ║
@@ -1311,6 +1296,15 @@ async function startMonitor() {
     console.log('[MONITOR] Maintainer change analysis disabled (MUADDIB_MONITOR_TEMPORAL_MAINTAINER=false)');
   }
 
+  // Webhook filtering mode
+  if (isVerboseMode()) {
+    console.log('[MONITOR] Verbose mode ON — ALL anomalies sent as webhooks (temporal, publish, maintainer, AST)');
+  } else {
+    console.log('[MONITOR] Strict webhook mode — only IOC matches, sandbox confirmations, and canary exfiltrations trigger webhooks');
+    console.log('[MONITOR]   Temporal/publish/maintainer anomalies are logged but NOT sent as webhooks');
+    console.log('[MONITOR]   Use --verbose to send all anomalies as webhooks');
+  }
+
   const state = loadState();
   console.log(`[MONITOR] State loaded — npm last: ${state.npmLastPackage || 'none'}, pypi last: ${state.pypiLastPackage || 'none'}`);
   console.log(`[MONITOR] Polling every ${POLL_INTERVAL / 1000}s. Ctrl+C to stop.\n`);
@@ -1538,6 +1532,10 @@ module.exports = {
   isCanaryEnabled,
   buildCanaryExfiltrationWebhookEmbed,
   isPublishAnomalyOnly,
+  isVerboseMode,
+  setVerboseMode,
+  hasIOCMatch,
+  IOC_MATCH_TYPES,
   DETECTIONS_FILE,
   appendDetection,
   loadDetections,

package/src/safe-install.js

@@ -2,10 +2,7 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { loadCachedIOCs } = require('./ioc/updater.js');
-const { REHABILITATED_PACKAGES } = require('./shared/constants.js');
-
-// Regex to validate npm package names (prevents command injection)
-const NPM_PACKAGE_REGEX = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+const { REHABILITATED_PACKAGES, NPM_PACKAGE_REGEX } = require('./shared/constants.js');
 
 /**
  * Validates that a package name is safe (no command injection)

package/src/sandbox.js

@@ -8,9 +8,10 @@ const {
   detectCanaryInOutput
 } = require('./canary-tokens.js');
 
+const { NPM_PACKAGE_REGEX } = require('./shared/constants.js');
+
 const DOCKER_IMAGE = 'muaddib-sandbox';
 const CONTAINER_TIMEOUT = 120000; // 120 seconds
-const NPM_PACKAGE_REGEX = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
 
 // Domains excluded from network findings (false positives)
 const SAFE_DOMAINS = [

package/src/scanner/npm-registry.js

@@ -1,10 +1,11 @@
+const { NPM_PACKAGE_REGEX } = require('../shared/constants.js');
+
 const REGISTRY_URL = 'https://registry.npmjs.org';
 const DOWNLOADS_URL = 'https://api.npmjs.org/downloads/point/last-week';
 const SEARCH_URL = 'https://registry.npmjs.org/-/v1/search';
 
 const REQUEST_TIMEOUT = 10000; // 10 seconds
 const MAX_RETRIES = 3;
-const NPM_NAME_REGEX = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
 
 /**
  * Create a timeout signal, with fallback for older Node versions.
@@ -75,7 +76,7 @@ async function fetchWithRetry(url) {
 
 async function getPackageMetadata(packageName) {
   // Validate package name before building URL
-  if (!NPM_NAME_REGEX.test(packageName)) return null;
+  if (!NPM_PACKAGE_REGEX.test(packageName)) return null;
 
   // 1. Registry metadata
   const registryUrl = REGISTRY_URL + '/' + encodeURIComponent(packageName);

package/src/shared/constants.js

@@ -79,4 +79,11 @@ const REHABILITATED_PACKAGES = {
   }
 };
 
-module.exports = { REHABILITATED_PACKAGES };
+// Regex to validate npm package names (prevents command injection)
+const NPM_PACKAGE_REGEX = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+
+// Download/extraction limits
+const MAX_TARBALL_SIZE = 50 * 1024 * 1024; // 50MB
+const DOWNLOAD_TIMEOUT = 30_000; // 30 seconds
+
+module.exports = { REHABILITATED_PACKAGES, NPM_PACKAGE_REGEX, MAX_TARBALL_SIZE, DOWNLOAD_TIMEOUT };

package/src/shared/download.js

@@ -0,0 +1,171 @@
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { MAX_TARBALL_SIZE, DOWNLOAD_TIMEOUT } = require('./constants.js');
+
+// Allowed redirect domains for tarball downloads (SSRF protection)
+const ALLOWED_DOWNLOAD_DOMAINS = [
+  'registry.npmjs.org',
+  'registry.yarnpkg.com',
+  'pypi.org',
+  'files.pythonhosted.org'
+];
+
+// Private IP ranges — block redirects to internal networks
+const PRIVATE_IP_PATTERNS = [
+  /^127\./,
+  /^10\./,
+  /^172\.(1[6-9]|2[0-9]|3[0-1])\./,
+  /^192\.168\./,
+  /^0\./,
+  /^169\.254\./,
+  /^::1$/,
+  /^::ffff:127\./,
+  /^fc00:/,
+  /^fe80:/
+];
+
+/**
+ * Validates that a redirect URL is allowed (SSRF protection).
+ * Only HTTPS to whitelisted domains is permitted.
+ * @param {string} redirectUrl - The redirect target URL
+ * @returns {{allowed: boolean, error?: string}}
+ */
+function isAllowedDownloadRedirect(redirectUrl) {
+  try {
+    const urlObj = new URL(redirectUrl);
+    if (urlObj.protocol !== 'https:') {
+      return { allowed: false, error: `Redirect blocked: non-HTTPS protocol ${urlObj.protocol}` };
+    }
+    const hostname = urlObj.hostname.toLowerCase();
+    // Block private IP addresses
+    if (PRIVATE_IP_PATTERNS.some(p => p.test(hostname))) {
+      return { allowed: false, error: `Redirect blocked: private IP ${hostname}` };
+    }
+    const domainAllowed = ALLOWED_DOWNLOAD_DOMAINS.some(domain =>
+      hostname === domain || hostname.endsWith('.' + domain)
+    );
+    if (!domainAllowed) {
+      return { allowed: false, error: `Redirect blocked: domain ${hostname} not in allowlist` };
+    }
+    return { allowed: true };
+  } catch {
+    return { allowed: false, error: `Redirect blocked: invalid URL ${redirectUrl}` };
+  }
+}
+
+/**
+ * Download a file from HTTPS URL to disk, with SSRF-safe redirect handling.
+ * @param {string} url - Source URL (must be HTTPS)
+ * @param {string} destPath - Local file path to write to
+ * @param {number} [timeoutMs] - Download timeout in ms (default: DOWNLOAD_TIMEOUT)
+ * @returns {Promise<number>} Number of bytes downloaded
+ */
+function downloadToFile(url, destPath, timeoutMs = DOWNLOAD_TIMEOUT) {
+  return new Promise((resolve, reject) => {
+    const doRequest = (requestUrl) => {
+      const req = https.get(requestUrl, { timeout: timeoutMs }, (res) => {
+        if (res.statusCode === 301 || res.statusCode === 302) {
+          res.resume();
+          const location = res.headers.location;
+          if (!location) return reject(new Error(`Redirect without Location for ${requestUrl}`));
+          // Resolve relative redirects against the request URL
+          const absoluteLocation = new URL(location, requestUrl).href;
+          const check = isAllowedDownloadRedirect(absoluteLocation);
+          if (!check.allowed) {
+            return reject(new Error(check.error));
+          }
+          return doRequest(absoluteLocation);
+        }
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          res.resume();
+          return reject(new Error(`HTTP ${res.statusCode} for ${requestUrl}`));
+        }
+        const contentLength = parseInt(res.headers['content-length'], 10);
+        if (contentLength && contentLength > MAX_TARBALL_SIZE) {
+          res.resume();
+          return reject(new Error(`Package too large: ${contentLength} bytes (max ${MAX_TARBALL_SIZE})`));
+        }
+        const fileStream = fs.createWriteStream(destPath);
+        let downloadedBytes = 0;
+        res.on('data', (chunk) => {
+          downloadedBytes += chunk.length;
+          if (downloadedBytes > MAX_TARBALL_SIZE) {
+            res.destroy();
+            fileStream.destroy();
+            try { fs.unlinkSync(destPath); } catch {}
+            reject(new Error(`Package too large: ${downloadedBytes}+ bytes (max ${MAX_TARBALL_SIZE})`));
+          }
+        });
+        res.pipe(fileStream);
+        fileStream.on('finish', () => resolve(downloadedBytes));
+        fileStream.on('error', (err) => {
+          try { fs.unlinkSync(destPath); } catch {}
+          reject(err);
+        });
+        res.on('error', (err) => {
+          fileStream.destroy();
+          try { fs.unlinkSync(destPath); } catch {}
+          reject(err);
+        });
+      });
+      req.on('error', reject);
+      req.on('timeout', () => {
+        req.destroy();
+        reject(new Error(`Timeout downloading ${requestUrl}`));
+      });
+    };
+    doRequest(url);
+  });
+}
+
+/**
+ * Extract a .tar.gz to a directory. Returns the package root.
+ * Uses execFileSync (no shell) to prevent command injection.
+ * @param {string} tgzPath - Path to the .tar.gz file
+ * @param {string} destDir - Destination directory
+ * @returns {string} Path to extracted package root
+ */
+function extractTarGz(tgzPath, destDir) {
+  // Use cwd + relative paths so C: never appears in tar arguments
+  // (GNU tar treats C: as remote host, bsdtar doesn't support --force-local)
+  const tgzDir = path.dirname(path.resolve(tgzPath));
+  const tgzName = path.basename(tgzPath);
+  const relDest = path.relative(tgzDir, path.resolve(destDir)) || '.';
+  execFileSync('tar', ['xzf', tgzName, '-C', relDest], { cwd: tgzDir, timeout: 60_000, stdio: 'pipe' });
+  // npm tarballs extract into a package/ subdirectory; detect it
+  const packageSubdir = path.join(destDir, 'package');
+  if (fs.existsSync(packageSubdir) && fs.statSync(packageSubdir).isDirectory()) {
+    return packageSubdir;
+  }
+  // Otherwise return destDir itself (PyPI sdists vary)
+  const entries = fs.readdirSync(destDir);
+  if (entries.length === 1) {
+    const single = path.join(destDir, entries[0]);
+    if (fs.statSync(single).isDirectory()) return single;
+  }
+  return destDir;
+}
+
+/**
+ * Sanitize a package name for use in temporary directory names.
+ * Removes path traversal sequences, slashes, and @ symbols.
+ * @param {string} packageName - Raw package name
+ * @returns {string} Safe string for directory names
+ */
+function sanitizePackageName(packageName) {
+  return packageName
+    .replace(/\.\./g, '')
+    .replace(/\//g, '_')
+    .replace(/@/g, '');
+}
+
+module.exports = {
+  downloadToFile,
+  extractTarGz,
+  sanitizePackageName,
+  isAllowedDownloadRedirect,
+  ALLOWED_DOWNLOAD_DOMAINS,
+  PRIVATE_IP_PATTERNS
+};

package/src/temporal-ast-diff.js

@@ -2,16 +2,14 @@ const https = require('https');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { execSync } = require('child_process');
 const acorn = require('acorn');
 const walk = require('acorn-walk');
 const { findJsFiles } = require('./utils.js');
 const { fetchPackageMetadata, getLatestVersions } = require('./temporal-analysis.js');
+const { downloadToFile, extractTarGz, sanitizePackageName } = require('./shared/download.js');
 
 const REGISTRY_URL = 'https://registry.npmjs.org';
-const MAX_TARBALL_SIZE = 50 * 1024 * 1024; // 50MB
 const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
-const DOWNLOAD_TIMEOUT = 30_000;
 const METADATA_TIMEOUT = 10_000;
 
 const SENSITIVE_PATHS = [
@@ -77,84 +75,6 @@ function fetchVersionMetadata(packageName, version) {
   });
 }
 
-/**
- * Download a file from HTTPS URL to disk.
- */
-function downloadToFile(url, destPath) {
-  return new Promise((resolve, reject) => {
-    const doRequest = (requestUrl) => {
-      const req = https.get(requestUrl, { timeout: DOWNLOAD_TIMEOUT }, (res) => {
-        if (res.statusCode === 301 || res.statusCode === 302) {
-          res.resume();
-          const location = res.headers.location;
-          if (!location) return reject(new Error(`Redirect without Location for ${requestUrl}`));
-          return doRequest(location);
-        }
-        if (res.statusCode < 200 || res.statusCode >= 300) {
-          res.resume();
-          return reject(new Error(`HTTP ${res.statusCode} for ${requestUrl}`));
-        }
-        const contentLength = parseInt(res.headers['content-length'], 10);
-        if (contentLength && contentLength > MAX_TARBALL_SIZE) {
-          res.resume();
-          return reject(new Error(`Tarball too large: ${contentLength} bytes`));
-        }
-        const fileStream = fs.createWriteStream(destPath);
-        let downloaded = 0;
-        res.on('data', chunk => {
-          downloaded += chunk.length;
-          if (downloaded > MAX_TARBALL_SIZE) {
-            res.destroy();
-            fileStream.destroy();
-            try { fs.unlinkSync(destPath); } catch {}
-            reject(new Error(`Tarball too large: ${downloaded}+ bytes`));
-          }
-        });
-        res.pipe(fileStream);
-        fileStream.on('finish', () => resolve(downloaded));
-        fileStream.on('error', err => {
-          try { fs.unlinkSync(destPath); } catch {}
-          reject(err);
-        });
-        res.on('error', err => {
-          fileStream.destroy();
-          try { fs.unlinkSync(destPath); } catch {}
-          reject(err);
-        });
-      });
-      req.on('error', reject);
-      req.on('timeout', () => {
-        req.destroy();
-        reject(new Error(`Download timeout for ${requestUrl}`));
-      });
-    };
-    doRequest(url);
-  });
-}
-
-/**
- * Extract a .tar.gz to a directory. Returns the package root.
- */
-function extractTarGz(tgzPath, destDir) {
-  // Use cwd + relative paths so C: never appears in tar arguments
-  // (GNU tar treats C: as remote host, bsdtar doesn't support --force-local)
-  const tgzDir = path.dirname(path.resolve(tgzPath));
-  const tgzName = path.basename(tgzPath);
-  const relDest = path.relative(tgzDir, path.resolve(destDir)) || '.';
-  execSync(`tar xzf "${tgzName}" -C "${relDest}"`, { cwd: tgzDir, timeout: 60_000, stdio: 'pipe' });
-  // npm tarballs extract into a package/ subdirectory
-  const packageSubdir = path.join(destDir, 'package');
-  if (fs.existsSync(packageSubdir) && fs.statSync(packageSubdir).isDirectory()) {
-    return packageSubdir;
-  }
-  const entries = fs.readdirSync(destDir);
-  if (entries.length === 1) {
-    const single = path.join(destDir, entries[0]);
-    if (fs.statSync(single).isDirectory()) return single;
-  }
-  return destDir;
-}
-
 // --- Core functions ---
 
 /**
@@ -170,7 +90,7 @@ async function fetchPackageTarball(packageName, version) {
     throw new Error(`No tarball URL found for ${packageName}@${version}`);
   }
 
-  const safeName = packageName.replace(/\//g, '_').replace(/@/g, '');
+  const safeName = sanitizePackageName(packageName);
   const tmpBase = path.join(os.tmpdir(), 'muaddib-ast-diff');
   if (!fs.existsSync(tmpBase)) fs.mkdirSync(tmpBase, { recursive: true });
   const tmpDir = fs.mkdtempSync(path.join(tmpBase, `${safeName}-${version}-`));