muaddib-scanner 2.11.139 → 2.11.141

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 **20 parallel scanners** (274 detection rules), a **deobfuscation engine**, **inter-module dataflow analysis**, **compound scoring** (17 compound rules), and a gVisor/Docker sandbox to detect known threats and suspicious behavioral patterns in npm and PyPI packages. An XGBoost classifier exists in the codebase but is **currently inactive** (see [Evaluation Metrics](#evaluation-metrics) → ML Classifier section).
+MUAD'DIB combines **21 parallel scanners** (274 detection rules), a **deobfuscation engine**, **inter-module dataflow analysis**, **compound scoring** (20 compound rules), and a gVisor/Docker sandbox to detect known threats and suspicious behavioral patterns in npm and PyPI packages. An XGBoost classifier exists in the codebase but is **currently inactive** (see [Evaluation](#evaluation)).
 
 ---
 
@@ -45,6 +45,16 @@ MUAD'DIB is an educational tool and a free first line of defense. It detects **k
 
 ---
 
+## Scope
+
+**Detects** (npm & PyPI): known-malicious packages (name + SHA256 IOC match), typosquats, install-time RCE (lifecycle `preinstall`/`postinstall`, `curl | sh`, Python import-time, `binding.gyp`), credential read then network exfiltration (intra- and cross-file), obfuscated / high-entropy / stub-loader payloads, binary droppers (`chmod +x` + exec/spawn), and anti-analysis evasion markers.
+
+**Out of scope**: browser-only attacks (DOM/`window`, no Node.js API), the *contents* of native binaries / WASM (no binary analysis), zero-day unknown packages (the IOC feed is reactive), and non-npm/PyPI ecosystems (RubyGems, Maven, Go). Determined anti-sandbox fingerprinting and multi-stage remote payloads are known false-negative risks. Full detail: [Threat Model](docs/threat-model.md).
+
+**No telemetry.** Your code and scan results never leave your machine — MUAD'DIB only *downloads* threat-intel feeds (`muaddib update`) and, for scoring, reads public npm registry metadata. Webhook alerts are opt-in.
+
+---
+
 ## Installation
 
 ### npm (recommended)
@@ -176,7 +186,7 @@ muaddib replay                     # Ground truth validation (90/94 TPR@3, v2.11
 
 ## Features
 
-### 20 parallel scanners
+### 21 parallel scanners
 
 | Scanner | Detection |
 |---------|-----------|
@@ -201,10 +211,11 @@ muaddib replay                     # Ground truth validation (90/94 TPR@3, v2.11
 | Trusted-Dep-Diff (opt-in) | Diff against trusted dep tarballs from registry (v2.10.x) |
 | Python Source (PYSRC) | Import-time / install-time RCE patterns in `__init__.py` / `setup.py` (v2.11.41 — closes TrapDoor PyPI gap) |
 | Python AST (PYAST) | Tree-sitter-Python AST with taint-aware detectors (v2.11.42+) |
+| Anti-Scanner Injection (ASI) | Prompt-injection text in comments/strings that coerces an LLM code reviewer into a clean verdict or into skipping an obfuscated payload (ASI-001..004, Hades campaign 2026-06) |
 
 ### 274 detection rules
 
-All rules (269 RULES + 5 PARANOID) are mapped to MITRE ATT&CK techniques. See [SECURITY.md](SECURITY.md#detection-rules-v211117) for the complete rules reference.
+All rules (269 RULES + 5 PARANOID) are mapped to MITRE ATT&CK techniques. See [SECURITY.md](SECURITY.md#detection-rules-v211139) for the complete rules reference.
 
 ### Detected campaigns
 
@@ -278,75 +289,30 @@ With pre-commit framework:
 ```yaml
 repos:
   - repo: https://github.com/DNSZLSK/muad-dib
-    rev: v2.11.117
+    rev: v2.11.139
     hooks:
       - id: muaddib-scan
 ```
 
 ---
 
-## Evaluation Metrics
-
-Latest measurement: **v2.11.48** (2026-05-26, Track D + PyPI download fix). Ground truth holds 96 samples (94 in-scope, 2 out-of-scope protestware). This run measures the full 94 in-scope set after the 2026-05-25 enrichment (Track C synthetic for the new PYSRC/PYAST/AST-092/AICONF-004/PKG-022 rules, Track A real-world tarballs recovered from VPS archive, Track B reconstructions from the in-house security-review benchmark).
-
-### Operational metrics (what an operator actually gets)
-
-These are the numbers a user gets when running `muaddib scan` against npm or PyPI packages. The pipeline executes scanners + FP caps only — no ML filter is applied (see ML Classifier note below).
-
-| Metric | Result | Details |
-|--------|--------|---------|
-| **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% — last measurement v2.9.4, independent of GT. |
-| **TPR@3** (detection rate, v2.11.48) | **95.74%** (90/94 in-scope) | Full GT re-measurement. Threshold=3: any signal. 13 PyPI samples (was 0). 4 misses incl. 3 browser-only (lottie-player, polyfill-io, trojanized-jquery). |
-| **TPR@20** (alert rate, v2.11.48) | **88.30%** (83/94 in-scope) | Operational alert threshold=20. **+3.1pp vs v2.11.47** — Track D `recon_exfil_direct_ip` compound (MUADDIB-COMPOUND-016) closed the GT-095 gap (risk 3→50) and boosted GT-091 byvendors / GT-092 heloo131313 through `linux_fingerprint_exec`. |
-| **FPR rules** (Benign curated, v2.11.48 measure) | **1.10%** (6/545 scanned, 548 total) | **Unchanged after Track D** — the new compound + types created zero new FPs (sameFile gate + public-IP-only filter). Drop from 15.6% (v2.10.95) is attributable to FP caps F1-F14 (v2.10.97 → v2.11.31). 6 remaining FPs are real (meteor, prisma, @prisma/client, drizzle-orm, scrypt, liquid). |
-| **FPR** (Benign random, v2.11.48) | **2.50%** (5/200) | 200 random npm packages, unchanged. |
-| **FPR PyPI** (v2.11.48, first honest measurement) | **9.68%** (12/124 scanned, 132 total) | **Track D fixed the PyPI downloader** — removed `pip --no-binary :all:` flag (forced compile of wheel-only packages, timed out 38% of the time) + added `.whl` extraction via `extractArchive()`. Brought 42 previously-skipped giants (numpy/pandas/django/matplotlib/scikit-learn/...) into scope. All 12 FPs cluster at score 25-35: this is the cap-PyPI-35 artifact, not new rule misfires. Lifting the cap (Track E) would drop FPR PyPI to ≈0%. 8 residual fails are >500MB packages (torch, tensorflow, scipy, opencv-python, ansible…) hitting the 30s `PACK_TIMEOUT_MS`. |
-| **ADR** (Adversarial + Holdout, v2.11.48) | **96.26%** (103/107) | 67 adversarial + 40 holdout, global threshold=20. Stable vs v2.10.95. |
-
-**4414 tests** across 141 files. **266 rules** (261 RULES + 5 PARANOID; v2.11.67/70 Phantom Gyp added PKG-023 + COMPOUND-017).
-
-**Known issues (v2.11.48):**
-- *Cap PyPI à 35/100*: Python samples plafonnent à `riskScore=35` even when `globalRiskScore=100`. Confirmed empirically — all 12 PyPI FPs at score 25-35 (flask 32, django 35, tornado 35, bottle 30, pandas 25, matplotlib 25, plotly 25, bokeh 25, pymongo 35, coverage 32, fabric 35, websockets 35). Lifting the cap will simultaneously drop FPR PyPI to ≈0% and unblock PyPI MALWARE detection at higher thresholds. Track E target.
-
-### Operational coverage (v2.11.67-76)
-
-The static ground-truth TPR above is measured offline. Since v2.11.67 the monitor also tracks **operational** coverage on live npm/PyPI ingestion:
-- A per-scan **ledger** (`data/scan-ledger.jsonl`) records every scanned package's outcome; `computeLedgerRollup()` produces a 24h rollup (`alertRate`, per-ecosystem). Note: `alertRate` is a throughput signal, **not** detection TPR.
-- An active **GHSA poller** (~15 min; npm, pypi, crates) builds an authoritative "what should we have caught" denominator (`data/ghsa-malware.jsonl`), plus a **feed-health** alarm that fires when an IOC feed silently goes dark.
-- The Phase 5 **coverage-audit** (`scripts/coverage-audit.js`, daily 05:00 UTC) joins that denominator against ledger outcomes + the tarball archive to compute an honest GHSA-denominated **operational TPR** (`alerted / total`), and surfaces `scannedClean` misses as human-gated ground-truth candidates.
-
-This operational TPR is the real production detection rate, distinct from the static GT TPR (which has not been re-measured since v2.11.48).
-
-### ML Classifier (offline only)
-
-`src/ml/classifier.js` is **not wired into `muaddib scan`**. The XGBoost model is currently exercised only by `muaddib evaluate` (offline metric replay) and `muaddib monitor` (LOG-ONLY since 2026-04-08, model collapsed pending retrain — see `src/monitor/queue.js:628`). The v2.11.48 evaluate-time replay shows the same 1.10% FPR (no additional FPs filtered) — kept as a reference for retrain validation, but the published operational FPR is the rules-only number above.
-
-> **Static evaluation caveats:**
-> - TPR measured on the full 94 in-scope samples from the 96-sample ground truth (2 out-of-scope protestware GT-005/GT-009 with `min_threats=0`)
-> - TPR@3 = detection rate (any signal); TPR@20 = operational alert threshold
-> - FPR rules measured on 548 curated popular npm packages (not a random sample)
-> - FPR PyPI: 124/132 scanned (8 download fails on >500MB giants — torch/tensorflow/ansible/…). Smaller N than npm.
-> - ADR measured with global threshold (score >= 20) as of v2.6.5
-
-See [Evaluation Methodology](docs/EVALUATION_METHODOLOGY.md) for the full experimental protocol, holdout history, and Datadog benchmark details.
+## Evaluation
 
-### ML Classifier — R&D, currently inactive
+Last measured **v2.11.48** (2026-05-26), **rules-only** (the ML classifier is inactive — see below). Ground truth: 94 in-scope real-world attacks + 200 random npm + 124 PyPI + 107 adversarial/holdout.
 
-> **Status (2026-04-08 → present):** The XGBoost classifier (`src/ml/classifier.js`) is **not wired into `muaddib scan`** at all, and in `muaddib monitor` it runs in **LOG-ONLY mode** since 2026-04-08 — the trained model collapsed (predicts p≈0.002 for every input, including clearly malicious lifecycle+exec+staged_payload patterns) and was disabled pending retrain on balanced JSONL data. The metrics below come from offline `muaddib evaluate` replay against a frozen bench. They describe what the model *would* contribute if it worked, **not** what an operator gets today.
+| Metric | Result |
+|--------|--------|
+| Detection rate (TPR@3) | **95.74%** (90/94) |
+| Alert rate (TPR@20) | **88.30%** (83/94) |
+| FPR — curated npm (548) | **1.10%** (6/545) |
+| FPR — random npm (200) | **2.50%** (5/200) |
+| FPR — PyPI (132) | **9.68%** (12/124) |
+| ADR — adversarial + holdout | **96.26%** (103/107) |
+| Wild TPR (Datadog 17K) | **92.8%** (13,538/14,587) |
 
-| Metric (offline `evaluate` replay) | Result | Details |
-|--------|--------|---------|
-| **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 |
-| **FPR after ML T1** (offline replay, v2.11.48) | **1.10%** (6/545 scanned) | Classifier filters 0/6 raw FPs in this run (filtered 1 at v2.11.47). Not applied during real scans — `muaddib scan` never invokes the classifier. |
+**ML classifier: inactive.** An XGBoost model lives in `src/ml/` but is never wired into `muaddib scan`, and runs LOG-ONLY in the monitor since 2026-04-08 (the trained model collapsed, pending retrain). All numbers above are rules-only.
 
-> **Retrain methodology (v2.10.51):**
-> - Ground truth: 377 confirmed_malicious via auto-labeler (OSSF malicious-packages, GitHub Advisory Database, npm registry takedown correlation)
-> - Dataset: 56,564 samples (14,602 malicious, 41,962 clean). Stratified 80/20 split
-> - Grid search: depth=4, estimators=300, lr=0.05. AUC-ROC=0.999, F1=0.960
-> - Leaky feature filter: 23 dead/leaky features removed (source-identity proxies)
->
-> The shadow model continues to log predictions in `muaddib monitor` for retraining validation. When the next model passes shadow validation, the LOG-ONLY guard in `src/monitor/queue.js:660` will be flipped and the metrics above will move back into the operational table.
+Full protocol, per-track history, the PyPI cap-35 caveat, operational (GHSA-denominated) coverage, and the ML retrain methodology: [Evaluation Methodology](docs/EVALUATION_METHODOLOGY.md).
 
 ---
 
@@ -380,7 +346,7 @@ npm test
 
 ### Testing
 
-- **4414 tests** across 141 modular test files
+- **4500 tests** across 147 modular test files
 - **56 fuzz tests** - Malformed inputs, ReDoS, unicode, binary
 - **Datadog 17K benchmark** - 14,587 confirmed malware samples (in-scope)
 - **Ground truth validation** - 96 real-world attacks (95.74% TPR@3, 88.30% TPR@20 — v2.11.48 full measure on 94 in-scope)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muaddib-scanner",
-  "version": "2.11.139",
+  "version": "2.11.141",
   "description": "Supply-chain threat detection & response for npm & PyPI/Python",
   "main": "src/index.js",
   "bin": {
@@ -48,16 +48,16 @@
   },
   "dependencies": {
     "@inquirer/prompts": "8.5.2",
-    "acorn": "8.16.0",
+    "acorn": "8.17.0",
     "acorn-walk": "8.3.5",
     "adm-zip": "0.5.17",
-    "js-yaml": "4.2.0",
+    "js-yaml": "5.1.0",
     "web-tree-sitter": "^0.26.9"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "eslint": "10.4.1",
+    "eslint": "10.5.0",
     "eslint-plugin-security": "^4.0.0",
-    "globals": "17.6.0"
+    "globals": "17.7.0"
   }
 }

package/{self-scan-v2.11.139.json → self-scan-v2.11.141.json}

@@ -1,6 +1,6 @@
 {
   "target": "node_modules",
-  "timestamp": "2026-07-01T17:07:59.673Z",
+  "timestamp": "2026-07-01T21:11:52.228Z",
   "threats": [
     {
       "type": "string_mutation_obfuscation",
@@ -1068,28 +1068,6 @@
       "playbook": "SharedArrayBuffer + Worker Thread detectes. Canal IPC memoire partagee qui contourne la surveillance. Verifier si les workers manipulent des donnees sensibles. Isoler si combine avec eval/exec.",
       "points": 3
     },
-    {
-      "type": "dangerous_exec",
-      "severity": "MEDIUM",
-      "message": "[quick-scan] exec/spawn call detected in overflow file.",
-      "file": "eslint/lib/rules/eol-last.js",
-      "degraded": true,
-      "quickScan": true,
-      "count": 1,
-      "reductions": [],
-      "originalSeverity": "MEDIUM",
-      "confidenceTier": "low",
-      "rule_id": "MUADDIB-AST-007",
-      "rule_name": "Dangerous Shell Command Execution",
-      "confidence": "high",
-      "domain": "malware",
-      "references": [
-        "https://owasp.org/www-community/attacks/Command_Injection"
-      ],
-      "mitre": "T1059.004",
-      "playbook": "CRITIQUE: Execution de commande shell dangereuse detectee. Isoler la machine. Verifier si la commande a ete executee.",
-      "points": 3
-    },
     {
       "type": "dangerous_exec",
       "severity": "MEDIUM",
@@ -1468,7 +1446,29 @@
       "type": "dangerous_exec",
       "severity": "MEDIUM",
       "message": "[quick-scan] exec/spawn call detected in overflow file.",
-      "file": "js-yaml/lib/type/timestamp.js",
+      "file": "js-yaml/dist/browser/js-yaml.esm.min.mjs",
+      "degraded": true,
+      "quickScan": true,
+      "count": 1,
+      "reductions": [],
+      "originalSeverity": "MEDIUM",
+      "confidenceTier": "low",
+      "rule_id": "MUADDIB-AST-007",
+      "rule_name": "Dangerous Shell Command Execution",
+      "confidence": "high",
+      "domain": "malware",
+      "references": [
+        "https://owasp.org/www-community/attacks/Command_Injection"
+      ],
+      "mitre": "T1059.004",
+      "playbook": "CRITIQUE: Execution de commande shell dangereuse detectee. Isoler la machine. Verifier si la commande a ete executee.",
+      "points": 3
+    },
+    {
+      "type": "dangerous_exec",
+      "severity": "MEDIUM",
+      "message": "[quick-scan] exec/spawn call detected in overflow file.",
+      "file": "js-yaml/dist/browser/js-yaml.umd.min.js",
       "degraded": true,
       "quickScan": true,
       "count": 1,

package/src/scanner/ast-detectors/handle-call-expression.js

@@ -38,6 +38,51 @@ const {
   ETHEREUM_PACKAGES,
   SOLANA_PACKAGES
 } = require('./constants.js');
+
+// -----------------------------------------------------------------------------
+// SECURITY (E3 — audit 2026-07): ReDoS mitigation for static `.replace()`-chain resolution.
+// The resolver (Blue Team v8, below) statically re-applies `.replace(/regex/, str)` calls
+// taken from the SCANNED package to reconstruct obfuscated strings. On the CLI path this
+// runs synchronously on the main thread, so executing an attacker-authored regex that
+// catastrophically backtracks would wedge it. Note: the subject-length cap does NOT bound
+// this — exponential backtracking blows up on ~30 chars regardless of cap.
+//
+// Defense in depth (this is layer 1 of 2):
+//   Layer 1 (here): a BLOCKLIST of common catastrophic shapes + length caps, so the
+//     frequent cases fast-fail without running the regex. It is NOT exhaustive — a crafted
+//     pattern (e.g. nested groups like `((a+)x)+`) can slip past it.
+//   Layer 2 (hard bound): the monitor runs every scan in a Worker with a 45s
+//     STATIC_SCAN_TIMEOUT_MS -> worker.terminate() (src/monitor/queue.js). V8 TerminateExecution
+//     interrupts even a running regex (verified on Node 24 / V8 13.6: terminate returns ~6ms
+//     mid-backtrack) — TO CONFIRM on the VPS Node version: interruptible regexps have been in
+//     V8 since ~Node 16, but this was only tested on Node 24. On that basis a layer-1 bypass
+//     is bounded to <=45s and the worker is killed.
+//     The CLI runs the pipeline inline (src/index.js) and has no such backstop — one-shot,
+//     Ctrl-C-able, lower severity.
+//
+// A refused pattern only leaves the chain "unresolved" (still flagged by the depth>=4
+// fallback) — never a false negative by crash.
+// -----------------------------------------------------------------------------
+const MAX_REPLACE_REGEX_LEN = 200;    // reject absurdly long attacker regex sources
+const MAX_REPLACE_SUBJECT_LEN = 4000; // caps LINEAR/polynomial blowup on huge subjects (not exponential)
+
+// BLOCKLIST (non-exhaustive) of common catastrophic-backtracking regex shapes. Allows any
+// pattern that does not match a known-bad shape — the hard guarantee is layer 2 above, not
+// this heuristic. Its OWN patterns are linear (negated char classes only), so it introduces
+// no ReDoS of its own.
+function isCatastrophicReplaceRegex(src) {
+  if (typeof src !== 'string') return true;
+  // Quantifier applied to a group whose body already contains a quantifier:
+  //   (a+)+  (a*)*  (a+)*  ([ab]+)+  (\w+)*
+  if (/\([^()]*[+*][^()]*\)\s*[*+]/.test(src)) return true;
+  // Quantified group whose body contains a {n,m} repetition:  (\d{1,3})+
+  if (/\([^()]*\{\d+(?:,\d*)?\}[^()]*\)\s*[*+]/.test(src)) return true;
+  // Quantified group containing alternation (possible overlap):  (a|a)*  (ab|a)+
+  if (/\([^()]*\|[^()]*\)\s*[*+]/.test(src)) return true;
+  // Unbounded {n,} repetition applied to a group:  (...)+{2,}
+  if (/\)[*+?]?\{\d+,\}/.test(src)) return true;
+  return false;
+}
 const {
   extractStringValue,
   calculateShannonEntropy,
@@ -1919,14 +1964,20 @@ function handleCallExpression(node, ctx) {
             let replacement = null;
             // Extract regex or string pattern
             if (args[0].type === 'Literal' && args[0].regex) {
-              try { pattern = new RegExp(args[0].regex.pattern, args[0].regex.flags); } catch { /* skip */ }
+              // SECURITY (E3): the pattern is attacker-controlled. Refuse catastrophic
+              // shapes / over-long sources so a ReDoS can't wedge this synchronous scanner.
+              if (args[0].regex.pattern.length <= MAX_REPLACE_REGEX_LEN &&
+                  !isCatastrophicReplaceRegex(args[0].regex.pattern)) {
+                try { pattern = new RegExp(args[0].regex.pattern, args[0].regex.flags); } catch { /* skip */ }
+              }
             } else if (args[0].type === 'Literal' && typeof args[0].value === 'string') {
               pattern = args[0].value;
             }
             if (args[1].type === 'Literal' && typeof args[1].value === 'string') {
               replacement = args[1].value;
             }
-            if (pattern !== null && replacement !== null) {
+            // SECURITY (E3): also refuse to run any pattern against an oversized subject.
+            if (pattern !== null && replacement !== null && resolved.length <= MAX_REPLACE_SUBJECT_LEN) {
               resolved = resolved.replace(pattern, replacement);
             } else {
               resolved = null;
@@ -2101,4 +2152,4 @@ function handleCallExpression(node, ctx) {
 
 // _shadowClassifyMcpWrite is shared with handle-post-walk.js (the Wave-4
 // keyword-co-occurrence emitter — the third mcp_config_injection site).
-module.exports = { handleCallExpression, _shadowClassifyMcpWrite };
+module.exports = { handleCallExpression, _shadowClassifyMcpWrite, _isCatastrophicReplaceRegex: isCatastrophicReplaceRegex };

package/src/shared/constants.js

@@ -85,6 +85,10 @@ 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
+// Decompressed-size cap for tar.gz extraction (M4). PARTIAL tar-bomb mitigation only —
+// bypassable by a bomb forged to a multiple of 4GB + (<1GB), because the gzip ISIZE trailer
+// this is checked against is mod 2^32. A hard cap needs streaming decompression (separate tech debt).
+const MAX_EXTRACTED_SIZE = 1024 * 1024 * 1024; // 1GB
 
 // Shared scanner constants
 const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB — skip files larger than this to avoid memory issues
@@ -146,4 +150,4 @@ function clearASTCache() {
   _astCache.clear();
 }
 
-module.exports = { REHABILITATED_PACKAGES, NPM_PACKAGE_REGEX, MAX_TARBALL_SIZE, DOWNLOAD_TIMEOUT, MAX_FILE_SIZE, ACORN_OPTIONS, safeParse, clearASTCache, getMaxFileSize, setMaxFileSize, resetMaxFileSize };
+module.exports = { REHABILITATED_PACKAGES, NPM_PACKAGE_REGEX, MAX_TARBALL_SIZE, DOWNLOAD_TIMEOUT, MAX_EXTRACTED_SIZE, MAX_FILE_SIZE, ACORN_OPTIONS, safeParse, clearASTCache, getMaxFileSize, setMaxFileSize, resetMaxFileSize };

package/src/shared/download.js

@@ -3,7 +3,7 @@ const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
 const AdmZip = require('adm-zip');
-const { MAX_TARBALL_SIZE, DOWNLOAD_TIMEOUT } = require('./constants.js');
+const { MAX_TARBALL_SIZE, DOWNLOAD_TIMEOUT, MAX_EXTRACTED_SIZE } = require('./constants.js');
 const { registryAuthHeaders } = require('./registry-auth.js');
 
 // Allowed redirect domains for tarball downloads (SSRF protection)
@@ -241,6 +241,34 @@ function detectArchiveFormat(archivePath) {
   return 'unknown';
 }
 
+// SECURITY (M4 — audit 2026-07): PARTIAL tar-bomb mitigation.
+// Reads the gzip ISIZE trailer (last 4 bytes = uncompressed size mod 2^32) in O(1) memory,
+// synchronously, so _extractTarGzImpl can reject a declared-oversize archive BEFORE spawning
+// `tar` (rejecting pre-spawn matters: worker.terminate() can orphan a running tar child that
+// keeps writing to disk). LIMITATION — this is a PARTIAL mitigation, NOT a hard cap: because
+// ISIZE is mod 2^32, a bomb forged to a multiple of 4GB + (<1GB) wraps under the cap and evades
+// this hint; that narrow residual falls back to the 60s tar timeout. A complete cap requires
+// streaming decompression, which would make extraction async and ripple to all sync callers —
+// tracked as separate tech debt, deliberately not done here.
+function readGzipUncompressedHint(tgzPath) {
+  let fd;
+  try {
+    fd = fs.openSync(tgzPath, 'r');
+    const { size } = fs.fstatSync(fd);
+    if (size < 18) return null; // too small to be a valid gzip member
+    const magic = Buffer.alloc(2);
+    fs.readSync(fd, magic, 0, 2, 0);
+    if (magic[0] !== 0x1f || magic[1] !== 0x8b) return null; // not gzip — let tar error naturally
+    const isize = Buffer.alloc(4);
+    fs.readSync(fd, isize, 0, 4, size - 4);
+    return isize.readUInt32LE(0);
+  } catch {
+    return null; // unreadable hint — never block extraction on a hint failure
+  } finally {
+    if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* ignore */ } }
+  }
+}
+
 /**
  * Extract a tar.gz tarball with the system `tar` binary. Used for npm
  * tarballs and PyPI sdists. Internal implementation — call extractArchive
@@ -248,6 +276,14 @@ function detectArchiveFormat(archivePath) {
  * scanner/temporal-ast-diff.js callsite.
  */
 function _extractTarGzImpl(tgzPath, destDir) {
+  // SECURITY (M4): reject a declared-oversize gzip before `tar` ever runs. PARTIAL mitigation
+  // (bypassable by a 4GB-multiple + <1GB forged bomb) — see readGzipUncompressedHint.
+  const uncompressedHint = readGzipUncompressedHint(tgzPath);
+  if (uncompressedHint !== null && uncompressedHint > MAX_EXTRACTED_SIZE) {
+    throw new Error(
+      `Tar extract refused: declared uncompressed size ${uncompressedHint} exceeds ${MAX_EXTRACTED_SIZE} (possible decompression bomb)`
+    );
+  }
   // 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));
@@ -418,6 +454,7 @@ module.exports = {
   extractArchive,
   extractArchiveOffThread,
   detectArchiveFormat,
+  _readGzipUncompressedHint: readGzipUncompressedHint,
   sanitizePackageName,
   isAllowedDownloadRedirect,
   normalizeHostname,