@lateos/npm-scan 0.16.0 → 0.16.5

package/README.md

@@ -1,801 +1,826 @@
-# @lateos/npm-scan
-
-[![npm version](https://img.shields.io/npm/v/@lateos/npm-scan?style=flat-square)](https://www.npmjs.com/package/@lateos/npm-scan)
-[![License](https://img.shields.io/badge/license-Apache%202.0%20%2B%20Commons%20Clause-blue?style=flat-square)](LICENSING.md)
-[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)](package.json)
-[![Tests](https://img.shields.io/badge/tests-536%20passing-brightgreen?style=flat-square)](https://github.com/lateos-ai/npm-scan)
-[![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen?style=flat-square)](https://github.com/lateos-ai/npm-scan)
-[![Docker](https://img.shields.io/badge/docker-lateos%2Fnpm--scan-2496ED?style=flat-square&logo=docker)](https://hub.docker.com/r/lateos/npm-scan)
-[![Sigstore](https://img.shields.io/static/v1?label=Sigstore&message=Provenance&color=green&style=flat-square&logo=sigstore)](https://github.com/lateos-ai/npm-scan/actions/workflows/publish.yml)
-
-[![中文](https://img.shields.io/badge/lang-zh--CN-red?style=flat-square)](https://github.com/lateos-ai/npm-scan/blob/main/README.zh.md)
-[![日本語](https://img.shields.io/badge/lang-ja-purple?style=flat-square)](https://github.com/lateos-ai/npm-scan/blob/main/README.ja.md)
-[![Français](https://img.shields.io/badge/lang-fr-orange?style=flat-square)](https://github.com/lateos-ai/npm-scan/blob/main/README.fr.md)
-[![Deutsch](https://img.shields.io/badge/lang-de-green?style=flat-square)](https://github.com/lateos-ai/npm-scan/blob/main/README.de.md)
-
-**Modern supply chain security for the npm ecosystem.**
-Static + behavioral analysis that catches what npm audit, Snyk, and Socket miss — obfuscated payloads, credential stealers, conditional triggers, sandbox evasion, and worm-like propagation.
-
----
-
-## 📌 The Problem
-
-The 2025–2026 wave of npm supply chain attacks proved that traditional tooling is no longer enough.
-
-Attackers have moved past simple typosquatting. They now ship **obfuscated preinstall hooks**, **credential harvesters hidden behind environment detection**, **dormant backdoors with time-based activation**, and **worm-style transitive propagation** that spreads through peer dependencies.
-
-A growing attack vector is **HuggingFace org impersonation** — packages that masquerade as legitimate HF model repositories (e.g., `0penai/gpt2` instead of `openai/gpt2`) to trick users into downloading malicious model artifacts during CI/CD pipelines, often bundled with suspicious binaries (`.exe`, `.dll`) in model repos that deep-learned tools trust by default.
-
-The **Megalodon campaign** (2026) alone compromised 5,500+ repositories via fake GitHub PRs, malicious workflow injection, and cloud credential exfiltration — all coordinated through a single actor automating the entire kill chain. **@lateos/npm-scan** now detects artifacts of this campaign out of the box.
-
-The **TrapDoor campaign** (May 2026) spans npm, PyPI, and Crates.io — 34 malicious packages, 384+ versions attributed to a single publisher, targeting crypto, DeFi, Solana, and AI developers with Fernet + ECDH encrypted payloads, AI context poisoning via zero-width Unicode injection in `.cursorrules`/`CLAUDE.md`, and credential live-validation against AWS STS and GitHub API before exfiltration. **@lateos/npm-scan** now detects all 9 TrapDoor signals.
-
-The **node-ipc compromise** (May 14, 2026) weaponized an expired maintainer email domain to hijack one of npm's most depended-upon packages (822K weekly downloads). Three malicious versions (9.1.6, 9.2.3, 12.0.1) delivered an 80KB credential stealer via DNS TXT tunneling — no HTTP, no postinstall hook, invisible to HTTP-layer firewalls. **@lateos/npm-scan** now detects all 11 node-ipc compromise signals.
-
-Critical infrastructure vulnerabilities in the Python ecosystem are also in scope. The **BadHost (CVE-2026-48710)** vulnerability in Starlette < 1.0.1 enables authentication bypass via unvalidated HTTP Host header injection, affecting FastAPI, vLLM, LiteLLM, MCP servers, and any project using Starlette transitively — now detected across Python manifests, transitive dependency chains, and source code patterns in a single scan.
-
-**npm audit** checks known CVEs. **Snyk** scans for vulnerabilities. **Socket** looks at package behavior. None of them were designed for the generation of attacks that emerged in 2025 — attacks that look benign until they reach production.
-
-**@lateos/npm-scan** was built for this moment.
-
----
-
-## 🔬 Why @lateos/npm-scan?
-
-| Capability | npm audit | Snyk | Socket | **@lateos/npm-scan** |
-|---|---|---|---|---|
-| Known CVE matching | ✅ | ✅ | ❌ | ✅ |
-| Static analysis | ❌ | ✅ | ✅ | ✅ |
-| Obfuscated payload detection | ❌ | ❌ | ❌ | ✅ |
-| AST-level heuristic analysis | ❌ | ❌ | ❌ | ✅ |
-| Runtime behavioral sandbox | ❌ | ❌ | ✅ | ✅ |
-| Conditional trigger detection (ATK-009) | ❌ | ❌ | ❌ | ✅ |
-| Sandbox evasion detection (ATK-010) | ❌ | ❌ | ❌ | ✅ |
-| Transitive worm propagation (ATK-011) | ❌ | ❌ | ❌ | ✅ |
-| Campaign detection (Megalodon CI/CD) | ❌ | ❌ | ❌ | ✅ |
-| Worm campaign detection (Mini Shai-Hulud Wave 1–3) | ❌ | ❌ | ❌ | ✅ |
-| HF model repo impersonation + README clone | ❌ | ❌ | ❌ | ✅ |
-| VS Code extension supply chain scan (--vsix) | ❌ | ❌ | ❌ | ✅ |
-| Python vulnerability detection (CVE-2026-48710 BadHost) | ❌ | ❌ | ❌ | ✅ |
-| Cross-ecosystem attack detection (TrapDoor) | ❌ | ❌ | ❌ | ✅ |
-| Expired-domain hijack detection (node-ipc) | ❌ | ❌ | ❌ | ✅ |
-| Attack taxonomy (ATK series) | ❌ | ❌ | ❌ | ✅ |
-| SBOM output (CycloneDX + SPDX) | ❌ | ✅ | ❌ | ✅ |
-| SARIF v2.1 (GitHub Code Scanning) | ❌ | ❌ | ❌ | ✅ |
-| NIST 800-161 compliance reporting | ❌ | ❌ | ❌ | ✅ |
-| EU CRA compliance reporting | ❌ | ❌ | ❌ | ✅ |
-| SIEM export (CEF / ECS / Sentinel / QRadar) | ❌ | ❌ | ❌ | ✅ |
-| Runs entirely locally — no telemetry | ✅ | ❌ | ❌ | ✅ |
-| Policy-as-code (YAML allowlists) | ❌ | ❌ | ❌ | ✅ |
-
-> **Privacy first.** All scanning happens on your machine. No code leaves your environment. No telemetry. No cloud dependency.
-
----
-
-## ✨ Key Features
-
-| Icon | Feature | Description |
-|------|---------|-------------|
-| 🕵️ | **Heuristic static analysis** | AST-level inspection catches obfuscation, eval chains, env probing, and suspicious lifecycle scripts that regex-based tools miss |
-| 🧠 | **Behavioral detection** | Identifies conditional triggers (time-based, CI-aware), sandbox evasion, and dormant activation patterns |
-| 🧬 | **ATK attack taxonomy** | 11 classified attack types with NIST 800-161 mappings — versioned, documented, and PR-able |
-| 🪱 | **Worm campaign detection** | Mini Shai-Hulud — 6 sub-checks detecting burst publish, sibling compromise, SLSA attestation mismatch, publisher drift, IOC match, and token exfil across 3 waves (TanStack, AntV/atool, Nx Console) |
-| 🧩 | **VSIX extension scanning** | `npm-scan scan --vsix nrwl.angular-console` — detects VS Code Marketplace supply chain attacks: burst publish, publisher anomaly, activation event risk, orphan commit fetch, known IOC, and exfil patterns (Nx Console 18.95.0 CVE-2026-48027) |
-| 🐍 | **Python vulnerability detection** | CVE-2026-48710 (BadHost) — Starlette Host header injection across 6 Python manifest formats, 15 transitive downstream packages (fastapi, vllm, litellm, MCP), and static `request.url.path` code pattern analysis with `scope["path"]` suppression |
-| 🪤 | **Cross-ecosystem attack detection** | TrapDoor — 9 sub-checks: campaign marker P-2024-001, trap-core.js payload fingerprint, publisher blocklist asdxzxc, Gist-based credential exfil, AI config zero-width Unicode poisoning, crypto/DeFi lure name heuristic, Fernet+ECDH encryption, XOR key cargo-build-helper-2026, STS/GitHub API credential validation |
-| 📡 | **Expired-domain hijack detection** | node-ipc compromise — version blocklist (9.1.6/9.2.3/12.0.1), tarball SHA-256 verification, CJS vs ESM size anomaly with IIFE injection, DNS-over-non-standard-port C2, bootstrap resolver sh.azurestaticprovider.net, DNS TXT exfil zone bt.node.js, setImmediate() runtime trigger, ~/nt-*/ staging artifacts, unauthorized publisher atiertant, lockfile blast-radius with safe pin recommendations |
-| 📦 | **SBOM generation** | CycloneDX 1.5 and SPDX 2.3 with findings embedded as vulnerabilities |
-| 🔍 | **SARIF output** | GitHub Advanced Security / CodeQL compatible SARIF v2.1 — shows findings directly in Security tab |
-| 🧾 | **Compliance reporting** | NIST SP 800-161 traceability matrix + EU Cyber Resilience Act mapping (free tier) |
-| 🔌 | **SIEM export** | Splunk CEF, Elastic ECS, Microsoft Sentinel, IBM QRadar formats (premium) |
-| 📜 | **Policy-as-code** | YAML/JSON policy engine with allowlists, severity overrides, suppressions, and fail-on thresholds |
-| 🐳 | **Docker + GitHub Action** | Multi-arch images, one-command Compose pipeline, PR scan action |
-| 🛡️ | **Zero telemetry** | No data leaves your machine. No cloud. No callbacks. |
-| 💾 | **Local scan history** | SQLite-backed persistence, zero external dependencies |
-| 🪝 | **Pre-commit hook** | Block threats before commit — one-liner install, scans `package-lock.json` changes |
-| 🤖 | **HF impersonation detection** | Detects typosquatted HuggingFace orgs (Jaro-Winkler), README clones (SimHash), artifact mismatches (`.exe` in model repos), and new-org amplifier — with lazy two-stage evaluation, zero network in Stage 1 |
-| 📎 | **Yarn + pnpm support** | `scan-lockfile` parses `yarn.lock` and `pnpm-lock.yaml` alongside `package-lock.json` |
-
----
-
-## ⚡ Quick Start
-
-```bash
-# Install globally
-npm install -g @lateos/npm-scan
-
-# Scan a single package
-npm-scan scan lodash
-
-# Scan your lockfile
-npm-scan scan-lockfile
-
-# View latest scans
-npm-scan report
-```
-
-**No install? No problem:**
-
-```bash
-npx @lateos/npm-scan scan commander
-```
-
----
-
-## 🐳 Run @lateos/npm-scan anywhere with Docker — zero installation
-
-```bash
-# Pull and run a single scan — no Node.js or npm required
-docker run --rm lateos/npm-scan:cli scan lodash
-
-# Full pipeline with persistent storage and Compose
-docker compose --profile pipeline up -d
-```
-
-No Node.js. No `npm install`. No global packages. Works on any system with Docker — CI servers, air-gapped environments, Kubernetes clusters. Multi-arch images for `linux/amd64` and `linux/arm64`.
-
----
-
-## 🛡️ Government & SOC 2 Ready
-
-| Feature | SOC 2 Controls | NIST 800-161 | STIG/FedRAMP Alignment |
-|---------|-------|--------------|--------------|
-| Audit logs (--audit-log) | CC6.8 | AU-2 | ✓ |
-| FIPS crypto (--fips) | CC6.1 | SC-13 | ✓ |
-| STIG report (--stig) | CC7.3 | RA-5 | ✓ |
-| Offline cache (--cache-dir) | A1.2 | SC-8 | ✓ |
-| Sigstore provenance | CC6.2 | SI-7 | ✓ |
-| SBOM (SPDX/CycloneDX) | CC7.4 | SA-10 | ✓ |
-
-```bash
-# Air-gapped scan with full compliance
-npm-scan scan-lockfile --cache-dir /offline/cache --audit-log /var/log/npm-scan.audit --fips
-npm-scan report --stig
-```
-
-[![SOC 2 Ready](https://img.shields.io/badge/SOC%202-Ready-green?style=flat-square&logo=aicpa)](https://www.aicpa.org/interestareas/frc/assuranceadvisoryservices/sorhome.html#soc2)
-[![FedRAMP Aligned](https://img.shields.io/badge/FedRAMP-Aligned-blue?style=flat-square&logo=fedramp)](https://fedramp.gov/baselines/)
-
----
-
-## ☁️ BYOC — Bring Your Own Cloud
-
-Deploy npm-scan in your VPC with full data sovereignty. No data leaves your infrastructure.
-
-| Feature | Description |
-|---------|-------------|
-| **Self-hosted** | Run on EKS/GKE/AKS in your AWS/Azure/GCP account |
-| **SIEM Export** | CEF/ECS/Sentinel/QRadar to your existing SIEM |
-| **SSO/OIDC** | SAML/OIDC integration with your identity provider |
-| **PDF Reports** | Generate NIST-compliant PDF reports locally |
-| **External DB** | Connect to your existing PostgreSQL/Redis |
-
-```bash
-# Deploy to your VPC with Helm
-git clone https://github.com/lateos-ai/npm-scan.git
-cd npm-scan/deploy/helm
-helm install npm-scan -f values.byoc.yaml .
-
-# BYOC values example (see values.byoc.yaml)
-premium:
-  enabled: true
-  edition: enterprise
-  byoc:
-    enabled: true
-    cloudProvider: aws
-    vpcId: vpc-xxx
-    region: us-east-1
-```
-
-**Pricing**: Enterprise license $10k/yr — self-supported (docs + GitHub issues).
-
----
-
-## 📖 Usage Examples
-
-### Scan a single package
-
-```bash
-# Default JSON output with all findings
-npm-scan scan axios
-
-# Generate an SBOM alongside the scan
-npm-scan scan express --sbom             # CycloneDX JSON
-npm-scan scan express --sbom xml         # CycloneDX XML
-npm-scan scan express --sbom spdx        # SPDX 2.3
-
-# Apply a YAML policy
-npm-scan scan some-package --policy .npm-scan.yml
-
-# Scan a local tarball (no registry fetch needed)
-npm-scan scan --file path/to/malicious-package.tgz
-
-# Scan a VS Code extension for Marketplace supply chain attacks
-npm-scan scan --vsix nrwl.angular-console
-
-# Scan a package AND a VSIX extension together (findings merge)
-npm-scan scan lodash --vsix nrwl.angular-console
-```
-
-### Scan a lockfile
-
-```bash
-# Scan a single package
-npm-scan scan lodash
-
-# Scan your lockfile
-npm-scan scan-lockfile
-
-# Scan a VS Code extension for supply chain threats
-npm-scan scan --vsix nrwl.angular-console
-
-# View latest scans
-npm-scan report
-```
-
-### Generate reports
-
-```bash
-# List all recent scans
-npm-scan report
-
-# View a specific scan
-npm-scan report -i 42
-
-# Generate an HTML report (free) with full findings + NIST table
-npm-scan report -i 42 --html
-
-# Print NIST 800-161 compliance table
-npm-scan report -i 42 --nist
-
-# Print EU CRA compliance table
-npm-scan report --cra
-
-# CSV export for Excel / Sheets (audit-ready)
-npm-scan report --csv risks.csv
-npm-scan scan lodash --csv          # CSV to stdout
-
-# Text report (free)
-npm-scan report --text
-
-# PDF report (premium)
-npm-scan report --pdf --license-key <key>
-
-# SIEM export (premium)
-npm-scan report --siem cef        # Splunk CEF
-npm-scan report --siem ecs        # Elastic ECS
-npm-scan report --siem sentinel   # Microsoft Sentinel
-npm-scan report --siem qradar     # IBM QRadar
-
-# Combine all scans into a single report
-npm-scan report --html            # all scans
-npm-scan report --pdf             # all scans (premium)
-```
-
----
-
-## 🧬 Detection Capabilities (ATK Taxonomy)
-
-| ID | Attack Class | Detection Method | Severity | NIST 800-161 |
-|---|---|---|---|---|
-| **ATK-001** | Malicious lifecycle scripts (`preinstall`, `postinstall`, `install`) | Static | 🔴 high | SR-3.1 |
-| **ATK-002** | Obfuscated payload delivery (hex, base64, eval chains) | Static | 🟠 medium | SR-4.2 |
-| **ATK-003** | Credential harvesting (env vars, .npmrc, SSH keys) | Static + Dynamic | 🔴 high | SR-5.3 |
-| **ATK-004** | Persistence via editor/config dirs (.vscode, .claude, .cursor) | Static | 🔴 high | SR-6.4 |
-| **ATK-005** | Network exfiltration (GitHub API, DNS tunneling, HTTP C2) | Static + Dynamic | ⚫ critical | SR-7.5 |
-| **ATK-006** | Dependency confusion / namespace squatting | Static (lockfile) | 🟠 medium | SR-2.2 |
-| **ATK-007** | Typosquatting (edit-distance matching) | Static | 🟢 low | SR-2.1 |
-| **ATK-008** | Tarball tampering (published ≠ source) | Static | 🔴 high | SR-8.1 |
-| **ATK-009** | Conditional/dormant triggers (CI detection, time-based) | Behavioral | 🔴 high | SR-9.2 |
-| **ATK-010** | Sandbox evasion / anti-analysis | Behavioral | 🟠 medium | SR-10.3 |
-| **ATK-011** | Transitive propagation (worm-style lateral spread) | Behavioral | 🔴 high | SR-11.4 |
-| **MEGALODON** | Megalodon CI/CD campaign — workflow C2 exfil, credential harvest, publish velocity spike, publisher drift | Static + Registry | ⚫ critical | SR-3.1, SR-7.5 |
-| **HF_IMPERSONATION** | HuggingFace org spoof detection — Jaro-Winkler similarity against 15 known-good orgs, SimHash README clone detection, artifact mismatch (`.exe`/`.dll` in model repos), postinstall escalation, new-org amplifier | Static + Network (Stage 2) | 🔴 high / ⚫ critical | SR-2.1 |
-| **MINI_SHAI_HULUD** | Mini Shai-Hulud worm campaign — burst publish velocity (≥3 versions/30 min), co-temporal sibling compromise, SLSA attestation mismatch (sub-60s gap, first-ever, builder mismatch), publisher drift (<10 min account change), IOC match (scope/sha512/publisher from seed file), token exfil (NPM_TOKEN/.npmrc/atob patterns), Nx Console downstream detection | Static + Registry | 🔴 high / ⚫ critical | SR-3.1, SR-7.5 |
-| **VSIX_SCAN** | VS Code extension supply chain scan — burst publish (≥2 versions/30 min, hot-pull <20 min), publisher anomaly (account substitution, new-account on high-install ext, 15-min add+publish), activation event risk (onStartupFinished→HIGH, *→CRITICAL, escalation on shell keywords), orphan commit fetch (GitHub API SHA refs, npx git URL, MCP-disguised exfil, Bun install), known IOC (extensionId/publisherAccount/commit hash from seed), exfil patterns (cred paths, DNS tunneling, AES+RSA, anti-analysis, Bun APIs) | Static + Registry | 🟠 medium / 🔴 high / ⚫ critical | SR-3.1, SR-5.3 |
-| **CVE-2026-48710** | BadHost — Starlette authentication bypass via Host header injection (CVE-2026-48710, CVSS 7.0). Python dependency version detection (requirements.txt, pyproject.toml, poetry.lock, Pipfile, setup.py/cfg), transitive heuristic (15 known downstream packages: fastapi, vllm, litellm, MCP servers, etc.), static code pattern scan for dangerous `request.url.path` usage in auth/middleware context with `request.scope["path"]` suppression | Static + Registry | 🔴 high / 🟠 medium / ℹ️ info | SR-3.1, SR-5.3 |
-| **TRAPDOOR** | TrapDoor cross-ecosystem attack — campaign marker P-2024-001 in files, shared payload trap-core.js filename/48,485-byte fingerprint, publisher blocklist asdxzxc, Gist-based credential exfil (ddjidd564.github.io + credential paths), AI context poisoning via zero-width Unicode in .cursorrules/CLAUDE.md, crypto/DeFi lure name heuristic (<30 days), Fernet+ECDH crypto primitives in postinstall, XOR key cargo-build-helper-2026 in lockfiles, STS/GitHub API credential validation in postinstall | Static + Registry | 🟠 medium / 🔴 high / ⚫ critical | SR-3.1, SR-5.3, SR-7.5 |
-| **NODE_IPC_COMPROMISE** | node-ipc supply chain compromise (May 14, 2026) — version blocklist (9.1.6/9.2.3/12.0.1) with safe pins, tarball SHA-256 verification, CJS payload IIFE injection detection (CJS>ESM size differential), injected payload hash match, DNS-over-non-standard-port C2 (setServers + custom resolver), bootstrap resolver sh.azurestaticprovider.net + C2 IP 37.16.75.69, DNS TXT exfiltration zone bt.node.js, setImmediate() runtime trigger, ~/nt-*/ staging artifact detection, unauthorized publisher atiertant, lockfile blast-radius detection with pin recommendations | Static + Registry | ⚫ critical | SR-3.1, SR-5.3, SR-7.5 |
-
-> **How evasive attacks are caught:** ATK-009 detects packages that check `process.env.CI`, probe hostnames, or use time-based activation. ATK-010 flags `debugger` statements, `os.hostname()` probes, and env fingerprinting. ATK-011 traces peer dependency graphs to detect worm-like propagation patterns.  
-> **MEGALODON** campaign detection analyzes bundled `.github/workflows/` files for C2 co-occurrence and base64 decode chains, scans tarball files for credential + outbound network patterns, detects version publish velocity spikes via npm registry metadata, and identifies publisher account drift — all without any network calls beyond the initial package fetch.  
-> **HF_IMPERSONATION** detection uses a lazy two-stage evaluation: Stage 1 scans `package.json` scripts and JS/TS sources for HuggingFace references (URLs, `from_pretrained()`, `hub.download()`) and runs Jaro-Winkler similarity against 15 known-good HF orgs — zero network. If spoofs are found, Stage 2 fetches the HF model API, computes SimHash of both READMEs for clone detection, validates artifact type consistency (e.g., `transformers` library with `.exe` files is flagged as critical), applies a new-org amplifier (<30 days), and escalates when the reference appears in a lifecycle script.  
-> **MINI_SHAI_HULUD** worm campaign detection uses a lazy two-stage evaluation: Stage 1 runs burst velocity, publisher drift, IOC, and token exfil checks (in-memory, no network). If burst triggers, Stage 2 queries npm attestation endpoints for SLSA anomalies and fetches sibling package registry metadata for co-temporal burst detection. Composite finding includes wave attribution (wave1-tanstack, wave2-antv, wave3-nx-console) and critical severity when SLSA or IOC match. NX_CONSOLE_DOWNSTREAM (D7) flags npm packages with `@nx/*` dependencies and checks for `nrwl.angular-console` in `.vscode/extensions.json`.  
-> **VSIX_SCAN** extension scanning wraps both VS Code Marketplace and Open VSX registries with rate-limited (10 req/min), cached (5 min TTL) API clients. All 6 detectors run asynchronously and aggregate into a single composite `VSIX_SCAN` finding. Zero extension code is executed — all analysis is static regex/text-pattern matching. No Bun installation required for Bun pattern detection.  
-> **CVE-2026-48710 (BadHost)** detection uses three independent layers: Layer 1 parses 6 Python manifest formats (requirements.txt, pyproject.toml, poetry.lock, Pipfile, setup.py, setup.cfg) with PEP 440 semver-aware version comparison. Layer 2 scans for 15 known Starlette-downstream packages with Tier 1 (HIGH confidence) and Tier 2 (MEDIUM confidence) transitive heuristics, suppressed by explicit `starlette >= 1.0.1` pin. Layer 3 performs function-boundary static analysis on `.py` files for `request.url.path` usage, escalating to MEDIUM severity in auth/middleware contexts and suppressing when `request.scope["path"]` is used in the same function.  
-> **TRAPDOOR** campaign detection runs 9 sub-detectors across all package files (README.md, package.json, .md, shell scripts, .cursorrules, CLAUDE.md) for the hardcoded marker P-2024-001, scans for trap-core.js by filename or exact 48,485-byte size, unconditionally blocks publisher asdxzxc, detects outbound references to ddjidd564.github.io or gist.github.com combined with credential-path patterns, scans .cursorrules and CLAUDE.md for zero-width Unicode characters (U+200B, U+200C, U+200D, U+FEFF), flags crypto/DeFi-themed packages <30 days old with no prior version history, detects simultaneous Fernet and ECDH/createECDH usage in postinstall JS, and identifies sts.amazonaws.com and api.github.com/user calls in postinstall hooks.  
-> **NODE_IPC_COMPROMISE** detection intercepts the expired-domain takeover attack across 11 dimensions: version blocklist with safe-pin recommendations (9.1.5 for 9.x, 12.0.0 for 12.x), tarball SHA-256 hash verification against known malicious hashes, CJS vs ESM size comparison with IIFE suffix pattern detection for injected payload identification, DNS resolver pattern analysis (dns.promises.Resolver + setServers with non-public IP + resolveTxt), bootstrap domain and C2 IP detection, resolveTxt() with bt.node.js zone references, setImmediate() runtime trigger detection, ~/nt-*/ staging artifact path identification, publisher account verification against unauthorized account atiertant, and lockfile scanning for compromised version resolution with safe-pin suggestions.  
-> See [`docs/attack-taxonomy.md`](docs/attack-taxonomy.md) for full evasion surface documentation and PoC examples.
-
----
-
-## 📊 Output & Reports
-
-### Formats
-
-| Format | Availability | Description |
-|--------|-------------|-------------|
-| JSON | ✅ Free | Structured machine-readable findings |
-| HTML | ✅ Free | Rich HTML report with NIST compliance table, severity badges, control matrix |
-| Text | ✅ Free | Clean terminal-friendly text report |
-| CycloneDX SBOM | ✅ Free | Industry-standard SBOM with findings as vulnerabilities |
-| SPDX SBOM | ✅ Free | SPDX 2.3 document format |
-| NIST 800-161 | ✅ Free | Control traceability matrix (SR-2.1 → SR-11.4) |
-| EU CRA | ✅ Free | Cyber Resilience Act article mapping |
-| PDF | 🔐 Premium | Multi-page PDF with title page, findings table, NIST compliance matrix |
-| Splunk CEF | 🔐 Premium | Common Event Format for Splunk ingestion |
-| Elastic ECS | 🔐 Premium | Elastic Common Schema format |
-| Microsoft Sentinel | 🔐 Premium | Sentinel-ready formatted output |
-| IBM QRadar | 🔐 Premium | QRadar DSM-ready format with QID mappings |
-
-### Sample output
-
-```json
-{
-  "scanId": 1,
-  "findings": [
-    {
-      "id": "ATK-003",
-      "severity": "high",
-      "title": "Credential harvesting",
-      "evidence": "process.env.NPM_TOKEN detected in postinstall.js:17"
-    }
-  ]
-}
-```
-
----
-
-## ⚙️ Configuration & Advanced Usage
-
-### Policy-as-code
-
-Define allowlists, severity overrides, suppressions, and fail thresholds in a YAML file:
-
-```yaml
-# .npm-scan.yml
-allowlist:
-  - lodash
-  - chalk
-
-severity_overrides:
-  - id: ATK-001
-    severity: medium
-
-suppress:
-  - atk_id: ATK-009
-  - package: some-package
-
-fail_on: high
-```
-
-```bash
-npm-scan scan target --policy .npm-scan.yml
-```
-
-### Environment variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `NPM_SCAN_LICENSE_KEY` | Premium / enterprise license key | — |
-| `NPM_SCAN_DATA_DIR` | Scan history directory | `./.npm-scan` |
-| `NPM_SCAN_LOG_LEVEL` | Log verbosity | `info` |
-| `NPM_SCAN_LICENSE_SECRET` | HMAC key for license generation/validation | `npm-scan-default-dev-key` |
-
-### IOC configuration
-
-Campaign detectors use seed IOC files for known-malicious fingerprints:
-
-| IOC File | Detector | Types |
-|----------|----------|-------|
-| `backend/detectors/mini-shai-hulud/iocs.json` | Mini Shai-Hulud (Waves 1–3) | `packageScope`, `publisherAccount`, `sha512`, `extensionId` |
-| `backend/detectors/trapdoor/iocs.json` | TrapDoor | `publisherAccount`, `campaignMarker`, `payloadFilename`, `payloadSize`, `xorKey`, `c2Domain`, `gistDomain` |
-| `backend/detectors/node-ipc-compromise/iocs.json` | node-ipc compromise | `publisherAccount`, `c2Domain`, `c2IP`, `exfilZone`, `payloadHash` |
-| `backend/vsix-scan/vsix-iocs.json` | VSIX extension scan | `extensionId`, `publisherAccount`, `orphanCommitHash` |
-
-IOC files follow a unified schema (`iocs: [{ type, value, ... }]`) and are loaded at module init. Update them from your threat intel feed to extend detection coverage without code changes.
-
-### Premium licensing
-
-Contact leo@lateos.ai for a premium/enterprise license key.
-
-```bash
-# Use it
-npm-scan scan target --license-key <key>
-npm-scan report --pdf --license-key <key>
-npm-scan report --siem cef --license-key <key>
-```
-
----
-
-## 🔗 Integrations
-
-### GitHub Actions CI (for this repo)
-
-Every push and PR runs tests across Node 18, 20, and 22:
-
-```yaml
-# .github/workflows/ci.yml
-name: CI
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [18, 20, 22]
-    steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-node@v4
-      with:
-        node-version: ${{ matrix.node-version }}
-        cache: 'npm'
-    - run: npm ci
-    - run: npm test
-    - run: npm run test:coverage
-    - run: node --test test/detectors-corpus.test.js
-    - run: npm run lint
-    - run: npm run build
-```
-
-### GitHub Action (for downstream users)
-
-Scan your project's `package-lock.json` on every PR — detects typosquats, obfuscated payloads, credential harvesters, and worm propagation before they reach production. **SARIF output shows findings directly in GitHub's Security tab (Code Scanning).**
-
-```yaml
-# .github/workflows/scan.yml
-name: npm-scan
-on:
-  pull_request:
-    paths:
-      - 'package-lock.json'
-      - '**/package.json'
-jobs:
-  scan:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-    - uses: lateos/npm-scan@v1
-      with:
-        scan-type: lockfile
-        sarif: results.sarif
-        fail-on: high
-    - name: Upload SARIF to Security tab
-      uses: github/codeql-action/upload-sarif@v3
-      with:
-        sarif_file: results.sarif
-```
-
-#### Action inputs
-
-| Input | Default | Description |
-|-------|---------|-------------|
-| `scan-type` | `lockfile` | `lockfile` to scan `package-lock.json` or `package` to scan a specific npm package |
-| `package` | — | Package name (required when `scan-type=package`) |
-| `fail-on` | `high` | Fail the workflow at this severity threshold: `none`, `low`, `medium`, `high`, `critical` |
-| `policy-file` | — | Path to a YAML/JSON policy file for allowlists, severity overrides, and suppressions |
-| `license-key` | — | Premium license key for SIEM export and PDF reports |
-| `siem-format` | — | SIEM output: `cef`, `ecs`, `sentinel`, `qradar` (premium) |
-| `sbom-format` | — | SBOM output: `json`, `xml`, `spdx` |
-
-#### Action outputs
-
-| Output | Description |
-|--------|-------------|
-| `findings-count` | Number of findings detected |
-| `scan-id` | Scan ID for later reference in reports |
-
-#### Example: scan a specific package with policy + SBOM
-
-```yaml
-- uses: lateos/npm-scan@v1
-  with:
-    scan-type: package
-    package: lodash
-    policy-file: .npm-scan.yml
-    sbom-format: spdx
-    fail-on: critical
-```
-
-#### Example: scan with SIEM export (premium)
-
-```yaml
-- uses: lateos/npm-scan@v1
-  with:
-    scan-type: lockfile
-    siem-format: cef
-    license-key: ${{ secrets.NPM_SCAN_LICENSE_KEY }}
-```
-
-### CI/CD pipeline
-
-Integrate directly into your existing pipeline without the composite action:
-
-```bash
-# Scan lockfile, fail build on high severity
-npm-scan scan-lockfile --policy .npm-scan.yml || exit 1
-
-# Scan a specific package, fail on critical only
-npm-scan scan lodash --policy .npm-scan.yml || exit 1
-
-# Generate SBOM as a build artifact
-npm-scan scan express --sbom spdx > express-sbom.spdx.json
-
-# Generate HTML compliance report in CI
-npm-scan report --html > report.html
-
-# Upload report as an artifact
-# uses: actions/upload-artifact@v4
-#   with:
-#     name: npm-scan-report
-#     path: report.html
-```
-
-### Docker
-
-See the [Docker quick-start section](#-run-lateosnpm-scan-anywhere-with-docker--zero-installation) above for pull commands, Compose pipeline, and multi-arch images.
-
-Scan your project's `package-lock.json` on every PR — detects typosquats, obfuscated payloads, credential harvesters, and worm propagation before they reach production:
-
-```yaml
-# .github/workflows/scan.yml
-name: npm-scan
-on:
-  pull_request:
-    paths:
-      - 'package-lock.json'
-      - '**/package.json'
-jobs:
-  scan:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-node@v4
-      with:
-        node-version: 20
-    - name: Scan lockfile
-      uses: lateos/npm-scan@v1
-      with:
-        scan-type: lockfile
-        fail-on: high
-```
-
-#### Action inputs
-
-| Input | Default | Description |
-|-------|---------|-------------|
-| `scan-type` | `lockfile` | `lockfile` to scan `package-lock.json` or `package` to scan a specific npm package |
-| `package` | — | Package name (required when `scan-type=package`) |
-| `fail-on` | `high` | Fail the workflow at this severity threshold: `none`, `low`, `medium`, `high`, `critical` |
-| `policy-file` | — | Path to a YAML/JSON policy file for allowlists, severity overrides, and suppressions |
-| `license-key` | — | Premium license key for SIEM export and PDF reports |
-| `siem-format` | — | SIEM output: `cef`, `ecs`, `sentinel`, `qradar` (premium) |
-| `sbom-format` | — | SBOM output: `json`, `xml`, `spdx` |
-
-#### Action outputs
-
-| Output | Description |
-|--------|-------------|
-| `findings-count` | Number of findings detected |
-| `scan-id` | Scan ID for later reference in reports |
-
-#### Example: scan a specific package with policy + SBOM
-
-```yaml
-- uses: lateos/npm-scan@v1
-  with:
-    scan-type: package
-    package: lodash
-    policy-file: .npm-scan.yml
-    sbom-format: spdx
-    fail-on: critical
-```
-
-#### Example: scan with SIEM export (premium)
-
-```yaml
-- uses: lateos/npm-scan@v1
-  with:
-    scan-type: lockfile
-    siem-format: cef
-    license-key: ${{ secrets.NPM_SCAN_LICENSE_KEY }}
-```
-
-### CI/CD pipeline
-
-Integrate directly into your existing pipeline without the composite action:
-
-```bash
-# Scan lockfile, fail build on high severity
-npm-scan scan-lockfile --policy .npm-scan.yml || exit 1
-
-# Scan a specific package, fail on critical only
-npm-scan scan lodash --policy .npm-scan.yml || exit 1
-
-# Generate SBOM as a build artifact
-npm-scan scan express --sbom spdx > express-sbom.spdx.json
-
-# Generate HTML compliance report in CI
-npm-scan report --html > report.html
-
-# Upload report as an artifact
-# uses: actions/upload-artifact@v4
-#   with:
-#     name: npm-scan-report
-#     path: report.html
-```
-
-### Pre-commit hook
-
-Block supply chain threats **before** they reach version control — no CI required.
-
-```bash
-# One-liner install (requires Node 18+, Git)
-npx husky@latest init && npm install && npx husky add .husky/pre-commit "npx lint-staged"
-```
-
-**What it does:** On every `git commit`, lint-staged detects staged changes to `package.json` or `package-lock.json` and runs `npm-scan scan-lockfile --fail-on high`. Commits are blocked if threats are found.
-
-```bash
-$ git commit -m "bump lodash"
-✔ Preparing lint-staged configuration...
-✔ Running tasks for staged package*.json files...
-✔ npm-scan scan-lockfile --fail-on high
-  🔴 ATK-003: Credential exfiltration (DNS lookup to credentialharvest.example.com)
-  🔴 ATK-007: Typosquat detected (lodash@7.7.7)
-  ⚠ Exiting with code 1 — threat(s) found
-
-npm scan • @lateos/npm-scan v0.11.6
-error: Command failed with exit code 1.
-```
-
-Add `--no-verify` to bypass for emergencies (`git commit -m "emergency fix" --no-verify`).
-
-### Docker
-
-See the [Docker quick-start section](#-run-lateosnpm-scan-anywhere-with-docker--zero-installation) above for pull commands, Compose pipeline, and multi-arch images.
-
----
-
-## 🗺️ Roadmap & Enterprise Features
-
-### Free tier (shipped)
-
-- All 11 ATK detectors + **MEGALODON** CI/CD campaign detection (D1–D6) + **HF_IMPERSONATION** detector + **MINI_SHAI_HULUD** worm campaign (D1–D7, 3 waves) + **VSIX_SCAN** extension supply chain scan (6 detectors) + **CVE-2026-48710 (BadHost)** Python vulnerability detection (3 layers) + **TRAPDOOR** cross-ecosystem attack detection (9 rules) + **NODE_IPC_COMPROMISE** expired-domain hijack detection (11 rules)
-- SBOM output (CycloneDX + SPDX)
-- HTML, text, and compliance reports (NIST + EU CRA)
-- Policy-as-code engine (YAML)
-- Local SQLite scan history
-- GitHub Action
-- Pre-commit hook (husky + lint-staged)
-- Docker images + Compose pipeline
-- Watch mode (--watch / --monorepo for auto-rescan)
-- VS Code extension scanning (--vsix flag with Marketplace + Open VSX registries)
-
-### Premium (🔐 license key)
-
-- PDF compliance reports with NIST traceability matrix
-- SIEM export (Splunk CEF, Elastic ECS, Microsoft Sentinel, IBM QRadar)
-- Dynamic sandbox (gVisor-based — ATK-008–010)
-- Reachability analysis (call graph filtering)
-
-### Enterprise (🏢 custom license)
-
-- SAML 2.0 SSO (Okta, Azure AD, OneLogin, Keycloak)
-- REST API + webhooks (FastAPI)
-- Team RBAC + audit logs
-- Helm chart for Kubernetes deployment
-- PostgreSQL backend for hosted/team tier
-- SLA-backed priority support
-
----
-
-## 🤝 Contributing
-
-We welcome contributions — especially new detectors, improved evasion resistance, and compliance templates.
-
-See [`docs/attack-taxonomy.md`](docs/attack-taxonomy.md) for the ATK governance process. Every new detector requires:
-
-1. A proof-of-concept sample
-2. A detection rule with tests
-3. False-positive analysis on top-500 npm packages
-4. NIST 800-161 control mapping
-
-### Testing
-
-The project uses the **Node.js native test runner** (`node:test` + `assert/strict`).
-
-```bash
-# Run all tests
-npm test
-
-# Run tests with coverage
-npm run test:coverage
-
-# Run tests with verbose spec output
-npm run test:verbose
-
-# Run local malicious/clean corpus (no network needed)
-node --test test/detectors-corpus.test.js
-```
-
-**Test structure:**
-- `test/fixtures/mock-data.js` — shared mock scans, packages, and code snippets
-- `test/megalodon.test.js` — 30 Megalodon campaign detection tests (D1–D4 + aggregator + runAll integration)
-- `test/db.test.js` — database CRUD (save, query, persist)
-- `test/detectors-edge-cases.test.js` — per-detector boundary tests (no-ops, clean clears, severity)
-- `test/detectors-corpus.test.js` — 33 malicious + 50 clean tarball integration (offline)
-- `test/fetch.test.js` — tarball extraction, temp directory cleanup
-- `test/policy-edge-cases.test.js` — edge cases in suppress, override, load validation
-- `test/policy.test.js` — policy YAML/JSON load, apply, suppress, severity override tests
-- `test/report-snapshots.test.js` — HTML/text/CRA/PDF format assertions
-- `test/report.test.js` — SARIF, CSV, STIG, risk score format tests
-- `test/lockfile.test.js` — npm/yarn/pnpm parser, auto-detect, ATK-007/011 lockfile tests
-- `test/hf-impersonation.test.js` — 13 HF impersonation detection tests (no-ref, exact match, spoof, README clone, artifact mismatch, postinstall escalation, new-org tag)
-- `test/mini-shai-hulud.test.js` — 22 Mini Shai-Hulud worm campaign detection tests (burst, sibling, SLSA, maintainer, IOC, exfil, wave attribution)
-- `test/vsix-scan/burst-publish.test.js` — 4 VSIX burst publish tests (threshold, sub-threshold, hot-pull, Open VSX window)
-- `test/vsix-scan/publisher-anomaly.test.js` — 5 publisher anomaly tests (cross-namespace, new-account, add+publish, substitution, silent)
-- `test/vsix-scan/activation-event-risk.test.js` — 5 activation event risk tests (onStartupFinished, wildcard, escalation, first-time, silent)
-- `test/vsix-scan/orphan-commit-fetch.test.js` — 5 orphan commit tests (GitHub SHA, npx git, MCP exfil, Bun install, silent)
-- `test/vsix-scan/known-ioc.test.js` — 4 known IOC tests (extensionId, publisher window, outside window)
-- `test/vsix-scan/exfil-pattern.test.js` — 5 exfil pattern tests (creds, DNS tunnel, AES+RSA, anti-analysis, silent)
-- `test/vsix-scan/integration.test.js` — 4 integration tests (Nx Console CRITICAL, safe version clean, orphan commit, skipNetwork)
-- `test/cve-2026-48710-badhost/manifest.test.js` — 13 Python manifest parsing tests (requirements.txt, pyproject.toml, poetry.lock, version edge cases)
-- `test/cve-2026-48710-badhost/transitive.test.js` — 7 transitive dependency tests (Tier 1/2, fastapi version gating, pin suppression)
-- `test/cve-2026-48710-badhost/codePattern.test.js` — 6 static code pattern tests (auth context, INFO fallthrough, scope suppression)
-- `test/cve-2026-48710-badhost/integration.test.js` — 4 integration tests (end-to-end composite findings, clean project, no Python files)
-- `test/trapdoor.test.js` — 40 TrapDoor campaign detection tests (D1–D9: campaign marker, payload fingerprint, publisher blocklist, Gist exfil, AI poisoning, lure name, crypto primitives, XOR key, credential validation)
-- `test/node-ipc.test.js` — 37 node-ipc compromise detection tests (D1–D11: version blocklist, tarball hash, CJS injection, payload hash, DNS C2 pattern, bootstrap resolver, DNS TXT exfil, runtime trigger, temp artifact, unauthorized publisher, blast radius)
-- `test/cli.test.js` — commander integration tests (help, version, scan, report, error handling)
-- `test/cli-lockfile.test.js` — scan-lockfile CLI options, yarn/pnpm/monorepo/watch tests
-
-### Need help?
-
-- 🔒 See [security policy](SECURITY.md) for vulnerability disclosure
-- 📖 Read the [project plan](docs/project-plan.md)
-- 🧬 Review the [attack taxonomy](docs/attack-taxonomy.md)
-- 🐛 Open an issue or PR
-
----
-
-## 📄 License
-
-Apache-2.0 core + Commons Clause.  
-See [`LICENSING.md`](LICENSING.md) for the exact boundary between free and premium features.
-
----
-
-## 👤 About the Maintainer
-
-**Roongrunchai Chongolnee** — creator and maintainer of `@lateos/npm-scan`. Certified security professional (CISSP, CEH, Cisco Security, AWS Cloud Practitioner) with a decade of infrastructure and application security experience at Philips. I built this tool to give the open-source community a practical, detector-driven defense against supply-chain malware — and I'm committed to keeping it transparent, community-owned, and continuously improved.
-
-[![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?style=flat-square&logo=linkedin)](https://www.linkedin.com/in/roongrunchai-chong-c-ab9742108/)
-[![GitHub](https://img.shields.io/badge/GitHub-lateos--ai-181717?style=flat-square&logo=github)](https://github.com/lateos-ai/npm-scan)
-
-Issues, ideas, and pull requests are always welcome — security is strongest when we collaborate.
-
----
-
-```
-@lateos/npm-scan — npm supply chain security scanner
-Copyright (C) 2026 Lateos
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-```
-
----
-
-**Scan your first package now:**
-
-```bash
-npx @lateos/npm-scan scan lodash
-```
+# @lateos/npm-scan
+
+[![npm version](https://img.shields.io/npm/v/@lateos/npm-scan?style=flat-square)](https://www.npmjs.com/package/@lateos/npm-scan)
+[![License](https://img.shields.io/badge/license-Apache%202.0%20%2B%20Commons%20Clause-blue?style=flat-square)](LICENSING.md)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)](package.json)
+[![Tests](https://img.shields.io/badge/tests-536%20passing-brightgreen?style=flat-square)](https://github.com/lateos-ai/npm-scan)
+[![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen?style=flat-square)](https://github.com/lateos-ai/npm-scan)
+[![Docker](https://img.shields.io/badge/docker-lateos%2Fnpm--scan-2496ED?style=flat-square&logo=docker)](https://hub.docker.com/r/lateos/npm-scan)
+[![Sigstore](https://img.shields.io/static/v1?label=Sigstore&message=Provenance&color=green&style=flat-square&logo=sigstore)](https://github.com/lateos-ai/npm-scan/actions/workflows/publish.yml)
+
+[![中文](https://img.shields.io/badge/lang-zh--CN-red?style=flat-square)](https://github.com/lateos-ai/npm-scan/blob/main/README.zh.md)
+[![日本語](https://img.shields.io/badge/lang-ja-purple?style=flat-square)](https://github.com/lateos-ai/npm-scan/blob/main/README.ja.md)
+[![Français](https://img.shields.io/badge/lang-fr-orange?style=flat-square)](https://github.com/lateos-ai/npm-scan/blob/main/README.fr.md)
+[![Deutsch](https://img.shields.io/badge/lang-de-green?style=flat-square)](https://github.com/lateos-ai/npm-scan/blob/main/README.de.md)
+
+**Modern supply chain security for the npm ecosystem.**
+Static + behavioral analysis that catches what npm audit, Snyk, and Socket miss — obfuscated payloads, credential stealers, conditional triggers, sandbox evasion, and worm-like propagation.
+
+---
+
+## 📌 The Problem
+
+The 2025–2026 wave of npm supply chain attacks proved that traditional tooling is no longer enough.
+
+Attackers have moved past simple typosquatting. They now ship **obfuscated preinstall hooks**, **credential harvesters hidden behind environment detection**, **dormant backdoors with time-based activation**, and **worm-style transitive propagation** that spreads through peer dependencies.
+
+A growing attack vector is **HuggingFace org impersonation** — packages that masquerade as legitimate HF model repositories (e.g., `0penai/gpt2` instead of `openai/gpt2`) to trick users into downloading malicious model artifacts during CI/CD pipelines, often bundled with suspicious binaries (`.exe`, `.dll`) in model repos that deep-learned tools trust by default.
+
+The **Megalodon campaign** (2026) alone compromised 5,500+ repositories via fake GitHub PRs, malicious workflow injection, and cloud credential exfiltration — all coordinated through a single actor automating the entire kill chain. **@lateos/npm-scan** now detects artifacts of this campaign out of the box.
+
+The **Mini Shai-Hulud worm campaign** (May 2026) hit the npm ecosystem in three waves — TanStack CI/CD hijack (84 artifacts in 6 minutes), AntV/atool maintainer compromise (600+ malicious versions across 300+ packages), and Nx Console VS Code extension poisoning (CVE-2026-48027) — all using ctf-scramble-v2 obfuscation, daemonized persistence with CI environment checks, geographic killswitches targeting sanctioned regions, and GitHub C2 dead-drop channels for token recovery. **@lateos/npm-scan** now detects all 10 Mini Shai-Hulud signals across two detector suites.
+
+The **TrapDoor campaign** (May 2026) spans npm, PyPI, and Crates.io — 34 malicious packages, 384+ versions attributed to a single publisher, targeting crypto, DeFi, Solana, and AI developers with Fernet + ECDH encrypted payloads, AI context poisoning via zero-width Unicode injection in `.cursorrules`/`CLAUDE.md`, and credential live-validation against AWS STS and GitHub API before exfiltration. **@lateos/npm-scan** now detects all 9 TrapDoor signals.
+
+The **node-ipc compromise** (May 14, 2026) weaponized an expired maintainer email domain to hijack one of npm's most depended-upon packages (822K weekly downloads). Three malicious versions (9.1.6, 9.2.3, 12.0.1) delivered an 80KB credential stealer via DNS TXT tunneling — no HTTP, no postinstall hook, invisible to HTTP-layer firewalls. **@lateos/npm-scan** now detects all 11 node-ipc compromise signals.
+
+The **Mass Typosquatting campaign (vpmdhaj)** (May 2026) weaponized the `vpmdhaj` npm maintainer account to publish 14 typosquatted packages in a 4-hour window — targeting AWS/CI/CD environments with preinstall stagers (`setup.mjs`, `stager.js`), Bun runtime abuse, and cloud credential exfiltration (AWS IMDSv2, ECS task roles, Vault, GitHub tokens). **@lateos/npm-scan** now detects all 3 typosquatting campaign signals.
+
+The **Axios Registry Poisoning campaign** (May 2026) compromised the npm registry's axios package metadata to publish `axios@1.14.1` and `axios@0.30.4` with injected dependencies (`plain-crypto-js`) containing cross-platform RAT payloads with C2 callbacks, process injection, and system persistence. **@lateos/npm-scan** now detects all 3 axios poisoning signals.
+
+Critical infrastructure vulnerabilities in the Python ecosystem are also in scope. The **BadHost (CVE-2026-48710)** vulnerability in Starlette < 1.0.1 enables authentication bypass via unvalidated HTTP Host header injection, affecting FastAPI, vLLM, LiteLLM, MCP servers, and any project using Starlette transitively — now detected across Python manifests, transitive dependency chains, and source code patterns in a single scan.
+
+**npm audit** checks known CVEs. **Snyk** scans for vulnerabilities. **Socket** looks at package behavior. None of them were designed for the generation of attacks that emerged in 2025 — attacks that look benign until they reach production.
+
+**@lateos/npm-scan** was built for this moment.
+
+---
+
+## 🔬 Why @lateos/npm-scan?
+
+| Capability | npm audit | Snyk | Socket | **@lateos/npm-scan** |
+|---|---|---|---|---|
+| Known CVE matching | ✅ | ✅ | ❌ | ✅ |
+| Static analysis | ❌ | ✅ | ✅ | ✅ |
+| Obfuscated payload detection | ❌ | ❌ | ❌ | ✅ |
+| AST-level heuristic analysis | ❌ | ❌ | ❌ | ✅ |
+| Runtime behavioral sandbox | ❌ | ❌ | ✅ | ✅ |
+| Conditional trigger detection (ATK-009) | ❌ | ❌ | ❌ | ✅ |
+| Sandbox evasion detection (ATK-010) | ❌ | ❌ | ❌ | ✅ |
+| Transitive worm propagation (ATK-011) | ❌ | ❌ | ❌ | ✅ |
+| Campaign detection (Megalodon CI/CD) | ❌ | ❌ | ❌ | ✅ |
+| Worm campaign detection (Mini Shai-Hulud Wave 1–3) | ❌ | ❌ | ❌ | ✅ |
+| HF model repo impersonation + README clone | ❌ | ❌ | ❌ | ✅ |
+| VS Code extension supply chain scan (--vsix) | ❌ | ❌ | ❌ | ✅ |
+| Python vulnerability detection (CVE-2026-48710 BadHost) | ❌ | ❌ | ❌ | ✅ |
+| Cross-ecosystem attack detection (TrapDoor) | ❌ | ❌ | ❌ | ✅ |
+| Expired-domain hijack detection (node-ipc) | ❌ | ❌ | ❌ | ✅ |
+| Malware obfuscation detection (ctf-scramble-v2) | ❌ | ❌ | ❌ | ✅ |
+| Mass typosquatting campaign (vpmdhaj maintainer) | ❌ | ❌ | ❌ | ✅ |
+| Registry poisoning detection (axios fake versions) | ❌ | ❌ | ❌ | ✅ |
+| Attack taxonomy (ATK series) | ❌ | ❌ | ❌ | ✅ |
+| SBOM output (CycloneDX + SPDX) | ❌ | ✅ | ❌ | ✅ |
+| SARIF v2.1 (GitHub Code Scanning) | ❌ | ❌ | ❌ | ✅ |
+| NIST 800-161 compliance reporting | ❌ | ❌ | ❌ | ✅ |
+| EU CRA compliance reporting | ❌ | ❌ | ❌ | ✅ |
+| SIEM export (CEF / ECS / Sentinel / QRadar) | ❌ | ❌ | ❌ | ✅ |
+| Runs entirely locally — no telemetry | ✅ | ❌ | ❌ | ✅ |
+| Policy-as-code (YAML allowlists) | ❌ | ❌ | ❌ | ✅ |
+
+> **Privacy first.** All scanning happens on your machine. No code leaves your environment. No telemetry. No cloud dependency.
+
+---
+
+## ✨ Key Features
+
+| Icon | Feature | Description |
+|------|---------|-------------|
+| 🕵️ | **Heuristic static analysis** | AST-level inspection catches obfuscation, eval chains, env probing, and suspicious lifecycle scripts that regex-based tools miss |
+| 🧠 | **Behavioral detection** | Identifies conditional triggers (time-based, CI-aware), sandbox evasion, and dormant activation patterns |
+| 🧬 | **ATK attack taxonomy** | 11 classified attack types with NIST 800-161 mappings — versioned, documented, and PR-able |
+| 🪱 | **Worm campaign detection** | Mini Shai-Hulud — 6 sub-checks detecting burst publish, sibling compromise, SLSA attestation mismatch, publisher drift, IOC match, and token exfil across 3 waves (TanStack, AntV/atool, Nx Console) |
+| 🧩 | **VSIX extension scanning** | `npm-scan scan --vsix nrwl.angular-console` — detects VS Code Marketplace supply chain attacks: burst publish, publisher anomaly, activation event risk, orphan commit fetch, known IOC, and exfil patterns (Nx Console 18.95.0 CVE-2026-48027) |
+| 🐍 | **Python vulnerability detection** | CVE-2026-48710 (BadHost) — Starlette Host header injection across 6 Python manifest formats, 15 transitive downstream packages (fastapi, vllm, litellm, MCP), and static `request.url.path` code pattern analysis with `scope["path"]` suppression |
+| 🪤 | **Cross-ecosystem attack detection** | TrapDoor — 9 sub-checks: campaign marker P-2024-001, trap-core.js payload fingerprint, publisher blocklist asdxzxc, Gist-based credential exfil, AI config zero-width Unicode poisoning, crypto/DeFi lure name heuristic, Fernet+ECDH encryption, XOR key cargo-build-helper-2026, STS/GitHub API credential validation |
+| 📡 | **Expired-domain hijack detection** | node-ipc compromise — version blocklist (9.1.6/9.2.3/12.0.1), tarball SHA-256 verification, CJS vs ESM size anomaly with IIFE injection, DNS-over-non-standard-port C2, bootstrap resolver sh.azurestaticprovider.net, DNS TXT exfil zone bt.node.js, setImmediate() runtime trigger, ~/nt-*/ staging artifacts, unauthorized publisher atiertant, lockfile blast-radius with safe pin recommendations |
+| ☣️ | **Malware obfuscation detection** | ctf-scramble-v2 detection — scans package dist/lib for known malware obfuscation patterns (ctf-scramble-v2, ctf-scramble-v3), halts analysis immediately with max severity CRITICAL stop condition |
+| 🎭 | **Mass typosquatting campaign detection** | vpmdhaj maintainer blocklist with stop condition, levenshtein-based typosquat detection (opensearch-setup, env-config-manager), preinstall stager identification (setup.mjs, stager.js, Bun runner), AWS ECS/Vault/GitHub credential exfiltration patterns |
+| ☠️ | **Registry poisoning detection** | Axios version blocklist (1.14.1/0.30.4) with stop condition, decoy dependency discovery (plain-crypto-js), cross-platform RAT payload detection (DLL injection, launchd/systemd/cron persistence, PowerShell IEX, C2 callbacks) |
+| 🔏 | **Provenance audit trail** | Aureus-Elicitor v1.7 framework — HMAC-SHA256 signed detection manifests, content-hash verified audit trails, rule provenance URLs, campaign source attribution. Every finding includes cryptographically verifiable provenance metadata |
+| 📦 | **SBOM generation** | CycloneDX 1.5 and SPDX 2.3 with findings embedded as vulnerabilities |
+| 🔍 | **SARIF output** | GitHub Advanced Security / CodeQL compatible SARIF v2.1 — shows findings directly in Security tab |
+| 🧾 | **Compliance reporting** | NIST SP 800-161 traceability matrix + EU Cyber Resilience Act mapping (free tier) |
+| 🔌 | **SIEM export** | Splunk CEF, Elastic ECS, Microsoft Sentinel, IBM QRadar formats (premium) |
+| 📜 | **Policy-as-code** | YAML/JSON policy engine with allowlists, severity overrides, suppressions, and fail-on thresholds |
+| 🐳 | **Docker + GitHub Action** | Multi-arch images, one-command Compose pipeline, PR scan action |
+| 🛡️ | **Zero telemetry** | No data leaves your machine. No cloud. No callbacks. |
+| 💾 | **Local scan history** | SQLite-backed persistence, zero external dependencies |
+| 🪝 | **Pre-commit hook** | Block threats before commit — one-liner install, scans `package-lock.json` changes |
+| 🤖 | **HF impersonation detection** | Detects typosquatted HuggingFace orgs (Jaro-Winkler), README clones (SimHash), artifact mismatches (`.exe` in model repos), and new-org amplifier — with lazy two-stage evaluation, zero network in Stage 1 |
+| 📎 | **Yarn + pnpm support** | `scan-lockfile` parses `yarn.lock` and `pnpm-lock.yaml` alongside `package-lock.json` |
+
+---
+
+## ⚡ Quick Start
+
+```bash
+# Install globally
+npm install -g @lateos/npm-scan
+
+# Scan a single package
+npm-scan scan lodash
+
+# Scan your lockfile
+npm-scan scan-lockfile
+
+# View latest scans
+npm-scan report
+```
+
+**No install? No problem:**
+
+```bash
+npx @lateos/npm-scan scan commander
+```
+
+---
+
+## 🐳 Run @lateos/npm-scan anywhere with Docker — zero installation
+
+```bash
+# Pull and run a single scan — no Node.js or npm required
+docker run --rm lateos/npm-scan:cli scan lodash
+
+# Full pipeline with persistent storage and Compose
+docker compose --profile pipeline up -d
+```
+
+No Node.js. No `npm install`. No global packages. Works on any system with Docker — CI servers, air-gapped environments, Kubernetes clusters. Multi-arch images for `linux/amd64` and `linux/arm64`.
+
+---
+
+## 🛡️ Government & SOC 2 Ready
+
+| Feature | SOC 2 Controls | NIST 800-161 | STIG/FedRAMP Alignment |
+|---------|-------|--------------|--------------|
+| Audit logs (--audit-log) | CC6.8 | AU-2 | ✓ |
+| FIPS crypto (--fips) | CC6.1 | SC-13 | ✓ |
+| STIG report (--stig) | CC7.3 | RA-5 | ✓ |
+| Offline cache (--cache-dir) | A1.2 | SC-8 | ✓ |
+| Sigstore provenance | CC6.2 | SI-7 | ✓ |
+| SBOM (SPDX/CycloneDX) | CC7.4 | SA-10 | ✓ |
+
+```bash
+# Air-gapped scan with full compliance
+npm-scan scan-lockfile --cache-dir /offline/cache --audit-log /var/log/npm-scan.audit --fips
+npm-scan report --stig
+```
+
+[![SOC 2 Ready](https://img.shields.io/badge/SOC%202-Ready-green?style=flat-square&logo=aicpa)](https://www.aicpa.org/interestareas/frc/assuranceadvisoryservices/sorhome.html#soc2)
+[![FedRAMP Aligned](https://img.shields.io/badge/FedRAMP-Aligned-blue?style=flat-square&logo=fedramp)](https://fedramp.gov/baselines/)
+
+---
+
+## ☁️ BYOC — Bring Your Own Cloud
+
+Deploy npm-scan in your VPC with full data sovereignty. No data leaves your infrastructure.
+
+| Feature | Description |
+|---------|-------------|
+| **Self-hosted** | Run on EKS/GKE/AKS in your AWS/Azure/GCP account |
+| **SIEM Export** | CEF/ECS/Sentinel/QRadar to your existing SIEM |
+| **SSO/OIDC** | SAML/OIDC integration with your identity provider |
+| **PDF Reports** | Generate NIST-compliant PDF reports locally |
+| **External DB** | Connect to your existing PostgreSQL/Redis |
+
+```bash
+# Deploy to your VPC with Helm
+git clone https://github.com/lateos-ai/npm-scan.git
+cd npm-scan/deploy/helm
+helm install npm-scan -f values.byoc.yaml .
+
+# BYOC values example (see values.byoc.yaml)
+premium:
+  enabled: true
+  edition: enterprise
+  byoc:
+    enabled: true
+    cloudProvider: aws
+    vpcId: vpc-xxx
+    region: us-east-1
+```
+
+**Pricing**: Enterprise license $10k/yr — self-supported (docs + GitHub issues).
+
+---
+
+## 📖 Usage Examples
+
+### Scan a single package
+
+```bash
+# Default JSON output with all findings
+npm-scan scan axios
+
+# Generate an SBOM alongside the scan
+npm-scan scan express --sbom             # CycloneDX JSON
+npm-scan scan express --sbom xml         # CycloneDX XML
+npm-scan scan express --sbom spdx        # SPDX 2.3
+
+# Apply a YAML policy
+npm-scan scan some-package --policy .npm-scan.yml
+
+# Scan a local tarball (no registry fetch needed)
+npm-scan scan --file path/to/malicious-package.tgz
+
+# Scan a VS Code extension for Marketplace supply chain attacks
+npm-scan scan --vsix nrwl.angular-console
+
+# Scan a package AND a VSIX extension together (findings merge)
+npm-scan scan lodash --vsix nrwl.angular-console
+```
+
+### Scan a lockfile
+
+```bash
+# Scan a single package
+npm-scan scan lodash
+
+# Scan your lockfile
+npm-scan scan-lockfile
+
+# Scan a VS Code extension for supply chain threats
+npm-scan scan --vsix nrwl.angular-console
+
+# View latest scans
+npm-scan report
+```
+
+### Generate reports
+
+```bash
+# List all recent scans
+npm-scan report
+
+# View a specific scan
+npm-scan report -i 42
+
+# Generate an HTML report (free) with full findings + NIST table
+npm-scan report -i 42 --html
+
+# Print NIST 800-161 compliance table
+npm-scan report -i 42 --nist
+
+# Print EU CRA compliance table
+npm-scan report --cra
+
+# CSV export for Excel / Sheets (audit-ready)
+npm-scan report --csv risks.csv
+npm-scan scan lodash --csv          # CSV to stdout
+
+# Text report (free)
+npm-scan report --text
+
+# PDF report (premium)
+npm-scan report --pdf --license-key <key>
+
+# SIEM export (premium)
+npm-scan report --siem cef        # Splunk CEF
+npm-scan report --siem ecs        # Elastic ECS
+npm-scan report --siem sentinel   # Microsoft Sentinel
+npm-scan report --siem qradar     # IBM QRadar
+
+# Combine all scans into a single report
+npm-scan report --html            # all scans
+npm-scan report --pdf             # all scans (premium)
+```
+
+---
+
+## 🧬 Detection Capabilities (ATK Taxonomy)
+
+| ID | Attack Class | Detection Method | Severity | NIST 800-161 |
+|---|---|---|---|---|
+| **ATK-001** | Malicious lifecycle scripts (`preinstall`, `postinstall`, `install`) | Static | 🔴 high | SR-3.1 |
+| **ATK-002** | Obfuscated payload delivery (hex, base64, eval chains) | Static | 🟠 medium | SR-4.2 |
+| **ATK-003** | Credential harvesting (env vars, .npmrc, SSH keys) | Static + Dynamic | 🔴 high | SR-5.3 |
+| **ATK-004** | Persistence via editor/config dirs (.vscode, .claude, .cursor) | Static | 🔴 high | SR-6.4 |
+| **ATK-005** | Network exfiltration (GitHub API, DNS tunneling, HTTP C2) | Static + Dynamic | ⚫ critical | SR-7.5 |
+| **ATK-006** | Dependency confusion / namespace squatting | Static (lockfile) | 🟠 medium | SR-2.2 |
+| **ATK-007** | Typosquatting (edit-distance matching) | Static | 🟢 low | SR-2.1 |
+| **ATK-008** | Tarball tampering (published ≠ source) | Static | 🔴 high | SR-8.1 |
+| **ATK-009** | Conditional/dormant triggers (CI detection, time-based) | Behavioral | 🔴 high | SR-9.2 |
+| **ATK-010** | Sandbox evasion / anti-analysis | Behavioral | 🟠 medium | SR-10.3 |
+| **ATK-011** | Transitive propagation (worm-style lateral spread) | Behavioral | 🔴 high | SR-11.4 |
+| **MEGALODON** | Megalodon CI/CD campaign — workflow C2 exfil, credential harvest, publish velocity spike, publisher drift | Static + Registry | ⚫ critical | SR-3.1, SR-7.5 |
+| **HF_IMPERSONATION** | HuggingFace org spoof detection — Jaro-Winkler similarity against 15 known-good orgs, SimHash README clone detection, artifact mismatch (`.exe`/`.dll` in model repos), postinstall escalation, new-org amplifier | Static + Network (Stage 2) | 🔴 high / ⚫ critical | SR-2.1 |
+| **MINI_SHAI_HULUD** | Mini Shai-Hulud worm campaign — burst publish velocity (≥3 versions/30 min), co-temporal sibling compromise, SLSA attestation mismatch (sub-60s gap, first-ever, builder mismatch), publisher drift (<10 min account change), IOC match (scope/sha512/publisher from seed file), token exfil (NPM_TOKEN/.npmrc/atob patterns), Nx Console downstream detection | Static + Registry | 🔴 high / ⚫ critical | SR-3.1, SR-7.5 |
+| **VSIX_SCAN** | VS Code extension supply chain scan — burst publish (≥2 versions/30 min, hot-pull <20 min), publisher anomaly (account substitution, new-account on high-install ext, 15-min add+publish), activation event risk (onStartupFinished→HIGH, *→CRITICAL, escalation on shell keywords), orphan commit fetch (GitHub API SHA refs, npx git URL, MCP-disguised exfil, Bun install), known IOC (extensionId/publisherAccount/commit hash from seed), exfil patterns (cred paths, DNS tunneling, AES+RSA, anti-analysis, Bun APIs) | Static + Registry | 🟠 medium / 🔴 high / ⚫ critical | SR-3.1, SR-5.3 |
+| **CVE-2026-48710** | BadHost — Starlette authentication bypass via Host header injection (CVE-2026-48710, CVSS 7.0). Python dependency version detection (requirements.txt, pyproject.toml, poetry.lock, Pipfile, setup.py/cfg), transitive heuristic (15 known downstream packages: fastapi, vllm, litellm, MCP servers, etc.), static code pattern scan for dangerous `request.url.path` usage in auth/middleware context with `request.scope["path"]` suppression | Static + Registry | 🔴 high / 🟠 medium / ℹ️ info | SR-3.1, SR-5.3 |
+| **TRAPDOOR** | TrapDoor cross-ecosystem attack — campaign marker P-2024-001 in files, shared payload trap-core.js filename/48,485-byte fingerprint, publisher blocklist asdxzxc, Gist-based credential exfil (ddjidd564.github.io + credential paths), AI context poisoning via zero-width Unicode in .cursorrules/CLAUDE.md, crypto/DeFi lure name heuristic (<30 days), Fernet+ECDH crypto primitives in postinstall, XOR key cargo-build-helper-2026 in lockfiles, STS/GitHub API credential validation in postinstall | Static + Registry | 🟠 medium / 🔴 high / ⚫ critical | SR-3.1, SR-5.3, SR-7.5 |
+| **NODE_IPC_COMPROMISE** | node-ipc supply chain compromise (May 14, 2026) — version blocklist (9.1.6/9.2.3/12.0.1) with safe pins, tarball SHA-256 verification, CJS payload IIFE injection detection (CJS>ESM size differential), injected payload hash match, DNS-over-non-standard-port C2 (setServers + custom resolver), bootstrap resolver sh.azurestaticprovider.net + C2 IP 37.16.75.69, DNS TXT exfiltration zone bt.node.js, setImmediate() runtime trigger, ~/nt-*/ staging artifact detection, unauthorized publisher atiertant, lockfile blast-radius detection with pin recommendations | Static + Registry | ⚫ critical | SR-3.1, SR-5.3, SR-7.5 |
+| **MSH_SUPPLEMENT** | Mini Shai-Hulud supplement — ctf-scramble-v2 obfuscation (HALT on match), daemonization persistence (spawn detached, systemd, cron, launchd, Task Scheduler), geographic killswitch detection (ru_RU/be_BY locale checks via process.env.LANG/LC_ALL/Intl.DateTimeFormat), C2 dead-drop indicators (OhNoWhatsGoingOnWithGitHub keyword, GitHub commit scraping + token exfiltration co-occurrence) | Static + Behavioral | ⚫ critical | SR-3.1, SR-7.5, SR-9.2 |
+| **TYPOSQUAT_VPMDHAJ** | Mass Typosquatting campaign (vpmdhaj) — maintainer blocklist (HALT on match), vpmdhaj-* namespace prefix detection, levenshtein typosquat matching vs popular packages, preinstall stager identification (setup.mjs/stager.js/bun run with generation tracking), cloud credential exfiltration (AWS IMDSv2, ECS task role tokens, Vault credentials, GITHUB_TOKEN/GH_TOKEN with HTTP exfil) | Static + Registry | ⚫ critical | SR-2.1, SR-3.1, SR-5.3 |
+| **AXIOS_POISONING** | Axios Registry Poisoning — version blocklist (1.14.1/0.30.4, HALT on match), decoy dependency injection (plain-crypto-js), crypto-dependency heuristic in non-crypto packages, cross-platform RAT payload detection (PowerShell IEX, launchd, systemd, cron, DLL/LoadLibrary, CreateRemoteThread, binary drops to temp dirs, C2 callbacks) | Static + Behavioral | ⚫ critical | SR-3.1, SR-5.3, SR-7.5 |
+
+> **How evasive attacks are caught:** ATK-009 detects packages that check `process.env.CI`, probe hostnames, or use time-based activation. ATK-010 flags `debugger` statements, `os.hostname()` probes, and env fingerprinting. ATK-011 traces peer dependency graphs to detect worm-like propagation patterns.  
+> **MEGALODON** campaign detection analyzes bundled `.github/workflows/` files for C2 co-occurrence and base64 decode chains, scans tarball files for credential + outbound network patterns, detects version publish velocity spikes via npm registry metadata, and identifies publisher account drift — all without any network calls beyond the initial package fetch.  
+> **HF_IMPERSONATION** detection uses a lazy two-stage evaluation: Stage 1 scans `package.json` scripts and JS/TS sources for HuggingFace references (URLs, `from_pretrained()`, `hub.download()`) and runs Jaro-Winkler similarity against 15 known-good HF orgs — zero network. If spoofs are found, Stage 2 fetches the HF model API, computes SimHash of both READMEs for clone detection, validates artifact type consistency (e.g., `transformers` library with `.exe` files is flagged as critical), applies a new-org amplifier (<30 days), and escalates when the reference appears in a lifecycle script.  
+> **MINI_SHAI_HULUD** worm campaign detection uses a lazy two-stage evaluation: Stage 1 runs burst velocity, publisher drift, IOC, and token exfil checks (in-memory, no network). If burst triggers, Stage 2 queries npm attestation endpoints for SLSA anomalies and fetches sibling package registry metadata for co-temporal burst detection. Composite finding includes wave attribution (wave1-tanstack, wave2-antv, wave3-nx-console) and critical severity when SLSA or IOC match. NX_CONSOLE_DOWNSTREAM (D7) flags npm packages with `@nx/*` dependencies and checks for `nrwl.angular-console` in `.vscode/extensions.json`.  
+> **VSIX_SCAN** extension scanning wraps both VS Code Marketplace and Open VSX registries with rate-limited (10 req/min), cached (5 min TTL) API clients. All 6 detectors run asynchronously and aggregate into a single composite `VSIX_SCAN` finding. Zero extension code is executed — all analysis is static regex/text-pattern matching. No Bun installation required for Bun pattern detection.  
+> **CVE-2026-48710 (BadHost)** detection uses three independent layers: Layer 1 parses 6 Python manifest formats (requirements.txt, pyproject.toml, poetry.lock, Pipfile, setup.py, setup.cfg) with PEP 440 semver-aware version comparison. Layer 2 scans for 15 known Starlette-downstream packages with Tier 1 (HIGH confidence) and Tier 2 (MEDIUM confidence) transitive heuristics, suppressed by explicit `starlette >= 1.0.1` pin. Layer 3 performs function-boundary static analysis on `.py` files for `request.url.path` usage, escalating to MEDIUM severity in auth/middleware contexts and suppressing when `request.scope["path"]` is used in the same function.  
+> **TRAPDOOR** campaign detection runs 9 sub-detectors across all package files (README.md, package.json, .md, shell scripts, .cursorrules, CLAUDE.md) for the hardcoded marker P-2024-001, scans for trap-core.js by filename or exact 48,485-byte size, unconditionally blocks publisher asdxzxc, detects outbound references to ddjidd564.github.io or gist.github.com combined with credential-path patterns, scans .cursorrules and CLAUDE.md for zero-width Unicode characters (U+200B, U+200C, U+200D, U+FEFF), flags crypto/DeFi-themed packages <30 days old with no prior version history, detects simultaneous Fernet and ECDH/createECDH usage in postinstall JS, and identifies sts.amazonaws.com and api.github.com/user calls in postinstall hooks.  
+> **NODE_IPC_COMPROMISE** detection intercepts the expired-domain takeover attack across 11 dimensions: version blocklist with safe-pin recommendations (9.1.5 for 9.x, 12.0.0 for 12.x), tarball SHA-256 hash verification against known malicious hashes, CJS vs ESM size comparison with IIFE suffix pattern detection for injected payload identification, DNS resolver pattern analysis (dns.promises.Resolver + setServers with non-public IP + resolveTxt), bootstrap domain and C2 IP detection, resolveTxt() with bt.node.js zone references, setImmediate() runtime trigger detection, ~/nt-*/ staging artifact path identification, publisher account verification against unauthorized account atiertant, and lockfile scanning for compromised version resolution with safe-pin suggestions.  
+> **MSH_SUPPLEMENT** detection augments the existing Mini Shai-Hulud worm campaign with 4 additional sub-detectors: D1 scans all extracted JS files for `require('ctf-scramble-v2')` or `import 'ctf-scramble-v2'` patterns (including variant ctf-scramble-v3+) and returns a CRITICAL stop condition that halts all further scanning. D2 scans lifecycle scripts (preinstall/install/postinstall) for daemonization APIs (`daemon()`, `fork()`, `spawn({detached: true})`), persistence mechanisms (systemd unit files, crontab, launchd plists, Windows Task Scheduler), and CI environment guards (`!process.env.CI`, `process.env.CI === undefined`). D3 scans code for geographic locale checks targeting sanctioned regions (`ru_RU`, `be_BY`) via `process.env.LANG`, `process.env.LC_ALL`, and `Intl.DateTimeFormat().resolvedOptions().timeZone` with `process.exit(0)` silent termination. D4 detects C2 dead-drop indicators including the hardcoded `OhNoWhatsGoingOnWithGitHub` keyword and co-occurring GitHub token access + GitHub API commit scraping patterns. All sub-detectors produce provenance-attached findings with HMAC-SHA256 signed audit trails.
+> **TYPOSQUAT_VPMDHAJ** campaign detection uses 3 sub-detectors: D1 checks the npm registry metadata for the blocked maintainer `vpmdhaj` (CRITICAL stop condition), scans package names for the `vpmdhaj-*` prefix namespace, and runs levenshtein edit-distance matching against a blocklist of popular packages to detect typosquats (e.g., `env-config-manager` mimicking dotenv, `opensearch-setup` mimicking OpenSearch). D2 scans `package.json` for suspicious `preinstall` lifecycle hooks (unusual — most packages use postinstall), detects `setup.mjs`, `loader.js`, and `stager.js` entry points, and identifies Bun runtime abuse (`bun run stager.js`) as a stealthy loader technique. D3 scans all extracted files for cloud credential exfiltration patterns targeting AWS IMDSv2 (`169.254.169.254`), ECS task role tokens (`AWS_CONTAINER_AUTHORIZATION_TOKEN`, `AWS_CONTAINER_CREDENTIALS_FULL_URI`), HashiCorp Vault (`VAULT_ADDR`, `VAULT_TOKEN`), and GitHub Actions tokens (`GITHUB_TOKEN`, `GH_TOKEN`) combined with HTTP POST exfiltration or base64 obfuscation to attacker-controlled domains. All findings include provenance metadata with HMAC-SHA256 signed manifests.
+> **AXIOS_POISONING** campaign detection uses 3 sub-detectors: D1 checks the package name and version against a hardcoded blocklist of known-malicious axios versions (`1.14.1`, `0.30.4`) with a CRITICAL stop condition that halts all scanning on match. D2 scans axios `package.json` dependencies for injected decoy packages (`plain-crypto-js`), and applies a heuristic that flags crypto-related dependency additions in non-crypto packages as potentially malicious pre-staged decoys. D3 scans all files and lifecycle scripts for cross-platform RAT indicators: Windows (PowerShell `IEX`, `Invoke-Expression`, `cmd.exe`, binary `.exe` drops to temp dirs), macOS (launchd plist installation via `launchctl load/start`), Linux (systemd unit files, crontab persistence), process injection APIs (`CreateRemoteThread`, `VirtualAllocEx`, `LoadLibrary`/`dlopen`), and C2 network callbacks via HTTP/HTTPS/WebSocket to attacker-controlled servers. Only suspicious code patterns (curl, wget, fetch, exec, spawn, eval, etc.) in lifecycle hooks trigger D3 — legitimate build scripts are not flagged.
+> See [`docs/attack-taxonomy.md`](docs/attack-taxonomy.md) for full evasion surface documentation and PoC examples.
+
+---
+
+## 📊 Output & Reports
+
+### Formats
+
+| Format | Availability | Description |
+|--------|-------------|-------------|
+| JSON | ✅ Free | Structured machine-readable findings |
+| HTML | ✅ Free | Rich HTML report with NIST compliance table, severity badges, control matrix |
+| Text | ✅ Free | Clean terminal-friendly text report |
+| CycloneDX SBOM | ✅ Free | Industry-standard SBOM with findings as vulnerabilities |
+| SPDX SBOM | ✅ Free | SPDX 2.3 document format |
+| NIST 800-161 | ✅ Free | Control traceability matrix (SR-2.1 → SR-11.4) |
+| EU CRA | ✅ Free | Cyber Resilience Act article mapping |
+| PDF | 🔐 Premium | Multi-page PDF with title page, findings table, NIST compliance matrix |
+| Splunk CEF | 🔐 Premium | Common Event Format for Splunk ingestion |
+| Elastic ECS | 🔐 Premium | Elastic Common Schema format |
+| Microsoft Sentinel | 🔐 Premium | Sentinel-ready formatted output |
+| IBM QRadar | 🔐 Premium | QRadar DSM-ready format with QID mappings |
+
+### Sample output
+
+```json
+{
+  "scanId": 1,
+  "findings": [
+    {
+      "id": "ATK-003",
+      "severity": "high",
+      "title": "Credential harvesting",
+      "evidence": "process.env.NPM_TOKEN detected in postinstall.js:17"
+    }
+  ]
+}
+```
+
+---
+
+## ⚙️ Configuration & Advanced Usage
+
+### Policy-as-code
+
+Define allowlists, severity overrides, suppressions, and fail thresholds in a YAML file:
+
+```yaml
+# .npm-scan.yml
+allowlist:
+  - lodash
+  - chalk
+
+severity_overrides:
+  - id: ATK-001
+    severity: medium
+
+suppress:
+  - atk_id: ATK-009
+  - package: some-package
+
+fail_on: high
+```
+
+```bash
+npm-scan scan target --policy .npm-scan.yml
+```
+
+### Environment variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NPM_SCAN_LICENSE_KEY` | Premium / enterprise license key | — |
+| `NPM_SCAN_DATA_DIR` | Scan history directory | `./.npm-scan` |
+| `NPM_SCAN_LOG_LEVEL` | Log verbosity | `info` |
+| `NPM_SCAN_LICENSE_SECRET` | HMAC key for license generation/validation | `npm-scan-default-dev-key` |
+
+### IOC configuration
+
+Campaign detectors use seed IOC files for known-malicious fingerprints:
+
+| IOC File | Detector | Types |
+|----------|----------|-------|
+| `backend/detectors/mini-shai-hulud/iocs.json` | Mini Shai-Hulud (Waves 1–3) | `packageScope`, `publisherAccount`, `sha512`, `extensionId` |
+| `backend/detectors/trapdoor/iocs.json` | TrapDoor | `publisherAccount`, `campaignMarker`, `payloadFilename`, `payloadSize`, `xorKey`, `c2Domain`, `gistDomain` |
+| `backend/detectors/node-ipc-compromise/iocs.json` | node-ipc compromise | `publisherAccount`, `c2Domain`, `c2IP`, `exfilZone`, `payloadHash` |
+| `backend/detectors/msh-supplement/` | MSH Supplement | `obfuscationPattern`, `persistenceApi`, `targetedLocale`, `c2Keyword` |
+| `backend/detectors/typosquat-vpmdhaj/` | Typosquat vpmdhaj | `blockedMaintainer`, `typosquatTarget`, `loaderPattern`, `credTarget` |
+| `backend/detectors/axios-poisoning/` | Axios Poisoning | `blockedVersion`, `decoyDependency`, `ratPlatform`, `ratApi` |
+| `backend/vsix-scan/vsix-iocs.json` | VSIX extension scan | `extensionId`, `publisherAccount`, `orphanCommitHash` |
+
+IOC files follow a unified schema (`iocs: [{ type, value, ... }]`) and are loaded at module init. Update them from your threat intel feed to extend detection coverage without code changes.
+
+### Premium licensing
+
+Contact leo@lateos.ai for a premium/enterprise license key.
+
+```bash
+# Use it
+npm-scan scan target --license-key <key>
+npm-scan report --pdf --license-key <key>
+npm-scan report --siem cef --license-key <key>
+```
+
+---
+
+## 🔗 Integrations
+
+### GitHub Actions CI (for this repo)
+
+Every push and PR runs tests across Node 18, 20, and 22:
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm test
+    - run: npm run test:coverage
+    - run: node --test test/detectors-corpus.test.js
+    - run: npm run lint
+    - run: npm run build
+```
+
+### GitHub Action (for downstream users)
+
+Scan your project's `package-lock.json` on every PR — detects typosquats, obfuscated payloads, credential harvesters, and worm propagation before they reach production. **SARIF output shows findings directly in GitHub's Security tab (Code Scanning).**
+
+```yaml
+# .github/workflows/scan.yml
+name: npm-scan
+on:
+  pull_request:
+    paths:
+      - 'package-lock.json'
+      - '**/package.json'
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: lateos/npm-scan@v1
+      with:
+        scan-type: lockfile
+        sarif: results.sarif
+        fail-on: high
+    - name: Upload SARIF to Security tab
+      uses: github/codeql-action/upload-sarif@v3
+      with:
+        sarif_file: results.sarif
+```
+
+#### Action inputs
+
+| Input | Default | Description |
+|-------|---------|-------------|
+| `scan-type` | `lockfile` | `lockfile` to scan `package-lock.json` or `package` to scan a specific npm package |
+| `package` | — | Package name (required when `scan-type=package`) |
+| `fail-on` | `high` | Fail the workflow at this severity threshold: `none`, `low`, `medium`, `high`, `critical` |
+| `policy-file` | — | Path to a YAML/JSON policy file for allowlists, severity overrides, and suppressions |
+| `license-key` | — | Premium license key for SIEM export and PDF reports |
+| `siem-format` | — | SIEM output: `cef`, `ecs`, `sentinel`, `qradar` (premium) |
+| `sbom-format` | — | SBOM output: `json`, `xml`, `spdx` |
+
+#### Action outputs
+
+| Output | Description |
+|--------|-------------|
+| `findings-count` | Number of findings detected |
+| `scan-id` | Scan ID for later reference in reports |
+
+#### Example: scan a specific package with policy + SBOM
+
+```yaml
+- uses: lateos/npm-scan@v1
+  with:
+    scan-type: package
+    package: lodash
+    policy-file: .npm-scan.yml
+    sbom-format: spdx
+    fail-on: critical
+```
+
+#### Example: scan with SIEM export (premium)
+
+```yaml
+- uses: lateos/npm-scan@v1
+  with:
+    scan-type: lockfile
+    siem-format: cef
+    license-key: ${{ secrets.NPM_SCAN_LICENSE_KEY }}
+```
+
+### CI/CD pipeline
+
+Integrate directly into your existing pipeline without the composite action:
+
+```bash
+# Scan lockfile, fail build on high severity
+npm-scan scan-lockfile --policy .npm-scan.yml || exit 1
+
+# Scan a specific package, fail on critical only
+npm-scan scan lodash --policy .npm-scan.yml || exit 1
+
+# Generate SBOM as a build artifact
+npm-scan scan express --sbom spdx > express-sbom.spdx.json
+
+# Generate HTML compliance report in CI
+npm-scan report --html > report.html
+
+# Upload report as an artifact
+# uses: actions/upload-artifact@v4
+#   with:
+#     name: npm-scan-report
+#     path: report.html
+```
+
+### Docker
+
+See the [Docker quick-start section](#-run-lateosnpm-scan-anywhere-with-docker--zero-installation) above for pull commands, Compose pipeline, and multi-arch images.
+
+Scan your project's `package-lock.json` on every PR — detects typosquats, obfuscated payloads, credential harvesters, and worm propagation before they reach production:
+
+```yaml
+# .github/workflows/scan.yml
+name: npm-scan
+on:
+  pull_request:
+    paths:
+      - 'package-lock.json'
+      - '**/package.json'
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 20
+    - name: Scan lockfile
+      uses: lateos/npm-scan@v1
+      with:
+        scan-type: lockfile
+        fail-on: high
+```
+
+#### Action inputs
+
+| Input | Default | Description |
+|-------|---------|-------------|
+| `scan-type` | `lockfile` | `lockfile` to scan `package-lock.json` or `package` to scan a specific npm package |
+| `package` | — | Package name (required when `scan-type=package`) |
+| `fail-on` | `high` | Fail the workflow at this severity threshold: `none`, `low`, `medium`, `high`, `critical` |
+| `policy-file` | — | Path to a YAML/JSON policy file for allowlists, severity overrides, and suppressions |
+| `license-key` | — | Premium license key for SIEM export and PDF reports |
+| `siem-format` | — | SIEM output: `cef`, `ecs`, `sentinel`, `qradar` (premium) |
+| `sbom-format` | — | SBOM output: `json`, `xml`, `spdx` |
+
+#### Action outputs
+
+| Output | Description |
+|--------|-------------|
+| `findings-count` | Number of findings detected |
+| `scan-id` | Scan ID for later reference in reports |
+
+#### Example: scan a specific package with policy + SBOM
+
+```yaml
+- uses: lateos/npm-scan@v1
+  with:
+    scan-type: package
+    package: lodash
+    policy-file: .npm-scan.yml
+    sbom-format: spdx
+    fail-on: critical
+```
+
+#### Example: scan with SIEM export (premium)
+
+```yaml
+- uses: lateos/npm-scan@v1
+  with:
+    scan-type: lockfile
+    siem-format: cef
+    license-key: ${{ secrets.NPM_SCAN_LICENSE_KEY }}
+```
+
+### CI/CD pipeline
+
+Integrate directly into your existing pipeline without the composite action:
+
+```bash
+# Scan lockfile, fail build on high severity
+npm-scan scan-lockfile --policy .npm-scan.yml || exit 1
+
+# Scan a specific package, fail on critical only
+npm-scan scan lodash --policy .npm-scan.yml || exit 1
+
+# Generate SBOM as a build artifact
+npm-scan scan express --sbom spdx > express-sbom.spdx.json
+
+# Generate HTML compliance report in CI
+npm-scan report --html > report.html
+
+# Upload report as an artifact
+# uses: actions/upload-artifact@v4
+#   with:
+#     name: npm-scan-report
+#     path: report.html
+```
+
+### Pre-commit hook
+
+Block supply chain threats **before** they reach version control — no CI required.
+
+```bash
+# One-liner install (requires Node 18+, Git)
+npx husky@latest init && npm install && npx husky add .husky/pre-commit "npx lint-staged"
+```
+
+**What it does:** On every `git commit`, lint-staged detects staged changes to `package.json` or `package-lock.json` and runs `npm-scan scan-lockfile --fail-on high`. Commits are blocked if threats are found.
+
+```bash
+$ git commit -m "bump lodash"
+✔ Preparing lint-staged configuration...
+✔ Running tasks for staged package*.json files...
+✔ npm-scan scan-lockfile --fail-on high
+  🔴 ATK-003: Credential exfiltration (DNS lookup to credentialharvest.example.com)
+  🔴 ATK-007: Typosquat detected (lodash@7.7.7)
+  ⚠ Exiting with code 1 — threat(s) found
+
+npm scan • @lateos/npm-scan v0.11.6
+error: Command failed with exit code 1.
+```
+
+Add `--no-verify` to bypass for emergencies (`git commit -m "emergency fix" --no-verify`).
+
+### Docker
+
+See the [Docker quick-start section](#-run-lateosnpm-scan-anywhere-with-docker--zero-installation) above for pull commands, Compose pipeline, and multi-arch images.
+
+---
+
+## 🗺️ Roadmap & Enterprise Features
+
+### Free tier (shipped)
+
+- All 11 ATK detectors + **MEGALODON** CI/CD campaign detection (D1–D6) + **HF_IMPERSONATION** detector + **MINI_SHAI_HULUD** worm campaign (D1–D7, 3 waves, with **MSH_SUPPLEMENT** D1–D4 for obfuscation/persistence/geofence/C2) + **VSIX_SCAN** extension supply chain scan (6 detectors) + **CVE-2026-48710 (BadHost)** Python vulnerability detection (3 layers) + **TRAPDOOR** cross-ecosystem attack detection (9 rules) + **NODE_IPC_COMPROMISE** expired-domain hijack detection (11 rules) + **TYPOSQUAT_VPMDHAJ** mass typosquatting campaign (3 rules) + **AXIOS_POISONING** registry poisoning campaign (3 rules)
+- SBOM output (CycloneDX + SPDX)
+- HTML, text, and compliance reports (NIST + EU CRA)
+- Policy-as-code engine (YAML)
+- Local SQLite scan history
+- GitHub Action
+- Pre-commit hook (husky + lint-staged)
+- Docker images + Compose pipeline
+- Watch mode (--watch / --monorepo for auto-rescan)
+- VS Code extension scanning (--vsix flag with Marketplace + Open VSX registries)
+
+### Premium (🔐 license key)
+
+- PDF compliance reports with NIST traceability matrix
+- SIEM export (Splunk CEF, Elastic ECS, Microsoft Sentinel, IBM QRadar)
+- Dynamic sandbox (gVisor-based — ATK-008–010)
+- Reachability analysis (call graph filtering)
+
+### Enterprise (🏢 custom license)
+
+- SAML 2.0 SSO (Okta, Azure AD, OneLogin, Keycloak)
+- REST API + webhooks (FastAPI)
+- Team RBAC + audit logs
+- Helm chart for Kubernetes deployment
+- PostgreSQL backend for hosted/team tier
+- SLA-backed priority support
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions — especially new detectors, improved evasion resistance, and compliance templates.
+
+See [`docs/attack-taxonomy.md`](docs/attack-taxonomy.md) for the ATK governance process. Every new detector requires:
+
+1. A proof-of-concept sample
+2. A detection rule with tests
+3. False-positive analysis on top-500 npm packages
+4. NIST 800-161 control mapping
+
+### Testing
+
+The project uses the **Node.js native test runner** (`node:test` + `assert/strict`).
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests with verbose spec output
+npm run test:verbose
+
+# Run local malicious/clean corpus (no network needed)
+node --test test/detectors-corpus.test.js
+```
+
+**Test structure:**
+- `test/fixtures/mock-data.js` — shared mock scans, packages, and code snippets
+- `test/megalodon.test.js` — 30 Megalodon campaign detection tests (D1–D4 + aggregator + runAll integration)
+- `test/db.test.js` — database CRUD (save, query, persist)
+- `test/detectors-edge-cases.test.js` — per-detector boundary tests (no-ops, clean clears, severity)
+- `test/detectors-corpus.test.js` — 33 malicious + 50 clean tarball integration (offline)
+- `test/fetch.test.js` — tarball extraction, temp directory cleanup
+- `test/policy-edge-cases.test.js` — edge cases in suppress, override, load validation
+- `test/policy.test.js` — policy YAML/JSON load, apply, suppress, severity override tests
+- `test/report-snapshots.test.js` — HTML/text/CRA/PDF format assertions
+- `test/report.test.js` — SARIF, CSV, STIG, risk score format tests
+- `test/lockfile.test.js` — npm/yarn/pnpm parser, auto-detect, ATK-007/011 lockfile tests
+- `test/hf-impersonation.test.js` — 13 HF impersonation detection tests (no-ref, exact match, spoof, README clone, artifact mismatch, postinstall escalation, new-org tag)
+- `test/mini-shai-hulud.test.js` — 22 Mini Shai-Hulud worm campaign detection tests (burst, sibling, SLSA, maintainer, IOC, exfil, wave attribution)
+- `test/vsix-scan/burst-publish.test.js` — 4 VSIX burst publish tests (threshold, sub-threshold, hot-pull, Open VSX window)
+- `test/vsix-scan/publisher-anomaly.test.js` — 5 publisher anomaly tests (cross-namespace, new-account, add+publish, substitution, silent)
+- `test/vsix-scan/activation-event-risk.test.js` — 5 activation event risk tests (onStartupFinished, wildcard, escalation, first-time, silent)
+- `test/vsix-scan/orphan-commit-fetch.test.js` — 5 orphan commit tests (GitHub SHA, npx git, MCP exfil, Bun install, silent)
+- `test/vsix-scan/known-ioc.test.js` — 4 known IOC tests (extensionId, publisher window, outside window)
+- `test/vsix-scan/exfil-pattern.test.js` — 5 exfil pattern tests (creds, DNS tunnel, AES+RSA, anti-analysis, silent)
+- `test/vsix-scan/integration.test.js` — 4 integration tests (Nx Console CRITICAL, safe version clean, orphan commit, skipNetwork)
+- `test/cve-2026-48710-badhost/manifest.test.js` — 13 Python manifest parsing tests (requirements.txt, pyproject.toml, poetry.lock, version edge cases)
+- `test/cve-2026-48710-badhost/transitive.test.js` — 7 transitive dependency tests (Tier 1/2, fastapi version gating, pin suppression)
+- `test/cve-2026-48710-badhost/codePattern.test.js` — 6 static code pattern tests (auth context, INFO fallthrough, scope suppression)
+- `test/cve-2026-48710-badhost/integration.test.js` — 4 integration tests (end-to-end composite findings, clean project, no Python files)
+- `test/trapdoor.test.js` — 40 TrapDoor campaign detection tests (D1–D9: campaign marker, payload fingerprint, publisher blocklist, Gist exfil, AI poisoning, lure name, crypto primitives, XOR key, credential validation)
+- `test/node-ipc.test.js` — 37 node-ipc compromise detection tests (D1–D11: version blocklist, tarball hash, CJS injection, payload hash, DNS C2 pattern, bootstrap resolver, DNS TXT exfil, runtime trigger, temp artifact, unauthorized publisher, blast radius)
+- `test/msh-supplement.test.js` — 17 MSH supplement tests (ctf-scramble-v2 stop, daemonization, geo killswitch, C2 dead-drop, provenance, false positives)
+- `test/typosquat-vpmdhaj.test.js` — 16 typosquatting campaign tests (maintainer block, prefix detection, levenshtein, preinstall stagers, Bun loader, AWS/ECS/Vault/GitHub cred exfil)
+- `test/axios-poisoning.test.js` — 13 axios poisoning tests (version blocklist stop, decoy dependency, crypto heuristic, cross-platform RAT, C2 callback)
+- `test/cli.test.js` — commander integration tests (help, version, scan, report, error handling)
+- `test/cli-lockfile.test.js` — scan-lockfile CLI options, yarn/pnpm/monorepo/watch tests
+
+### Need help?
+
+- 🔒 See [security policy](SECURITY.md) for vulnerability disclosure
+- 📖 Read the [project plan](docs/project-plan.md)
+- 🧬 Review the [attack taxonomy](docs/attack-taxonomy.md)
+- 🐛 Open an issue or PR
+
+---
+
+## 📄 License
+
+Apache-2.0 core + Commons Clause.  
+See [`LICENSING.md`](LICENSING.md) for the exact boundary between free and premium features.
+
+---
+
+## 👤 About the Maintainer
+
+**Roongrunchai Chongolnee** — creator and maintainer of `@lateos/npm-scan`. Certified security professional (CISSP, CEH, Cisco Security, AWS Cloud Practitioner) with a decade of infrastructure and application security experience at Philips. I built this tool to give the open-source community a practical, detector-driven defense against supply-chain malware — and I'm committed to keeping it transparent, community-owned, and continuously improved.
+
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?style=flat-square&logo=linkedin)](https://www.linkedin.com/in/roongrunchai-chong-c-ab9742108/)
+[![GitHub](https://img.shields.io/badge/GitHub-lateos--ai-181717?style=flat-square&logo=github)](https://github.com/lateos-ai/npm-scan)
+
+Issues, ideas, and pull requests are always welcome — security is strongest when we collaborate.
+
+---
+
+```
+@lateos/npm-scan — npm supply chain security scanner
+Copyright (C) 2026 Lateos
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+```
+
+---
+
+**Scan your first package now:**
+
+```bash
+npx @lateos/npm-scan scan lodash
+```