muaddib-scanner 2.1.0 → 2.1.2

package/README.fr.md

@@ -146,7 +146,7 @@ Détection ultra-stricte avec moins de tolérance. Utile pour les projets critiq
 muaddib scan . --webhook "https://discord.com/api/webhooks/..."
 ```
 
-Envoie une alerte avec le score et les menaces sur Discord ou Slack.
+Envoie une alerte avec le score et les menaces sur Discord ou Slack. Filtrage strict (v2.1.2) : les alertes ne sont envoyées que pour les correspondances IOC, les menaces confirmées par sandbox, ou l'exfiltration de canary tokens — réduisant le bruit des détections heuristiques seules.
 
 ### Surveillance temps réel
 
@@ -203,6 +203,8 @@ Monitoring multi-couches :
 - **Capture réseau** (tcpdump) : résolutions DNS avec IPs résolues, requêtes HTTP (méthode, host, path, body), détection TLS SNI
 - **Diff filesystem** : snapshot avant/après install, détecte les fichiers créés dans des emplacements suspects
 - **Détection exfiltration de données** : 16 patterns sensibles (tokens, credentials, clés SSH, clés privées, .env)
+- **Environnement CI simulé** (v2.1.2) : simule un environnement CI (GITHUB_ACTIONS, GITLAB_CI, TRAVIS, CIRCLECI, JENKINS) pour déclencher les malwares CI-aware qui resteraient autrement dormants
+- **Canary tokens enrichis** (v2.1.2) : 6 honeypots injectés comme variables d'environnement (GITHUB_TOKEN, NPM_TOKEN, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, SLACK_WEBHOOK_URL, DISCORD_WEBHOOK_URL). Si exfiltrés via réseau, DNS ou filesystem, déclenche une alerte CRITICAL avec score +50
 - **Moteur de scoring** : score de risque 0-100 basé sur la sévérité des comportements
 
 Utilisez `--strict` pour bloquer tout trafic réseau sortant non essentiel via iptables.
@@ -503,7 +505,14 @@ muaddib scan . --temporal-maintainer
 
 #### 5. Canary Tokens / Honey Tokens (sandbox)
 
-Injecte de faux credentials (GITHUB_TOKEN, NPM_TOKEN, clés AWS) dans l'environnement sandbox avant d'installer un package. Si le package tente d'exfiltrer ces honey tokens via HTTP, DNS ou stdout, il est signalé comme malveillant confirmé.
+Injecte de faux credentials dans l'environnement sandbox avant d'installer un package. Si le package tente d'exfiltrer ces honey tokens via HTTP, DNS, filesystem ou stdout, il est signalé comme malveillant confirmé.
+
+6 honeypots sont injectés :
+- `GITHUB_TOKEN` / `NPM_TOKEN` — Tokens de registre
+- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` — Credentials cloud
+- `SLACK_WEBHOOK_URL` / `DISCORD_WEBHOOK_URL` — Webhooks de messagerie
+
+Les tokens dynamiques (aléatoires par session, depuis `canary-tokens.js`) et les tokens statiques de fallback (dans `sandbox-runner.sh`) sont utilisés pour une défense en profondeur.
 
 ```bash
 muaddib sandbox suspicious-package
@@ -696,7 +705,7 @@ MUAD'DIB 2.1 Scanner
 |   +-- API Threat Feed (serveur HTTP, flux JSON pour SIEM)
 |
 +-- Paranoid Mode (ultra-strict)
-+-- Docker Sandbox (analyse comportementale, capture réseau, canary tokens)
++-- Docker Sandbox (analyse comportementale, capture réseau, canary tokens, CI-aware)
 +-- Moniteur Zero-Day (polling RSS npm + PyPI, alertes Discord, rapport quotidien)
 |
 v
@@ -741,7 +750,7 @@ npm test
 
 ### Tests
 
-- **709 tests unitaires/intégration** - 74% coverage via [Codecov](https://codecov.io/gh/DNSZLSK/muad-dib)
+- **742 tests unitaires/intégration** - 74% coverage via [Codecov](https://codecov.io/gh/DNSZLSK/muad-dib)
 - **56 tests de fuzzing** - YAML malformé, JSON invalide, fichiers binaires, ReDoS, unicode, inputs 10MB
 - **15 tests adversariaux** - Packages malveillants simulés, taux de détection 15/15
 - **8 tests multi-facteur typosquat** - Cas limites et comportement cache

package/README.md

@@ -146,7 +146,7 @@ Ultra-strict detection with lower tolerance. Useful for critical projects. Detec
 muaddib scan . --webhook "https://discord.com/api/webhooks/..."
 ```
 
