muaddib-scanner 2.10.96 → 2.10.98

package/README.md

@@ -30,7 +30,7 @@
 
 npm and PyPI supply-chain attacks are exploding. Shai-Hulud compromised 25K+ repos in 2025. Existing tools detect threats but don't help you respond.
 
-MUAD'DIB combines **14 parallel scanners** (200 detection rules), a **deobfuscation engine**, **inter-module dataflow analysis**, **compound scoring**, **ML classifiers** (XGBoost), and gVisor/Docker sandbox to detect known threats and suspicious behavioral patterns in npm and PyPI packages.
+MUAD'DIB combines **14 parallel scanners** (209 detection rules), a **deobfuscation engine**, **inter-module dataflow analysis**, **compound scoring**, **ML classifiers** (XGBoost), and gVisor/Docker sandbox to detect known threats and suspicious behavioral patterns in npm and PyPI packages.
 
 ---
 
@@ -169,7 +169,7 @@ muaddib scrape                     # Full IOC refresh (~5min)
 muaddib diff HEAD~1                # Compare threats with previous commit
 muaddib init-hooks                 # Pre-commit hooks (husky/pre-commit/git)
 muaddib scan . --breakdown         # Explainable score decomposition
-muaddib replay                     # Ground truth validation (60/64 TPR@3)
+muaddib replay                     # Ground truth validation (61/65 TPR@3)
 ```
 
 ---
@@ -195,7 +195,7 @@ muaddib replay                     # Ground truth validation (60/64 TPR@3)
 | GitHub Actions | Shai-Hulud backdoor detection |
 | Hash Scanner | Known malicious file hashes |
 
-### 200 detection rules
+### 209 detection rules
 
 All rules are mapped to MITRE ATT&CK techniques. See [SECURITY.md](SECURITY.md#detection-rules-v21021) for the complete rules reference.
 
@@ -271,7 +271,7 @@ With pre-commit framework:
 ```yaml
 repos:
   - repo: https://github.com/DNSZLSK/muad-dib
