muaddib-scanner 2.11.4 → 2.11.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muaddib-scanner",
-  "version": "2.11.4",
+  "version": "2.11.6",
   "description": "Supply-chain threat detection & response for npm & PyPI/Python",
   "main": "src/index.js",
   "bin": {
@@ -9,6 +9,8 @@
   "scripts": {
     "test": "node tests/run-tests.js",
     "test:integration": "node tests/run-tests-integration.js",
+    "test:regression-check": "node scripts/regression-check.js",
+    "fp-clusters": "node scripts/analyze-fp-clusters.js",
     "scan": "node bin/muaddib.js scan .",
     "update": "node bin/muaddib.js update",
     "lint": "eslint src bin --ext .js",

package/src/integrations/registry-signals.js

@@ -0,0 +1,216 @@
+/**
+ * Advanced npm registry signals for the FPR plan, Chantier 4.
+ *
+ * Computes four categorical signals on top of the basic metadata bundle :
+ *
+ *   - maintainer_change_recent   : a maintainer was added or replaced in the
+ *                                  last 30 days (boost ; matches Shai-Hulud /
+ *                                  Axios 2026 takeover patterns).
+ *   - maintainer_change_within_days : days since the last maintainer change,
+ *                                     or null if not detected.
+ *   - publish_cadence_anomaly    : the latest inter-publish gap is more than
+ *                                  3 sigma off the historical cadence (boost).
+ *   - stable_ownership_2y        : the latest maintainer set has been the same
+ *                                  for at least 2 years and the package has
+ *                                  > 100 versions (suppression douce).
+ *
+ * These are intended to be consumed by `_factorFromMetadata` in src/scoring.js.
+ * The first three are *boosts* (used as a safety net so suppressions in
+ * Chantier 5 do not mask a recent account takeover). The fourth is the only
+ * structural suppression and only fires on packages with substantial publish
+ * history.
+ *
+ * Pure functions on the npm registry packument shape ; no network IO. Caller
+ * passes the same `meta` object as `npm-registry.getPackageMetadata` already
+ * fetches, so we never double-fetch.
+ */
+
+'use strict';
+
+const MILLIS_PER_DAY = 24 * 60 * 60 * 1000;
+const RECENT_CHANGE_DAYS = 30;
+const STABLE_OWNERSHIP_DAYS = 2 * 365;
+const STABLE_OWNERSHIP_MIN_VERSIONS = 100;
+const CADENCE_MIN_VERSIONS = 6;
+const CADENCE_SIGMA = 3;
+
+function _daysBetween(a, b) {
+  if (!(a instanceof Date) || !(b instanceof Date)) return null;
+  return Math.floor((a.getTime() - b.getTime()) / MILLIS_PER_DAY);
+}
+
+function _toDate(value) {
+  if (!value) return null;
+  const d = new Date(value);
+  return isNaN(d.getTime()) ? null : d;
+}
+
+/**
+ * Extract maintainer names for a version object.
+ * Returns a sorted lowercased array (set semantics) so two versions with the
+ * same maintainers compared equal regardless of declaration order.
+ */
+function _maintainersFor(versionData) {
+  if (!versionData) return [];
+  const list = Array.isArray(versionData.maintainers) ? versionData.maintainers : [];
+  const names = list
+    .map(m => (m && typeof m.name === 'string') ? m.name.toLowerCase().trim() : null)
+    .filter(Boolean);
+  names.sort();
+  return names;
+}
+
+function _equalMaintainerSets(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Order all version entries by publish time descending.
+ * Returns array of { version, time: Date, maintainers: string[] }.
+ */
+function _orderedVersions(meta) {
+  if (!meta || !meta.versions || !meta.time) return [];
+  const out = [];
+  for (const [version, versionData] of Object.entries(meta.versions)) {
+    const t = _toDate(meta.time[version]);
+    if (!t) continue;
+    out.push({ version, time: t, maintainers: _maintainersFor(versionData) });
+  }
+  out.sort((a, b) => b.time.getTime() - a.time.getTime());
+  return out;
+}
+
+/**
+ * Detects whether a maintainer set changed (added or removed names) within
+ * `windowDays` of the latest publish.
+ *
+ * Returns { changed, daysSinceChange } - daysSinceChange is null when no
+ * change is detected within the window or when there is insufficient history.
+ */
+function detectRecentMaintainerChange(meta, windowDays = RECENT_CHANGE_DAYS) {
+  const ordered = _orderedVersions(meta);
+  if (ordered.length < 2) return { changed: false, daysSinceChange: null };
+
+  const latest = ordered[0];
+  if (latest.maintainers.length === 0) return { changed: false, daysSinceChange: null };
+
+  for (let i = 1; i < ordered.length; i++) {
+    const prev = ordered[i];
+    const days = _daysBetween(latest.time, prev.time);
+    if (days === null) continue;
+    if (days > windowDays) {
+      // No change within the window
+      return { changed: false, daysSinceChange: null };
+    }
+    if (!_equalMaintainerSets(latest.maintainers, prev.maintainers)) {
+      return { changed: true, daysSinceChange: days };
+    }
+  }
+  // All within-window versions had identical maintainers
+  return { changed: false, daysSinceChange: null };
+}
+
+/**
+ * Detects whether the publish cadence has changed dramatically. Computes the
+ * mean and stddev of historical inter-publish gaps (in days), then flags an
+ * anomaly when the latest gap is more than `sigma` standard deviations from
+ * the mean.
+ *
+ * Returns { anomaly, latestGapDays, meanGapDays, sigmaCount }.
+ * Insufficient history (< CADENCE_MIN_VERSIONS) -> anomaly=false.
+ */
+function detectPublishCadenceAnomaly(meta, sigma = CADENCE_SIGMA) {
+  const ordered = _orderedVersions(meta);
+  if (ordered.length < CADENCE_MIN_VERSIONS) {
+    return { anomaly: false, latestGapDays: null, meanGapDays: null, sigmaCount: null };
+  }
+
+  const gaps = [];
+  for (let i = 0; i < ordered.length - 1; i++) {
+    const days = _daysBetween(ordered[i].time, ordered[i + 1].time);
+    if (days !== null && days >= 0) gaps.push(days);
+  }
+  if (gaps.length < CADENCE_MIN_VERSIONS - 1) {
+    return { anomaly: false, latestGapDays: null, meanGapDays: null, sigmaCount: null };
+  }
+
+  const latestGap = gaps[0];
+  const historical = gaps.slice(1); // exclude latest from the baseline
+  const mean = historical.reduce((s, x) => s + x, 0) / historical.length;
+  const variance = historical.reduce((s, x) => s + (x - mean) * (x - mean), 0) / historical.length;
+  const stddev = Math.sqrt(variance);
+  if (stddev === 0) {
+    return { anomaly: false, latestGapDays: latestGap, meanGapDays: mean, sigmaCount: 0 };
+  }
+  const sigmaCount = Math.abs(latestGap - mean) / stddev;
+  return {
+    anomaly: sigmaCount > sigma,
+    latestGapDays: latestGap,
+    meanGapDays: mean,
+    sigmaCount
+  };
+}
+
+/**
+ * Detects whether the package has stable ownership for >= 2 years and > 100
+ * versions. This is the only structural suppression introduced in Chantier 4 -
+ * paired with C5's mature stable cap, it lets us cap mature, well-owned
+ * packages at MEDIUM while still surfacing maintainer change boosts above.
+ */
+function detectStableOwnership(meta, minDays = STABLE_OWNERSHIP_DAYS, minVersions = STABLE_OWNERSHIP_MIN_VERSIONS) {
+  const ordered = _orderedVersions(meta);
+  if (ordered.length < minVersions) return { stable: false, sinceDays: null };
+
+  const latest = ordered[0];
+  if (latest.maintainers.length === 0) return { stable: false, sinceDays: null };
+
+  // Walk backwards until we find a version whose maintainer set differs
+  // OR we exhaust history. Stable if the same set persists for >= minDays.
+  let oldestSameSet = latest;
+  for (let i = 1; i < ordered.length; i++) {
+    if (_equalMaintainerSets(latest.maintainers, ordered[i].maintainers)) {
+      oldestSameSet = ordered[i];
+      continue;
+    }
+    break;
+  }
+  const sinceDays = _daysBetween(latest.time, oldestSameSet.time);
+  return {
+    stable: sinceDays !== null && sinceDays >= minDays,
+    sinceDays
+  };
+}
+
+/**
+ * Computes the four advanced signals from a registry packument and returns
+ * a flat object suitable for merging into the basic metadata bundle.
+ */
+function computeAdvancedRegistrySignals(meta) {
+  const change = detectRecentMaintainerChange(meta);
+  const cadence = detectPublishCadenceAnomaly(meta);
+  const stable = detectStableOwnership(meta);
+  return {
+    maintainer_change_recent: change.changed,
+    maintainer_change_within_days: change.daysSinceChange,
+    publish_cadence_anomaly: cadence.anomaly,
+    publish_cadence_sigma: cadence.sigmaCount,
+    stable_ownership_2y: stable.stable,
+    stable_ownership_since_days: stable.sinceDays
+  };
+}
+
+module.exports = {
+  computeAdvancedRegistrySignals,
+  detectRecentMaintainerChange,
+  detectPublishCadenceAnomaly,
+  detectStableOwnership,
+  RECENT_CHANGE_DAYS,
+  STABLE_OWNERSHIP_DAYS,
+  STABLE_OWNERSHIP_MIN_VERSIONS,
+  CADENCE_MIN_VERSIONS,
+  CADENCE_SIGMA
+};

package/src/pipeline/processor.js

@@ -2,10 +2,29 @@ const fs = require('fs');
 const path = require('path');
 const { getRule } = require('../rules/index.js');
 const { getPlaybook } = require('../response/playbooks.js');
-const { computeReachableFiles } = require('../scanner/reachability.js');
-const { applyFPReductions, applyCompoundBoosts, calculateRiskScore, getSeverityWeights, applyContextualFPCaps, applySingleFireCriticalFloor, applyReputationFactor } = require('../scoring.js');
+const { computeReachableFiles, computeReachableFunctions } = require('../scanner/reachability.js');
+const { applyFPReductions, applyCompoundBoosts, calculateRiskScore, getSeverityWeights, applyContextualFPCaps, applySingleFireCriticalFloor, applyReputationFactor, applyMatureStableCap, applySandboxVerdict, applyDeltaMultiplier } = require('../scoring.js');
+const { loadPriorVersionSignatures, computeSignatures, saveCachedSignatures } = require('../scoring/delta-multiplier.js');
+const { annotateConfidenceTiers, tierAtLeast } = require('../rules/confidence-tiers.js');
 const { buildIntentPairs } = require('../intent-graph.js');
 const { debugLog } = require('../utils.js');
+const { getPackageMetadata } = require('../scanner/npm-registry.js');
+
+// Auto-sandbox compound trigger : optional out-of-tree dependency. Lazy-load
+// it so the pipeline still works when the file is absent (some dev machines
+// have it untracked, CI does not). When missing, evaluateSandboxTrigger
+// degrades to a no-op {shouldRun:false} so the auto-sandbox branch skips.
+let _sandboxTriggerCache = null;
+function evaluateSandboxTrigger(threats, prelimScore) {
+  if (_sandboxTriggerCache === null) {
+    try {
+      _sandboxTriggerCache = require('../sandbox/compound-triggers.js').evaluateSandboxTrigger;
+    } catch {
+      _sandboxTriggerCache = () => ({ shouldRun: false });
+    }
+  }
+  return _sandboxTriggerCache(threats, prelimScore);
+}
 
 /**
  * Process raw threats: sandbox integration, dedup, compounds, FP reductions,
@@ -18,32 +37,48 @@ const { debugLog } = require('../utils.js');
  * @returns {Promise<{result: object, deduped: Array, enrichedThreats: Array, sandboxData: object|null, pythonInfo: object|null, breakdown: Array, mostSuspiciousFile: string|null, maxFileScore: number, packageScore: number, globalRiskScore: number, scannerErrors: Array}>}
  */
 async function process(threats, targetPath, options, pythonDeps, warnings, scannerErrors) {
-  // Auto-sandbox: trigger sandbox analysis when static scan detects threats.
-  // Preliminary score estimate: count CRITICAL/HIGH threats as a quick heuristic.
-  // Only when --auto-sandbox flag is set, no explicit sandboxResult, and Docker available.
+  // Auto-sandbox: surgical trigger only when a sandbox-friendly compound
+  // matches AND the preliminary score is in the borderline window [15, 35].
+  // See src/sandbox/compound-triggers.js for the 6 compounds and rationale.
+  // Score < 15 = clean, no need to run; score > 35 = already definitive,
+  // no second-tier verdict needed. The verdict is then applied below via
+  // applySandboxVerdict (floor at 75/60 for malicious, -8 for clean).
   if (options.autoSandbox && !options.sandboxResult) {
     const critCount = threats.filter(t => t.severity === 'CRITICAL').length;
     const highCount = threats.filter(t => t.severity === 'HIGH').length;
     const prelimScore = Math.min(100, critCount * 25 + highCount * 10);
-    if (prelimScore >= 20) {
+    const sandboxTrigger = evaluateSandboxTrigger(threats, prelimScore);
+    if (sandboxTrigger.shouldRun) {
       try {
         const { isDockerAvailable, buildSandboxImage, runSandbox } = require('../sandbox/index.js');
         if (isDockerAvailable()) {
-          console.log(`\n[AUTO-SANDBOX] Preliminary score ~${prelimScore} >= 20 — triggering sandbox analysis...`);
+          console.log(`\n[AUTO-SANDBOX] Compound "${sandboxTrigger.compound}" matched (score ~${prelimScore}) - triggering sandbox analysis...`);
           const built = await buildSandboxImage();
           if (built) {
-            const sbResult = await runSandbox(targetPath, { local: true, strict: false });
+            const sbResult = await runSandbox(targetPath, {
+              local: true,
+              strict: false,
+              compound: sandboxTrigger.compound,
+              watchpoints: sandboxTrigger.watchpoints
+            });
             if (sbResult && Array.isArray(sbResult.findings)) {
+              if (sbResult.meta) {
+                sbResult.meta.compound = sandboxTrigger.compound;
+                sbResult.meta.watchpoints = sandboxTrigger.watchpoints;
+              } else {
+                sbResult.meta = { compound: sandboxTrigger.compound, watchpoints: sandboxTrigger.watchpoints };
+              }
               options.sandboxResult = sbResult;
             }
           }
         } else {
-          debugLog('[AUTO-SANDBOX] Docker not available — skipping sandbox');
+          debugLog('[AUTO-SANDBOX] Docker not available - skipping sandbox');
         }
       } catch (e) {
         debugLog('[AUTO-SANDBOX] Error:', e && e.message);
-        // Graceful fallback — sandbox is best-effort
       }
+    } else {
+      debugLog('[AUTO-SANDBOX] No compound matched (score ~' + prelimScore + ') - ' + sandboxTrigger.reason);
     }
   }
 
@@ -85,6 +120,7 @@ async function process(threats, targetPath, options, pythonDeps, warnings, scann
 
   // Reachability analysis: determine which files are reachable from entry points
   let reachableFiles = null;
+  let reachableFunctions = null; // FPR plan C2 : intra-file fn-level reachability
   if (!options.noReachability) {
     try {
       const reachability = computeReachableFiles(targetPath);
@@ -95,11 +131,24 @@ async function process(threats, targetPath, options, pythonDeps, warnings, scann
       debugLog('[REACHABILITY] error:', e?.message);
       // Graceful fallback — treat all files as reachable
     }
+    // FPR plan C2 : function-level reachability sits behind a flag while we
+    // measure FPR delta on the corpus. Off by default so production scans stay
+    // identical until the flag is flipped. Activated only when file-level
+    // reachability succeeded (otherwise no entry-point context to seed from).
+    if (reachableFiles && globalThis.process.env.MUADDIB_FN_REACHABILITY === '1') {
+      try {
+        reachableFunctions = computeReachableFunctions(targetPath, reachableFiles);
+      } catch (e) {
+        debugLog('[FN-REACHABILITY] error:', e?.message);
+        reachableFunctions = null;
+      }
+    }
   }
 
   // Read package name and dependencies for FP reduction heuristics
   let packageName = null;
   let packageDeps = null;
+  let packageVersion = null;
   let _pkgMeta = null; // v2.10.97: full pkg metadata for contextual FP caps
   try {
     const pkgPath = path.join(targetPath, 'package.json');
@@ -107,8 +156,10 @@ async function process(threats, targetPath, options, pythonDeps, warnings, scann
       const pkgData = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
       packageName = pkgData.name || null;
       packageDeps = pkgData.dependencies || null;
+      packageVersion = (typeof pkgData.version === 'string') ? pkgData.version : null;
       _pkgMeta = {
         name: pkgData.name,
+        version: packageVersion,
         scripts: pkgData.scripts || {},
         description: pkgData.description || '',
         homepage: pkgData.homepage || (typeof pkgData.repository === 'string' ? pkgData.repository : (pkgData.repository && pkgData.repository.url) || ''),
@@ -118,6 +169,39 @@ async function process(threats, targetPath, options, pythonDeps, warnings, scann
     }
   } catch { /* graceful fallback */ }
 
+  // FPR plan Chantier 4 + 5 wiring : when a package name is known and at least
+  // one of the metadata-driven gates is ON, fetch the npm registry packument
+  // and attach it as _pkgMeta.npmRegistryMeta. Without this, applyReputation-
+  // Factor and applyMatureStableCap cannot fire outside the monitor's own
+  // queue.js (which already pre-fetches the metadata bundle). getPackageMeta-
+  // data has its own in-process cache, so repeated scans of the same package
+  // hit the cache and never re-fetch. Network failure / unknown package -> the
+  // call returns null and both downstream functions degrade gracefully.
+  if (
+    packageName &&
+    _pkgMeta &&
+    (
+      globalThis.process.env.MUADDIB_METADATA_FACTOR === '1' ||
+      globalThis.process.env.MUADDIB_MATURE_CAP === '1' ||
+      globalThis.process.env.MUADDIB_DELTA_MODE === '1'
+    )
+  ) {
+    try {
+      const meta = await getPackageMetadata(packageName);
+      if (meta) {
+        // Attach the scanned version so applyMatureStableCap can require
+        // scan_version === latest_version. Without this gate, scanning a
+        // historical compromised version (e.g. eslint-scope 3.7.2, chalk
+        // 5.6.1) would inherit the live registry's "stable" reputation and
+        // mask the attack.
+        meta.scan_version = packageVersion;
+        _pkgMeta.npmRegistryMeta = meta;
+      }
+    } catch (err) {
+      debugLog('[REGISTRY-META] fetch failed for ' + packageName + ': ' + err.message);
+    }
+  }
+
   // Cross-scanner compound: detached_process + suspicious_dataflow in same file
   // Catches cases where credential flow is detected by dataflow scanner, not AST scanner
   {
@@ -206,11 +290,30 @@ async function process(threats, targetPath, options, pythonDeps, warnings, scann
 
   // FP reduction: legitimate frameworks produce high volumes of certain threat types.
   // A malware package typically has 1-3 occurrences, not dozens.
-  applyFPReductions(deduped, reachableFiles, packageName, packageDeps);
+  applyFPReductions(deduped, reachableFiles, packageName, packageDeps, reachableFunctions);
+
+  // FPR plan Chantier 3 - delta-aware decay. Threats present in the last 3
+  // published versions (and not HC/IOC) decay to LOW. Off by default until
+  // the cache is warm and we've measured the FPR delta on the corpus.
+  let _deltaResult = null;
+  if (
+    packageName && packageVersion &&
+    _pkgMeta && _pkgMeta.npmRegistryMeta &&
+    globalThis.process.env.MUADDIB_DELTA_MODE === '1'
+  ) {
+    try {
+      const packument = _pkgMeta.npmRegistryMeta.packument || _pkgMeta.npmRegistryMeta;
+      const priorSigs = loadPriorVersionSignatures(packageName, packageVersion, packument);
+      _deltaResult = applyDeltaMultiplier(deduped, priorSigs);
+    } catch (e) {
+      debugLog('[DELTA] error:', e?.message);
+      _deltaResult = null;
+    }
+  }
 
   // Compound scoring: inject synthetic CRITICAL threats when co-occurring types
   // indicate unambiguous malice. Applied AFTER FP reductions to recover signals
-  // that were individually downgraded (count-based, dist, reachability).
+  // that were individually downgraded (count-based, dist, reachability, delta).
   applyCompoundBoosts(deduped);
 
   // Intent coherence analysis: detect source→sink pairs within files
@@ -231,6 +334,13 @@ async function process(threats, targetPath, options, pythonDeps, warnings, scann
     }
   }
 
+  // FPR plan Chantier 6 - tag every threat with its confidence tier so the
+  // CLI / JSON / SARIF formatters can filter to verified+high by default and
+  // evaluate.js can report a "FPR perceived" headline alongside "FPR all".
+  // Annotation reads severity AFTER all FP reductions, so reductions trail
+  // (count_threshold, unreachable, delta_stable, ...) influences the tier.
+  annotateConfidenceTiers(deduped);
+
   // Enrich each threat with rules
   const enrichedThreats = deduped.map(t => {
     const rule = getRule(t.type);
@@ -241,6 +351,7 @@ async function process(threats, targetPath, options, pythonDeps, warnings, scann
       rule_id: rule.id || t.type,
       rule_name: rule.name || t.type,
       confidence: rule.confidence || 'medium',
+      confidenceTier: t.confidenceTier || 'medium',
       references: rule.references || [],
       mitre: t.mitre || rule.mitre,
       playbook: getPlaybook(t.type),
@@ -284,6 +395,16 @@ async function process(threats, targetPath, options, pythonDeps, warnings, scann
     threats: threats.filter(t => t.type === 'pypi_malicious_package' || t.type === 'pypi_typosquat_detected').length
   } : null;
 
+  // FPR plan Chantier 6 - tier counts let downstream metrics report FPR
+  // perceived (verified + high) alongside FPR all. The CLI reads these to
+  // decide whether to print a finding by default vs hide behind --show-low.
+  const tierCounts = { verified: 0, high: 0, medium: 0, low: 0 };
+  for (const t of deduped) {
+    const tier = t.confidenceTier || 'medium';
+    if (tierCounts[tier] !== undefined) tierCounts[tier]++;
+  }
+  const perceivedFlagged = tierCounts.verified + tierCounts.high;
+
   const result = {
     target: targetPath,
     timestamp: new Date().toISOString(),
@@ -303,7 +424,10 @@ async function process(threats, targetPath, options, pythonDeps, warnings, scann
       mostSuspiciousFile,
       fileScores,
       fileSizes,
-      breakdown
+      breakdown,
+      // C6 : confidence tier rollup
+      tierCounts,
+      perceivedFlagged
     },
     sandbox: sandboxData,
     warnings: warnings.length > 0 ? warnings : undefined,
@@ -319,6 +443,20 @@ async function process(threats, targetPath, options, pythonDeps, warnings, scann
       ' → score=' + result.summary.riskScore);
   }
 
+  // FPR plan Chantier 5 : mature stable cap — caps mature, well-owned, high-
+  // traffic packages at MEDIUM unless an HC type or IOC is present. Sits
+  // BETWEEN the contextual caps (which it composes with) and the single-fire
+  // floor (which can override on hard signals). Gated behind
+  // MUADDIB_MATURE_CAP=1 until measured against the full evaluation corpus.
+  if (globalThis.process.env.MUADDIB_MATURE_CAP === '1') {
+    const matureCap = applyMatureStableCap(result, _pkgMeta && _pkgMeta.npmRegistryMeta);
+    if (matureCap && matureCap.applied) {
+      debugLog('[MATURE-CAP] ' + (packageName || targetPath) + ': ' +
+        matureCap.oldScore + ' -> ' + matureCap.newScore + ' (' +
+        Object.entries(matureCap.reasons).map(([k, v]) => k + '=' + v).join(', ') + ')');
+    }
+  }
+
   // Hybrid v3 Phase 1: single-fire critical floor — applied AFTER contextual
   // caps so a deterministic IOC match (known_malicious_hash, lifecycle_shell_pipe…)
   // stays CRITICAL even if the package also matches a benign FP cluster.
@@ -345,6 +483,45 @@ async function process(threats, targetPath, options, pythonDeps, warnings, scann
     }
   }
 
+  // Sandbox verdict: meta-layer applied after every other scoring step.
+  // MALICIOUS_CONFIRMED floors the score at 75 (any honey READ correlated
+  // outbound, or critical preload signal). MALICIOUS_CHAIN floors at 60
+  // (>=2 high preload signals). CLEAN_HIGH_CONFIDENCE applies a -8 delta when
+  // the sandbox completed cleanly with no fingerprint detected. INCONCLUSIVE
+  // leaves the score unchanged with a warning attached.
+  if (options.sandboxResult) {
+    const verdict = applySandboxVerdict(result, options.sandboxResult);
+    if (verdict) {
+      debugLog('[SANDBOX-VERDICT] ' + (packageName || targetPath) + ': ' +
+        verdict.verdict + ' ' + verdict.oldScore + ' -> ' + verdict.newScore +
+        (verdict.signals.length > 0 ? ' [' + verdict.signals.slice(0, 3).join(', ') + ']' : ''));
+    }
+  }
+
+  // FPR plan Chantier 3 : persist this version's signature set so future scans
+  // (or future versions) can use it as a baseline for delta decay. Best-effort
+  // and idempotent ; cache misses on read are silent so a missed write never
+  // blocks scoring. Only write when the user opted in to delta-mode AND we
+  // have a concrete package@version pair.
+  if (
+    globalThis.process.env.MUADDIB_DELTA_MODE === '1' &&
+    packageName && packageVersion
+  ) {
+    try {
+      const sigs = computeSignatures(deduped);
+      saveCachedSignatures(packageName, packageVersion, sigs);
+      debugLog('[DELTA] cached ' + sigs.size + ' signatures for ' + packageName + '@' + packageVersion);
+    } catch (e) {
+      debugLog('[DELTA] cache write failed:', e?.message);
+    }
+  }
+
+  if (_deltaResult && _deltaResult.downgraded > 0) {
+    debugLog('[DELTA] ' + (packageName || targetPath) + ': ' +
+      _deltaResult.downgraded + ' threats decayed to LOW (baseline=' +
+      _deltaResult.baselineSize + ', new=' + _deltaResult.newThreats + ')');
+  }
+
   return {
     result,
     deduped,

package/src/response/playbooks.js

@@ -917,6 +917,37 @@ const PLAYBOOKS = {
     'CRITIQUE: Dependance declaree avec URL tarball (.tgz/.tar.gz) hebergee hors des registres npm legitimes (github.com, gitlab.com, bitbucket.org, registry.npmjs.org). ' +
     'Pattern ltidi chain attack (avril 2026): le stub publie sur npm n\'a aucun install hook visible, la charge utile est hebergee sur un cloud storage (GCS, S3, CDN) et contourne entierement l\'audit du registre npm. ' +
     'Verifier le contenu de la tarball distante avant toute installation. Supprimer le package. Signaler au registre npm.',
+
+  // Sandbox 2026: honey traps + persistence + chain analysis
+  sandbox_honey_read:
+    'CRITIQUE: Le package a lu un fichier decoy plante par la sandbox (.npmrc-decoy, .ssh/id_rsa-decoy, wallet decoy, etc.). ' +
+    'Aucun outil legitime ne lit ces chemins decoy. Indicateur fort de scan aveugle de credentials, meme pour des malwares zero-day. ' +
+    'Isoler la machine. Supprimer le package. Si un decoy a ete exfiltre via HTTP, le canary token apparaitra dans les logs reseau.',
+
+  sandbox_credential_target_read:
+    'ELEVE: Le package a lu un fichier de credentials connu (cloud creds, wallets, browser data, .gnupg, .kube/config). ' +
+    'Pattern PhantomRaven, Shai-Hulud. Verifier la correlation avec une connexion sortante non-registre dans la meme run. ' +
+    'Si le decoy a ete exfiltre (canary detection): rotation immediate de tous les secrets correspondants.',
+
+  sandbox_persistence_write:
+    'CRITIQUE: Le package a ecrit dans un emplacement de persistance (.bashrc, .zshrc, autostart, cron, systemd user, LaunchAgents). ' +
+    'Aucun cas legitime en npm install. Implant probable. ' +
+    'Inspecter le contenu ecrit, le supprimer, isoler la machine, regenerer la session shell.',
+
+  sandbox_execve_chain_depth:
+    'ELEVE: La chaine de processus depasse la profondeur attendue depuis npm install (npm install -> script -> binaire externe). ' +
+    'Pattern Shai-Hulud preinstall worm: install script lance node/sh qui lance curl|wget|bash. ' +
+    'Tracer chaque processus de la chaine, supprimer le package, verifier les fichiers crees dans /tmp et le home.',
+
+  sandbox_npm_self_invoke:
+    'CRITIQUE: Le package invoque npm publish/deprecate/owner/token/access depuis l\'arborescence npm install. ' +
+    'Pattern CanisterWorm self-propagation: le malware utilise le token npm de la machine pour publier des versions backdoorees d\'autres packages mainteneurs par l\'utilisateur. ' +
+    'Isoler immediatement. Revoquer tous les tokens npm. Auditer les versions publiees recemment depuis le compte.',
+
+  sandbox_runtime_deobfuscation_executed:
+    'ELEVE: new Function() ou eval() a execute un body de >500 octets derive d\'une string source obfusquee. ' +
+    'Pattern Axios 2026 OrDeR_7077: XOR + base64 decoded a l\'install puis execute en memoire. ' +
+    'Le statique voit l\'obfuscation, la sandbox confirme l\'execution effective. Lire le contenu deobfusque dans les logs preload, isoler la machine.',
 };
 
 function getPlaybook(threatType) {