-Sends an alert with score and threats to Discord or Slack.
+Sends an alert with score and threats to Discord or Slack. Strict filtering (v2.1.2): alerts are only sent for IOC matches, sandbox-confirmed threats, or canary token exfiltration — reducing noise from heuristic-only detections.
 
 ### Real-time monitoring
 
@@ -203,6 +203,8 @@ Multi-layer monitoring:
 - **Network capture** (tcpdump): DNS resolutions with resolved IPs, HTTP requests (method, host, path, body), TLS SNI detection
 - **Filesystem diff**: snapshot before/after install, detects files created in suspicious locations
 - **Data exfiltration detection**: 16 sensitive patterns (tokens, credentials, SSH keys, private keys, .env)
+- **CI-aware environment** (v2.1.2): simulates CI environments (GITHUB_ACTIONS, GITLAB_CI, TRAVIS, CIRCLECI, JENKINS) to trigger CI-aware malware that would otherwise stay dormant
+- **Enriched canary tokens** (v2.1.2): 6 honeypot credentials injected as env vars (GITHUB_TOKEN, NPM_TOKEN, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, SLACK_WEBHOOK_URL, DISCORD_WEBHOOK_URL). If exfiltrated via network, DNS, or filesystem, triggers CRITICAL alert with +50 score
 - **Scoring engine**: 0-100 risk score based on behavioral severity
 
 Use `--strict` to block all non-essential outbound network traffic via iptables.
@@ -504,7 +506,14 @@ muaddib scan . --temporal-maintainer
 
 #### 5. Canary Tokens / Honey Tokens (sandbox)
 
-Injects fake credentials (GITHUB_TOKEN, NPM_TOKEN, AWS keys) into the sandbox environment before installing a package. If the package attempts to exfiltrate these honey tokens via HTTP, DNS, or stdout, it's flagged as confirmed malicious.
+Injects fake credentials into the sandbox environment before installing a package. If the package attempts to exfiltrate these honey tokens via HTTP, DNS, filesystem, or stdout, it's flagged as confirmed malicious.
+
+6 honeypot credentials are injected:
+- `GITHUB_TOKEN` / `NPM_TOKEN` — Package registry tokens
+- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` — Cloud credentials
+- `SLACK_WEBHOOK_URL` / `DISCORD_WEBHOOK_URL` — Messaging webhooks
+
+Both dynamic tokens (random per session, from `canary-tokens.js`) and static fallback tokens (in `sandbox-runner.sh`) are used for defense in depth.
 
 ```bash
 muaddib sandbox suspicious-package
@@ -699,7 +708,7 @@ MUAD'DIB 2.1 Scanner
 |   +-- Threat Feed API (HTTP server, JSON feed for SIEM)
 |
 +-- Paranoid Mode (ultra-strict)
-+-- Docker Sandbox (behavioral analysis, network capture, canary tokens)
++-- Docker Sandbox (behavioral analysis, network capture, canary tokens, CI-aware)
 +-- Zero-Day Monitor (npm + PyPI RSS polling, Discord alerts, daily report)
 |
 v
@@ -744,7 +753,7 @@ npm test
 
 ### Testing
 