-    rev: v2.10.57
+    rev: v2.10.97
     hooks:
       - id: muaddib-scan
 ```
@@ -285,14 +285,14 @@ repos:
 | **ML FPR** | **2.85%** (239/8,393 holdout) | XGBoost retrained on 56,564 samples, 64 features, threshold=0.710 |
 | **ML TPR** | **99.93%** (2,918/2,920 holdout) | 377 confirmed_malicious via OSSF/GHSA/npm correlation |
 | **Wild TPR** (Datadog 17K) | **92.8%** (13,538/14,587 in-scope) | 17,922 packages. 3,335 skipped (no JS). By category: compromised_lib 97.8%, malicious_intent 92.1% |
-| **TPR@3** (detection rate) | **93.75%** (60/64) | 66 real attacks (64 active, 2 out-of-scope). Threshold=3: any signal |
-| **TPR@20** (alert rate) | **85.9%** (55/64) | Operational alert threshold=20, aligned with ADR/FPR |
-| **FPR rules** (Benign curated) | **14.0%** (74/532) | 532 npm packages, real source via `npm pack` |
-| **FPR after ML** | **8.3%** (44/529) | ML filters 30/31 T1 benign, 0 GT/ADR suppressed |
-| **FPR** (Benign random) | **7.5%** (15/200) | 200 random npm packages, stratified sampling |
+| **TPR@3** (detection rate) | **93.85%** (61/65) | 67 real attacks (65 active, 2 out-of-scope: GT-005 colors, GT-009 faker — protestware with min_threats=0). Threshold=3: any signal |
+| **TPR@20** (alert rate) | **86.2%** (56/65) | Operational alert threshold=20, aligned with ADR/FPR |
+| **FPR rules** (Benign curated, v2.10.95 measure) | **15.6%** (85/545 scanned, 548 total) | npm packages, real source via `npm pack`; v2.10.74 estimated 6-9% reduction did NOT materialize on rebuilt corpus |
+| **FPR after ML** (v2.10.95 measure) | **10.28%** (56/545 scanned) | ML filters 29/30 T1 benign, 0 GT/ADR suppressed |
+| **FPR** (Benign random, v2.10.95 measure) | **7.0%** (14/200) | 200 random npm packages, stratified sampling |
 | **ADR** (Adversarial + Holdout) | **96.3%** (103/107) | 67 adversarial + 40 holdout (107 available on disk), global threshold=20 |
 
-**3230 tests** across 66 files. **207 rules** (202 RULES + 5 PARANOID).
+**3280 tests** across 69 files. **209 rules** (204 RULES + 5 PARANOID).
 
 > **ML retrain methodology (v2.10.51):**
 > - Ground truth: 377 confirmed_malicious via auto-labeler (OSSF malicious-packages, GitHub Advisory Database, npm registry takedown correlation)
@@ -301,7 +301,7 @@ repos:
 > - Leaky feature filter: 23 dead/leaky features removed (source-identity proxies)
 >
 > **Static evaluation caveats:**
-> - TPR measured on 64 active Node.js attack samples (2 out-of-scope from 66 total)
+> - TPR measured on 65 active Node.js attack samples (2 out-of-scope: GT-005 colors, GT-009 faker, both protestware with min_threats=0; from 67 total)
 > - TPR@3 = detection rate (any signal); TPR@20 = operational alert threshold
 > - FPR measured on 532 curated popular npm packages (not a random sample)
 > - ADR measured with global threshold (score >= 20) as of v2.6.5
@@ -340,11 +340,11 @@ npm test
 
 ### Testing
 
-- **3230 tests** across 66 modular test files
+- **3280 tests** across 69 modular test files
 - **56 fuzz tests** - Malformed inputs, ReDoS, unicode, binary
 - **Datadog 17K benchmark** - 14,587 confirmed malware samples (in-scope)
-- **Ground truth validation** - 67 real-world attacks (93.75% TPR@3, 85.9% TPR@20)
-- **False positive validation** - 14.0% FPR rules, 8.3% after ML on 532 curated npm packages, 7.5% on 200 random
+- **Ground truth validation** - 67 real-world attacks (93.85% TPR@3, 86.2% TPR@20 — v2.10.95 measure)
+- **False positive validation** (v2.10.95 measure) - 15.6% FPR rules (85/545 scanned), 10.28% after ML (56/545 scanned), 7.0% on 200 random
 
 ---
 
@@ -361,8 +361,7 @@ npm test
 - [Documentation Index](docs/INDEX.md) - All documentation in one place
 - [Evaluation Methodology](docs/EVALUATION_METHODOLOGY.md) - Experimental protocol, holdout scores
 - [Threat Model](docs/threat-model.md) - What MUAD'DIB detects and doesn't detect
-- [Adversarial Evaluation](ADVERSARIAL.md) - Red team samples and ADR results
-- [Security Policy](SECURITY.md) - Detection rules reference (207 rules)
+- [Security Policy](SECURITY.md) - Detection rules reference (209 rules)
 - [Security Audit](docs/SECURITY_AUDIT.md) - Bypass validation report
 - [FP Analysis](docs/EVALUATION.md) - Historical false positive analysis
 

package/package.json

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

package/src/ml/feature-extractor.js

@@ -696,7 +696,11 @@ function extractFeatures(result, meta) {
   features.typosquat_scoped_package = typosquatScopedPackage(result, meta) ? 1 : 0;
   features.obfuscation_without_vector = obfuscationWithoutVector(result) ? 1 : 0;
   features.placeholder_anti_dep_confusion = placeholderAntiDepConfusion(result, meta) ? 1 : 0;
-  features.install_script_no_network_egress = installScriptNoNetworkEgress(result, meta) ? 1 : 0;
+  // F8 disabled for retrain — fires on malware due to incomplete EGRESS_TYPES
+  // (missing dangerous_exec, lifecycle_dangerous_exec, node_inline_exec).
+  // Re-enable in v2.10.97 after EGRESS_TYPES fix + re-validation.
+  // See ml-retrain/ml-auc-v2.10.96.md for details.
+  features.install_script_no_network_egress = 0; // installScriptNoNetworkEgress(result, meta) ? 1 : 0;
 
   return features;
 }

package/src/monitor/adaptive-concurrency.js

@@ -56,6 +56,27 @@ const PLATEAU_STREAK_REQUIRED = 2; // must see flat throughput N times before tr
  * @returns {{ target: number, reason: string }}
  */
 function computeTarget(current, queueDepth, stats) {
+  // Priority 0: V8 heap pressure — os.freemem() misses this entirely.
+  // With --max-old-space-size=8192 on a 12GB VPS, system RAM can show 7GB free
+  // while V8 heap is at 90% and GC is thrashing. Use the daemon's circuit breaker
+  // level to gate concurrency before system RAM pressure kicks in.
+  try {
+    const { getMemoryPressureLevel, MEMORY_PRESSURE_LEVELS } = require('./daemon.js');
+    const heapPressure = getMemoryPressureLevel();
+    if (heapPressure >= MEMORY_PRESSURE_LEVELS.HIGH) {
+      const target = clamp(MIN_CONCURRENCY);
+      _prevScanned = stats.scanned || 0;
+      _prevTimeouts = (stats.errorsByType && stats.errorsByType.static_timeout) || 0;
+      return { target, reason: `heap_pressure_high (level=${heapPressure}, dropping to min=${MIN_CONCURRENCY})` };
+    }
+    if (heapPressure >= MEMORY_PRESSURE_LEVELS.ELEVATED) {
+      const target = clamp(Math.min(current, BASE_CONCURRENCY));
+      _prevScanned = stats.scanned || 0;
+      _prevTimeouts = (stats.errorsByType && stats.errorsByType.static_timeout) || 0;
+      return { target, reason: `heap_elevated (level=${heapPressure}, capping at base=${BASE_CONCURRENCY})` };
+    }
+  } catch { /* daemon.js not loaded yet on first tick — proceed with system RAM check */ }
+
   // Use system RAM, not V8 heap ratio (see MEMORY_FREE_THRESHOLD comment above)
   const freeMem = os.freemem();
   const totalMem = os.totalmem();

package/src/monitor/daemon.js

@@ -57,7 +57,7 @@ const MEMORY_PRESSURE_LEVELS = {
 const MEMORY_THRESHOLD_ELEVATED = 0.75;
 const MEMORY_THRESHOLD_HIGH = 0.85;
 const MEMORY_THRESHOLD_CRITICAL = 0.90;
-const MEMORY_THRESHOLD_EMERGENCY = 0.95;
+const MEMORY_THRESHOLD_EMERGENCY = 0.92;
 // When truncating queue under EMERGENCY, keep the N most recent items.
 // These are the newest packages — most likely to still be on npm for re-scan.
 const EMERGENCY_QUEUE_KEEP = 500;
@@ -743,7 +743,7 @@ async function startMonitor(options, stats, dailyAlerts, recentlyScanned, downlo
       const rssMB = (currentMem.rss / 1024 / 1024).toFixed(0);
       const pctUsed = (heapRatio * 100).toFixed(0);
       const levelName = Object.keys(MEMORY_PRESSURE_LEVELS).find(k => MEMORY_PRESSURE_LEVELS[k] === pressureLevel) || 'UNKNOWN';
-      console.log(`[MONITOR] MEMORY: heap=${heapUsedMB}MB/${heapLimitMB}MB (${pctUsed}%), rss=${rssMB}MB, queue=${scanQueue.length}, dedup=${recentlyScanned.size}, downloads=${downloadsCache.size}, alerts=${alertedPackageRules.size}, pressure=${levelName}`);
+      console.log(`[MONITOR] MEMORY: heap=${heapUsedMB}MB/${heapLimitMB}MB (${pctUsed}%), rss=${rssMB}MB, queue=${scanQueue.length}, dedup=${recentlyScanned.size}, downloads=${downloadsCache.size}, alerts=${alertedPackageRules.size}, dailyAlerts=${dailyAlerts.length}, pressure=${levelName}`);
 
       // Graduated response at HIGH+
       if (pressureLevel >= MEMORY_PRESSURE_LEVELS.HIGH) {
@@ -765,12 +765,19 @@ async function startMonitor(options, stats, dailyAlerts, recentlyScanned, downlo
       await sendDailyReport(stats, dailyAlerts, recentlyScanned, downloadsCache);
       // Auto-relabel JSONL training data after daily report (once per day).
       // Checks registry takedown status for unconfirmed packages.
+      // Guard: relabel reads the entire JSONL into memory (21-100MB). Skip if
+      // heap is already under pressure — will fire tomorrow instead.
       try {
-        const { relabelDataset } = require('./auto-labeler.js');
-        const summary = await relabelDataset({});
-        const totalRelabeled = summary.relabeled_malicious + summary.relabeled_benign + summary.relabeled_likely_benign;
-        if (totalRelabeled > 0) {
-          console.log(`[MONITOR] Auto-relabel: ${summary.relabeled_malicious} malicious, ${summary.relabeled_benign} benign, ${summary.relabeled_likely_benign} likely_benign (${summary.checked} checked)`);
+        const relabelPressure = computeMemoryPressure();
+        if (relabelPressure.level >= MEMORY_PRESSURE_LEVELS.HIGH) {
+          console.log(`[MONITOR] Auto-relabel SKIPPED: memory pressure at ${(relabelPressure.ratio * 100).toFixed(0)}% — will retry tomorrow`);
+        } else {
+          const { relabelDataset } = require('./auto-labeler.js');
+          const summary = await relabelDataset({});
+          const totalRelabeled = summary.relabeled_malicious + summary.relabeled_benign + summary.relabeled_likely_benign;
+          if (totalRelabeled > 0) {
+            console.log(`[MONITOR] Auto-relabel: ${summary.relabeled_malicious} malicious, ${summary.relabeled_benign} benign, ${summary.relabeled_likely_benign} likely_benign (${summary.checked} checked)`);
+          }
         }
       } catch (err) {
         // Non-fatal: relabel failure must never crash the monitor

package/src/monitor/deferred-sandbox.js

@@ -101,6 +101,23 @@ function enqueueDeferred(item) {
 
   _deferredQueue.push(item);
   _deferredSeen.add(key);
+  // Strip large fields to reduce in-memory footprint.
+  // Keep minimal staticResult for buildAlertData() if sandbox detects something.
+  // Disk persistence already strips staticResult (persistDeferredQueue), this
+  // does the same in-memory — each item drops from ~10-50KB to ~1-2KB.
+  if (item.staticResult) {
+    item.staticResult = {
+      threats: (item.staticResult.threats || []).map(t => ({
+        type: t.type, severity: t.severity, rule_id: t.rule_id, file: t.file
+      })),
+      summary: item.staticResult.summary ? {
+        total: item.staticResult.summary.total,
+        riskScore: item.staticResult.summary.riskScore,
+        maxSeverity: item.staticResult.summary.maxSeverity
+      } : {}
+    };
+  }
+  delete item.npmRegistryMeta;
   // Sort by riskScore DESC (highest first)
   _deferredQueue.sort((a, b) => b.riskScore - a.riskScore);
   console.log(`[DEFERRED] ENQUEUED: ${key} (tier=${item.tier === 2 ? 'T2' : 'T1b'}, score=${item.riskScore}, queue=${_deferredQueue.length})`);

package/src/monitor/queue.js

@@ -38,7 +38,8 @@ const {
   tarballCachePath,
   appendAlert,
   getParisHour,
-  hasReportBeenSentToday
+  hasReportBeenSentToday,
+  MAX_DAILY_ALERTS
 } = require('./state.js');
 
 // From ./classify.js
@@ -899,7 +900,9 @@ async function scanPackage(name, version, ecosystem, tarballUrl, registryMeta, s
         }
 
         // Record daily alert with post-reputation score for top suspects ranking
-        dailyAlerts.push({ name, version, ecosystem, findingsCount: result.summary.total, score: adjustedResult.summary.riskScore || 0, tier });
+        if (dailyAlerts.length < MAX_DAILY_ALERTS) {
+          dailyAlerts.push({ name, version, ecosystem, findingsCount: result.summary.total, score: adjustedResult.summary.riskScore || 0, tier });
+        }
         // LLM Detective: AI-powered analysis for T1a/T1b suspects
         // Skip for fast-track (large boring packages — LLM analysis adds 10-30s for no value)
         let llmResult = null;

package/src/monitor/state.js

@@ -20,6 +20,7 @@ const TEMPORAL_DETECTIONS_FILE = path.join(__dirname, '..', '..', 'data', 'tempo
 // --- Alerts/detections persistence limits ---
 const ALERTS_MAX_SIZE = 100 * 1024 * 1024; // 100MB rotation threshold (matches ml-training.jsonl)
 const MAX_DETECTIONS = 10_000;              // Cap detections array — oldest entries discarded
+const MAX_DAILY_ALERTS = 50_000;            // Cap dailyAlerts array — prevents unbounded growth between daily resets
 
 // Local log persistence directories (parallel to Discord webhooks for offline analysis)
 // Primary: logs/ relative to project root. Fallback: /tmp/ if primary is read-only (EROFS/EACCES).
@@ -736,8 +737,9 @@ function loadDailyStats(stats, dailyAlerts) {
       stats.llmSuppressed = data.llmSuppressed || 0;
       stats.changesStreamPackages = data.changesStreamPackages || 0;
       if (Array.isArray(data.dailyAlerts)) {
+        const restored = data.dailyAlerts.slice(-MAX_DAILY_ALERTS);
         dailyAlerts.length = 0;
-        dailyAlerts.push(...data.dailyAlerts);
+        dailyAlerts.push(...restored);
       }
       console.log(`[MONITOR] Restored daily stats: ${stats.scanned} scanned, ${stats.clean} clean, ${stats.suspect} suspect`);
     }
@@ -892,6 +894,7 @@ module.exports = {
   DAILY_STATS_PERSIST_INTERVAL,
   ALERTS_MAX_SIZE,
   MAX_DETECTIONS,
+  MAX_DAILY_ALERTS,
 
   // Mutable state getters/setters
   getScanMemoryCache,

package/src/monitor/temporal.js

@@ -11,7 +11,7 @@ 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 { appendAlert } = require('./state.js');
+const { appendAlert, MAX_DAILY_ALERTS } = require('./state.js');
 
 // ---------------------------------------------------------------------------
 // Feature-flag helpers
@@ -190,13 +190,15 @@ async function runTemporalCheck(packageName, dailyAlerts) {
         }))
       });
 
-      dailyAlerts.push({
-        name: packageName,
-        version: result.latestVersion,
-        ecosystem: 'npm',
-        findingsCount: result.findings.length,
-        temporal: true
-      });
+      if (dailyAlerts.length < MAX_DAILY_ALERTS) {
+        dailyAlerts.push({
+          name: packageName,
+          version: result.latestVersion,
+          ecosystem: 'npm',
+          findingsCount: result.findings.length,
+          temporal: true
+        });
+      }
 
       // Webhook deferred — sent after sandbox confirms (see resolveTarballAndScan)
     }
@@ -236,13 +238,15 @@ async function runTemporalAstCheck(packageName, dailyAlerts) {
         }))
       });
 
-      dailyAlerts.push({
-        name: packageName,
-        version: result.latestVersion,
-        ecosystem: 'npm',
-        findingsCount: result.findings.length,
-        temporalAst: true
-      });
+      if (dailyAlerts.length < MAX_DAILY_ALERTS) {
+        dailyAlerts.push({
+          name: packageName,
+          version: result.latestVersion,
+          ecosystem: 'npm',
+          findingsCount: result.findings.length,
+          temporalAst: true
+        });
+      }
 
       // Webhook deferred — sent after sandbox confirms (see resolveTarballAndScan)
     }
@@ -282,13 +286,15 @@ async function runTemporalPublishCheck(packageName, dailyAlerts) {
         }))
       });
 
-      dailyAlerts.push({
-        name: packageName,
-        version: 'N/A',
-        ecosystem: 'npm',
-        findingsCount: result.anomalies.length,
-        temporalPublish: true
-      });
+      if (dailyAlerts.length < MAX_DAILY_ALERTS) {
+        dailyAlerts.push({
+          name: packageName,
+          version: 'N/A',
+          ecosystem: 'npm',
+          findingsCount: result.anomalies.length,
+          temporalPublish: true
+        });
+      }
 
       // Webhook deferred — sent after sandbox confirms (see resolveTarballAndScan)
     }
@@ -329,13 +335,15 @@ async function runTemporalMaintainerCheck(packageName, dailyAlerts) {
         }))
       });
 
-      dailyAlerts.push({
-        name: packageName,
-        version: 'N/A',
-        ecosystem: 'npm',
-        findingsCount: result.findings.length,
-        temporalMaintainer: true
-      });
+      if (dailyAlerts.length < MAX_DAILY_ALERTS) {
+        dailyAlerts.push({
+          name: packageName,
+          version: 'N/A',
+          ecosystem: 'npm',
+          findingsCount: result.findings.length,
+          temporalMaintainer: true
+        });
+      }
 
       // Webhook deferred — sent after sandbox confirms (see resolveTarballAndScan)
     }

package/src/pipeline/processor.js

@@ -3,7 +3,7 @@ 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 } = require('../scoring.js');
+const { applyFPReductions, applyCompoundBoosts, calculateRiskScore, getSeverityWeights, applyContextualFPCaps } = require('../scoring.js');
 const { buildIntentPairs } = require('../intent-graph.js');
 const { debugLog } = require('../utils.js');
 
@@ -100,12 +100,21 @@ async function process(threats, targetPath, options, pythonDeps, warnings, scann
   // Read package name and dependencies for FP reduction heuristics
   let packageName = null;
   let packageDeps = null;
+  let _pkgMeta = null; // v2.10.97: full pkg metadata for contextual FP caps
   try {
     const pkgPath = path.join(targetPath, 'package.json');
     if (fs.existsSync(pkgPath)) {
       const pkgData = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
       packageName = pkgData.name || null;
       packageDeps = pkgData.dependencies || null;
+      _pkgMeta = {
+        name: pkgData.name,
+        scripts: pkgData.scripts || {},
+        description: pkgData.description || '',
+        homepage: pkgData.homepage || (typeof pkgData.repository === 'string' ? pkgData.repository : (pkgData.repository && pkgData.repository.url) || ''),
+        dependencies: pkgData.dependencies,
+        devDependencies: pkgData.devDependencies,
+      };
     }
   } catch { /* graceful fallback */ }
 
@@ -301,6 +310,15 @@ async function process(threats, targetPath, options, pythonDeps, warnings, scann
     scannerErrors: scannerErrors.length > 0 ? scannerErrors : undefined
   };
 
+  // v2.10.97: contextual FP post-filter — deterministic score caps for
+  // packages matching well-known FP clusters (100% precision, 302 human labels).
+  const fpCaps = applyContextualFPCaps(result, _pkgMeta);
+  if (fpCaps.length > 0) {
+    debugLog('[FP-CAP] ' + (packageName || targetPath) + ': ' +
+      fpCaps.map(c => c.feature + (c.cap > 0 ? '→MAX' + c.cap : '→suppress')).join(', ') +
+      ' → score=' + result.summary.riskScore);
+  }
+
   return {
     result,
     deduped,

package/src/scoring.js

@@ -1011,8 +1011,110 @@ function calculateRiskScore(deduped, intentResult) {
   };
 }
 
+// ============================================
+// v2.10.97: CONTEXTUAL FP POST-FILTER
+// ============================================
+// Deterministic score caps for packages matching well-known FP clusters.
+// Each feature has 100% precision on 302 human-reviewed packages (zero
+// malware misclassified).  Applied AFTER calculateRiskScore() so that
+// compound boosts and lifecycle floors have already had their say.
+const {
+  bundleWithoutInstallScripts,
+  installUrlGithubReleases,
+  networkDestinationFirstParty,
+  gitHookSourceLocal,
+  typosquatScopedPackage,
+  obfuscationWithoutVector,
+  placeholderAntiDepConfusion,
+} = require('./ml/feature-extractor.js');
+
+/**
+ * Apply contextual FP score caps to a scan result.
+ * Mutates result.summary.riskScore / riskLevel in-place.
+ * Returns array of { feature, cap } describing applied caps (empty if none).
+ */
+function applyContextualFPCaps(result, pkgMeta) {
+  if (!result || !result.summary) return [];
+
+  const meta = {
+    name: pkgMeta && pkgMeta.name,
+    registryMeta: {
+      scripts: (pkgMeta && pkgMeta.scripts) || {},
+      description: (pkgMeta && pkgMeta.description) || '',
+      homepage: (pkgMeta && pkgMeta.homepage) || '',
+      dependencies: (pkgMeta && pkgMeta.dependencies),
+      devDependencies: (pkgMeta && pkgMeta.devDependencies),
+    },
+  };
+
+  const applied = [];
+
+  // F7: placeholder anti-dep-confusion → MAX 20
+  if (placeholderAntiDepConfusion(result, meta)) {
+    applied.push({ feature: 'placeholder_anti_dep_confusion', cap: 20 });
+  }
+  // F1: minified bundle without install scripts → MAX 30
+  if (bundleWithoutInstallScripts(result, meta)) {
+    applied.push({ feature: 'bundle_without_install_scripts', cap: 30 });
+  }
+  // F3: credential destination first-party API → MAX 30
+  if (networkDestinationFirstParty(result, meta)) {
+    applied.push({ feature: 'network_destination_first_party', cap: 30 });
+  }
+  // F2: binary installer from GitHub Releases → MAX 35
+  if (installUrlGithubReleases(result)) {
+    applied.push({ feature: 'install_url_github_releases', cap: 35 });
+  }
+  // F4: git hooks from local source → MAX 35
+  if (gitHookSourceLocal(result)) {
+    applied.push({ feature: 'git_hook_source_local', cap: 35 });
+  }
+  // F6: commercial obfuscation without attack vector → MAX 35
+  if (obfuscationWithoutVector(result)) {
+    applied.push({ feature: 'obfuscation_without_vector', cap: 35 });
+  }
+  // F5: typosquat on scoped package → suppress typosquat points
+  if (typosquatScopedPackage(result, meta)) {
+    applied.push({ feature: 'typosquat_scoped_package', cap: -1 });
+  }
+
+  if (applied.length === 0) return applied;
+
+  // Apply the tightest (lowest) cap
+  const caps = applied.filter(a => a.cap > 0);
+  const lowestCap = caps.length > 0 ? Math.min(...caps.map(a => a.cap)) : Infinity;
+
+  if (lowestCap < result.summary.riskScore) {
+    result.summary.riskScore = lowestCap;
+    result.summary.riskLevel =
+      lowestCap >= _riskThresholds.CRITICAL ? 'CRITICAL'
+        : lowestCap >= _riskThresholds.HIGH ? 'HIGH'
+        : lowestCap >= _riskThresholds.MEDIUM ? 'MEDIUM'
+        : lowestCap > 0 ? 'LOW' : 'SAFE';
+  }
+
+  // F5: subtract typosquat points from score
+  if (applied.find(a => a.feature === 'typosquat_scoped_package')) {
+    const typoPoints = result.threats
+      .filter(t => t.type === 'typosquat_detected' || t.type === 'lifecycle_typosquat')
+      .reduce((s, t) => s + (t.points || 0), 0);
+    if (typoPoints > 0) {
+      result.summary.riskScore = Math.max(0, result.summary.riskScore - typoPoints);
+      const rs = result.summary.riskScore;
+      result.summary.riskLevel =
+        rs >= _riskThresholds.CRITICAL ? 'CRITICAL'
+          : rs >= _riskThresholds.HIGH ? 'HIGH'
+          : rs >= _riskThresholds.MEDIUM ? 'MEDIUM'
+          : rs > 0 ? 'LOW' : 'SAFE';
+    }
+  }
+
+  return applied;
+}
+
 module.exports = {
   SEVERITY_WEIGHTS, RISK_THRESHOLDS, MAX_RISK_SCORE, CONFIDENCE_FACTORS,
   isPackageLevelThreat, computeGroupScore, applyFPReductions, applyCompoundBoosts, calculateRiskScore,
-  applyConfigOverrides, resetConfigOverrides, getSeverityWeights, getRiskThresholds
+  applyConfigOverrides, resetConfigOverrides, getSeverityWeights, getRiskThresholds,
+  applyContextualFPCaps
 };