-- **709 unit/integration tests** - 74% code coverage via [Codecov](https://codecov.io/gh/DNSZLSK/muad-dib)
+- **742 unit/integration tests** - 74% code coverage via [Codecov](https://codecov.io/gh/DNSZLSK/muad-dib)
 - **56 fuzz tests** - Malformed YAML, invalid JSON, binary files, ReDoS, unicode, 10MB inputs
 - **15 adversarial tests** - Simulated malicious packages, 15/15 detection rate
 - **8 multi-factor typosquat tests** - Edge cases and cache behavior

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/docker/sandbox-runner.sh

@@ -44,6 +44,26 @@ tcpdump -i any -nn 'not port 53 and not port 80 and not port 443' -l > /tmp/othe
 OTHER_PID=$!
 sleep 1
 
+# ── 2b. CI environment simulation ──
+# Simulate CI to trigger CI-aware malware that checks for these env vars
+echo "[SANDBOX] Simulating CI environment..." >&2
+export CI=true
+export GITHUB_ACTIONS=true
+export GITLAB_CI=true
+export TRAVIS=true
+export CIRCLECI=true
+export JENKINS_URL=http://localhost:8080
+
+# ── 2c. Canary tokens (honeypots) ──
+# Use Docker-injected dynamic tokens if available, otherwise static fallbacks.
+# If exfiltrated via network/DNS/files, sandbox.js detects the theft.
+export GITHUB_TOKEN="${GITHUB_TOKEN:-MUADDIB_CANARY_GITHUB_f8k3t0k3n}"
+export NPM_TOKEN="${NPM_TOKEN:-MUADDIB_CANARY_NPM_s3cr3tt0k3n}"
+export AWS_ACCESS_KEY_ID="${AWS_ACCESS_KEY_ID:-MUADDIB_CANARY_AKIAIOSFODNN7EXAMPLE}"
+export AWS_SECRET_ACCESS_KEY="${AWS_SECRET_ACCESS_KEY:-MUADDIB_CANARY_wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY}"
+export SLACK_WEBHOOK_URL="${SLACK_WEBHOOK_URL:-https://hooks.slack.com/MUADDIB_CANARY_SLACK}"
+export DISCORD_WEBHOOK_URL="${DISCORD_WEBHOOK_URL:-https://discord.com/api/webhooks/MUADDIB_CANARY_DISCORD}"
+
 # ── 3. npm install with strace ──
 echo "[SANDBOX] Installing $PACKAGE..." >&2
 cd /sandbox/install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muaddib-scanner",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "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 = [
@@ -34,6 +35,18 @@ const PROBE_PORTS = [65535]; // Node.js internal connectivity checks
 // Commands that are always suspicious in a sandbox
 const DANGEROUS_CMDS = ['curl', 'wget', 'nc', 'netcat', 'python', 'python3', 'bash', 'sh'];
 
+// Static canary tokens injected by sandbox-runner.sh (fallback honeypots).
+// These are searched in the sandbox report as a complement to the dynamic
+// tokens from canary-tokens.js (which use random suffixes per session).
+const STATIC_CANARY_TOKENS = {
+  GITHUB_TOKEN: 'MUADDIB_CANARY_GITHUB_f8k3t0k3n',
+  NPM_TOKEN: 'MUADDIB_CANARY_NPM_s3cr3tt0k3n',
+  AWS_ACCESS_KEY_ID: 'MUADDIB_CANARY_AKIAIOSFODNN7EXAMPLE',
+  AWS_SECRET_ACCESS_KEY: 'MUADDIB_CANARY_wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+  SLACK_WEBHOOK_URL: 'MUADDIB_CANARY_SLACK',
+  DISCORD_WEBHOOK_URL: 'MUADDIB_CANARY_DISCORD'
+};
+
 // Patterns indicating data exfiltration in HTTP bodies
 const EXFIL_PATTERNS = [
   { pattern: /\bNPM_TOKEN\b/i, label: 'npm token', severity: 'CRITICAL' },
@@ -246,7 +259,7 @@ async function runSandbox(packageName, options = {}) {
 
       const { score, findings } = scoreFindings(report);
 
-      // Canary token exfiltration detection
+      // Canary token exfiltration detection (dynamic tokens)
       if (canaryTokens) {
         const networkExfil = detectCanaryExfiltration(report.network || {}, canaryTokens);
         const outputExfil = detectCanaryInOutput(stdout, stderr, canaryTokens);
@@ -261,6 +274,22 @@ async function runSandbox(packageName, options = {}) {
         }
       }
 
+      // Static canary token detection (fallback for shell-injected tokens)
+      const staticExfil = detectStaticCanaryExfiltration(report);
+      for (const { token, value } of staticExfil) {
+        const alreadyDetected = findings.some(f =>
+          f.type === 'canary_exfiltration' && f.detail && f.detail.includes(token)
+        );
+        if (!alreadyDetected) {
+          findings.push({
+            type: 'canary_exfiltration',
+            severity: 'CRITICAL',
+            detail: `Canary token exfiltration detected: ${token}`,
+            evidence: value
+          });
+        }
+      }
+
       const finalScore = Math.min(100, findings.reduce((s, f) => {
         if (f.type === 'canary_exfiltration') return s + 50;
         return s;
@@ -284,6 +313,47 @@ async function runSandbox(packageName, options = {}) {
   });
 }
 
+// ── Static canary detection ──
+
+/**
+ * Detect static canary token exfiltration in a sandbox report.
+ * Searches HTTP bodies, DNS queries, HTTP request URLs, TLS domains,
+ * filesystem changes, process commands, and install output.
+ * @param {object} report - Parsed sandbox report JSON
+ * @returns {Array<{token: string, value: string}>} Exfiltrated tokens
+ */
+function detectStaticCanaryExfiltration(report) {
+  const exfiltrated = [];
+  if (!report) return exfiltrated;
+
+  const searchable = [];
+
+  // Network data
+  for (const body of (report.network?.http_bodies || [])) if (body) searchable.push(body);
+  for (const domain of (report.network?.dns_queries || [])) if (domain) searchable.push(domain);
+  for (const req of (report.network?.http_requests || [])) {
+    searchable.push(`${req.method || ''} ${req.host || ''}${req.path || ''}`);
+  }
+  for (const tls of (report.network?.tls_connections || [])) if (tls.domain) searchable.push(tls.domain);
+
+  // Filesystem + processes
+  for (const file of (report.filesystem?.created || [])) if (file) searchable.push(file);
+  for (const proc of (report.processes?.spawned || [])) if (proc.command) searchable.push(proc.command);
+
+  // Install output
+  if (report.install_output) searchable.push(report.install_output);
+
+  const allOutput = searchable.join('\n');
+
+  for (const [tokenName, tokenValue] of Object.entries(STATIC_CANARY_TOKENS)) {
+    if (allOutput.includes(tokenValue)) {
+      exfiltrated.push({ token: tokenName, value: tokenValue });
+    }
+  }
+
+  return exfiltrated;
+}
+
 // ── Scoring engine ──
 
 function scoreFindings(report) {
@@ -547,4 +617,4 @@ function displayResults(result) {
   }
 }
 
-module.exports = { buildSandboxImage, runSandbox, scoreFindings, generateNetworkReport, EXFIL_PATTERNS, SAFE_DOMAINS, getSeverity, displayResults, isDockerAvailable, imageExists };
+module.exports = { buildSandboxImage, runSandbox, scoreFindings, generateNetworkReport, EXFIL_PATTERNS, SAFE_DOMAINS, getSeverity, displayResults, isDockerAvailable, imageExists, STATIC_CANARY_TOKENS, detectStaticCanaryExfiltration };

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}-`));