fad-checker 2.2.0 → 2.2.2

package/README.md

@@ -9,9 +9,10 @@
 
 `fad-checker` scans **Maven**, **npm**, **Yarn**, **Composer (PHP)**, **PyPI (Python)**, **NuGet (C#/.NET)**, **Go**, **Ruby**, **vendored JavaScript** and **committed native binaries** in any source tree — multi-module, monorepo, polyglot, whatever you've got — and produces a single self-contained HTML report with CVE (prioritised by **EPSS + CISA KEV**), EOL, obsolete, outdated and **license** findings, plus per-ecosystem fix recipes. It also exports a **CycloneDX 1.6 SBOM** and a **CSAF 2.0 VEX**.
 
+
 🌐 **[Project site & docs →](https://n8tz.github.io/fad-checker/)**
 
-<p align="center"><img src="docs/assets/cli.png" alt="fad-checker terminal output — a [n/N] checklist warming each vulnerability database, then CVE findings coloured by severity" width="760"></p>
+<p align="center"><img src="docs/assets/cli.png" alt="fad-checker terminal output — a [n/N] checklist warming each vulnerability database, then CVE findings coloured by severity" height="760"></p>
 
 It runs against the source files alone. **No `mvn`, no `npm install`, no `composer install`, no `pip`, no `dotnet restore`, no Docker.** It reads `pom.xml`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `composer.lock`, `poetry.lock`/`Pipfile.lock`/`uv.lock`/`pdm.lock`/`pyproject.toml`/`requirements.txt`, and `packages.lock.json`/`*.csproj`/`*.fsproj`/`*.vbproj`/`packages.config` directly.
 
@@ -55,7 +56,7 @@ Exactly **one** runtime dependencies must be on PATH (or installed automatically
 | **4. EOL frameworks** | endoflife.date | Spring Boot 2.5, Hibernate 4.x, EOL JDKs, AngularJS, Laravel/Symfony, Django, .NET, etc. |
 | **5. Obsolete libraries** | curated list (Maven) + registry maintainer flags | log4j 1.x, jackson-mapper-asl, joda-time, …; npm `deprecated`, Composer `abandoned`, PyPI `yanked`/inactive, NuGet `deprecation` |
 | **6. Outdated libraries** | Maven Central + npm / Packagist / PyPI / NuGet registries | Available newer versions, with release dates |
-| **7. Licenses** | registry metadata + Maven POMs → SPDX policy | Each dep's license normalised to SPDX and classified; copyleft (GPL/AGPL/LGPL/MPL), proprietary and unknown flagged for review |
+| **7. Licenses** *(opt-in: `--licenses`)* | registry metadata + Maven POMs → SPDX policy | Each dep's license normalised to SPDX and classified; copyleft (GPL/AGPL/LGPL/MPL), proprietary and unknown flagged for review |
 | **8. Fix Recommendations** | computed | Per-ecosystem pin recipes: Maven `<dependencyManagement>`, npm `overrides`, yarn `resolutions`, `composer require`, `pip install`, `dotnet add package` |
 
 The HTML report opens in any browser, contains every detail (CVSS vectors, references, full descriptions, CPE configurations, via-paths for transitives) and ships a Word-compatible `.doc` twin. Every match carries a **composite priority** (KEV-exploited > EPSS likelihood > CVSS severity), and the run can additionally emit a **CycloneDX 1.6 SBOM** (`--report-sbom`, vulnerabilities inline) and a **CSAF 2.0 VEX** (`--report-csaf`) for downstream tooling.
@@ -104,6 +105,9 @@ fad-checker -s ./proj --no-all-libs --no-transitive
 # Fully offline (uses cached data only)
 fad-checker -s ./proj --offline
 
+# License + copyleft-policy chapter (off by default)
+fad-checker -s ./proj --licenses
+
 # Pick ecosystems — --ecosystem is a list: auto (default) | all | comma list
 fad-checker -s ./proj --ecosystem maven            # Maven only
 fad-checker -s ./proj --ecosystem maven,npm,pypi   # several
@@ -127,36 +131,22 @@ Run `fad-checker --help` for the full flag list.
 The console prints a summary; the full detail lives in the self-contained HTML/`.doc`:
 
 ```
+╭───────────────────────────────────────────────────╮
+│ fad-checker v2.2.1 · Autonomous Dependency Checker │
+╰───────────────────────────────────────────────────╯
 Executive Summary [CRITICAL] — 1708 dependencies scanned
   • 81 CVE in production deps (critical=5, high=53, medium=12, low=11)
-  • 32 CVE in dev/test deps
-  • 17 vulnerable vendored JS finding(s) (retire.js)
-  • 2 end-of-life frameworks
-  • 13 obsolete / deprecated libs
-  • 172 outdated libs
+  • 32 CVE in dev/test deps · 17 vulnerable vendored JS (retire.js)
+  • 2 EOL frameworks · 13 obsolete/deprecated · 172 outdated
   • 4 scan-completeness alerts — see chapter 0
-
-0. Warnings & scan-completeness (4)
-1. CVE Vulnerabilities — production (81)
-   1.a Maven (49)
-      1.a.0 All (49)
-      By pom.xml (14 files)
-         build/building/pom.xml (17)
-         services/api/pom.xml (17)
-         … 12 more
-   1.b npm (package-lock) (32)
-      1.b.0 All (32)
-      By package-lock.json (1 file)
-         web/package-lock.json (32)
-2. CVE in dev dependencies (32)
-3. Vendored JS scan — retire.js (17)
-4. End-of-Life Frameworks (2)
-5. Obsolete / Deprecated Libraries (13)
-6. Outdated Libraries (172)
-7. Fix Recommendations
 ```
 
-Each CVE row shows: severity badge · CVE / GHSA id · dep coord & version · which manifest file declares it · source(s) (CVEProject / OSV / NVD / Snyk / retire / fad) · fix-version · summary. Click a row for the full panel (CVSS vectors, NVD references categorised by type, transitive paths, CPE configurations).
+The HTML report organises this into chapters (0 Warnings, 1 CVE prod, 1B embedded JARs,
+1C native binaries, 1D vendored-JS inventory, 2 vendored-JS vulns, 3 dev CVE, 4 EOL,
+5 obsolete, 6 outdated, 7 Licenses *(opt-in)*, 8 Fix Recommendations), each grouped by
+ecosystem and manifest. Every CVE row carries: severity badge · CVE/GHSA id · coord &
+version · declaring manifest · source(s) · fix-version · priority (KEV/EPSS) — click for
+the full panel (CVSS vectors, references, transitive paths, CPE configs).
 
 ---
 
@@ -209,54 +199,17 @@ fad-checker --completion zsh  > ~/.zsh/completions/_fad-checker
 | Ruby | `Gemfile.lock` (`specs:`) | the lockfile |
 | Vendored JS / binaries | the committed `.js` / `.jar` / `.so` files themselves | n/a (read in place) |
 
-The rest of this section is the detail behind that table.
-
-- **Maven** — `pom.xml` files are parsed with xml2js. Property substitution (`${jackson.version}`), parent inheritance, local BOM imports (`<scope>import</scope>`) and every profile are resolved in-process. Transitive deps are walked by fetching child POMs from Maven Central (cached forever — POMs are immutable). When the project uses an **external BOM** (`spring-boot-dependencies` etc.), the deps whose version comes from that BOM can't be resolved without `mvn` itself — those are surfaced in chapter 0 as "unresolved-versions" so you know what's missing.
-- **npm / Yarn / pnpm** — `package-lock.json` (v1, v2, v3), `yarn.lock` (v1 + Berry/v2+, via `js-yaml`) and `pnpm-lock.yaml` (v5/v6/v9, via `js-yaml`) are parsed directly. Lockfiles already contain every transitive version. No `node_modules/` traversal, no `npm install`.
-- **Composer (PHP)** — `composer.lock` (`packages` + `packages-dev`) gives concrete + transitive versions; `composer.json` alone is best-effort.
-- **PyPI (Python)** — `poetry.lock` / `Pipfile.lock` / `uv.lock` / `pdm.lock` are parsed (TOML via `smol-toml`, or JSON); `pyproject.toml` (PEP 621 `[project]` + `[tool.poetry]`) and `requirements.txt` (following `-r`/`-c` includes recursively, with `-c` constraint pins applied to ranges) are best-effort on exact pins. Package names are PEP 503-normalised (`Flask-SQLAlchemy` → `flask-sqlalchemy`).
-- **NuGet (C#/.NET)** — `packages.lock.json` is authoritative; otherwise `*.csproj` / `*.fsproj` / `*.vbproj` `<PackageReference>` (resolving Central Package Management against `Directory.Packages.props`) and legacy `packages.config`. Ids are case-insensitive.
-- **Go** — `go.mod` `require` entries are the selected versions (full pruned graph on Go ≥1.17; `// indirect` → transitive), `go.sum` as fallback. OSV "Go" ecosystem for recall, the Go module proxy for outdated.
-- **Ruby** — `Gemfile.lock` `specs:` give the resolved gem set. OSV "RubyGems" for recall, the RubyGems API for outdated + licenses.
-- **Lockfile-first, best-effort fallback** — when a lockfile is present it wins. When it's absent, the loose manifest (`package.json` / `composer.json` / `pyproject.toml` / `requirements.txt` / `*.csproj`) is still parsed for its **pinned exact versions**, with ranges skipped and a `no-lockfile` warning in chapter 0 flagging the partial coverage.
-- **Vendored JavaScript** — `retire.js` shells out (with `--verbose`) and scans `.js` / `.min.js` files by signature. Two outputs: a full **inventory of every identified standalone lib** — jQuery, Bootstrap, Angular, PDF.js copies that no lockfile knows about, *vulnerable or not* (chapter 1D, a cyber-hygiene constat on unmanaged third-party code; `--no-vendored-js-inventory` to skip) — and the **vulnerable subset** with its CVEs/advisories (chapter 2).
-- **Embedded JARs** — committed `.jar` / `.war` / `.ear` archives are unzipped **in memory** (via `fflate` — nested fat-jar libs are recursed without ever touching disk, so there's no zip-slip risk) and each artifact's Maven coordinate is read from `META-INF/maven/.../pom.properties` (authoritative), then `MANIFEST.MF`, then the file name. Those coordinates run through the same CVE/OSV/NVD matching as declared deps but report in their own **Embedded binaries** chapter, grouped by containing archive. An archive whose coordinate can't be resolved is flagged in chapter 0 rather than scanned blindly. Auto when archives are present; disable with `--no-jars`. (Embedded coords don't trigger Maven Central transitive resolution — a fat-jar already ships its dependencies, which the recursion finds directly.)
-- **Committed native binaries** — `.dll` / `.exe` / `.so` / `.dylib` files are found by a magic-byte-confirmed walk (extension **and** PE/ELF/Mach-O signature must agree, so an image renamed `.so` or any asset is rejected), hashed (SHA-1 + SHA-256), then **identified by checksum** online: **deps.dev** query-by-hash returns the exact package coordinate (so the file is byte-identical to a published artifact → *pristine*, and ought to be a declared dependency), and **CIRCL hashlookup** recognises known OS/distro/CDN/NSRL files (→ *known-good*) plus a free `KnownMalicious` flag. Files no source knows are flagged *unknown*; a filename that disagrees with the resolved identity is flagged *name≠checksum*. Reported in their own **Unmanaged / vendored binaries** chapter (1C) and the JSON export. Cached + `--offline`-aware; disable with `--no-binaries`. No malware/AV lane and no binary-metadata parsing — identity is hash-lookup, integrity is hash-comparison.
-- **CVE data** — three independent sources merged:
-  - **CVEProject** (the canonical `cvelistV5` bundle, filtered to Maven-relevant entries)
-  - **OSV.dev** (Google + GitHub Security Lab, multi-ecosystem)
-  - **NVD** (official NIST records, used for enrichment: full CVSS, references, CPE configurations)
-- **CPE refinement** — once a CVE is matched, its NVD CPE configurations are checked against the dep version range. A match outside the vulnerable range is flagged `cpeFiltered: true` (likely false positive). A curated `data/cpe-coord-map.json` maps CPE `vendor:product` to Maven `g:a` (60+ entries seeded: log4j, jackson, spring, tomcat, jetty, netty, …).
-- **Prioritization** — each matched CVE is enriched with **EPSS** (FIRST.org exploit-prediction percentile) and **CISA KEV** (known-exploited catalogue), then scored: KEV (exploited in the wild) outranks EPSS-weighted CVSS. The report sorts by this composite priority and badges KEV/EPSS.
-- **Licenses** — each dependency's license is resolved (registry metadata, no extra request; Maven from cached POMs), normalised to SPDX and classified against a copyleft policy (`data/license-policy.json`) — permissive / weak / strong / network copyleft / proprietary / unknown.
-- **Unified outputs** — one `--report-<type>` flag per output, each with an OPTIONAL path (omit it → a default name under `--report-output`): `--report-html`, `--report-doc`, plus the machine-readable `--report-sbom` (**CycloneDX 1.6**, vulnerabilities inline / VDR), `--report-csaf` (**CSAF 2.0 VEX**), `--report-json` (flat findings, diff-friendly) and `--report-sarif` (**SARIF 2.1.0** for GitHub/GitLab code scanning). With no `--report-*` flag, HTML + `.doc` are written by default; `--no-report` writes nothing (gate-only). purls per ecosystem.
-- **CI gating & triage** — `--fail-on <low|medium|high|critical|kev>` sets a non-zero exit code (`kev` = fail only on a CISA-known-exploited finding). `--ignore <file>` (CVE/coord/glob rules) and `--vex <file>` (ingest a CSAF VEX) suppress accepted-risk / false-positive findings from the report and the gate, while keeping them flagged in the exports — so re-audits stay signal-rich.
+Highlights of the matching layer: **three CVE sources merged** (CVEProject + OSV.dev + NVD), **CPE/version cross-check** to drop false positives, **EPSS + CISA KEV** prioritisation, lockfile-first with a **best-effort pinned-version fallback** when no lockfile, in-memory **embedded-JAR** unzip (no disk, no zip-slip), and **checksum identity** for native binaries. Outputs: HTML + `.doc` by default, plus opt-in `--report-sbom`/`-csaf`/`-json`/`-sarif`; CI gating via `--fail-on` with `--ignore`/`--vex` triage.
+
+> Full per-ecosystem and per-stage detail lives in **[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)** and **[`docs/USAGE.md`](docs/USAGE.md)**.
 
 ---
 
 ## Caching
 
-All cached data lives in `~/.fad-checker/`:
-
-| Cache | Path | TTL |
-| --- | --- | --- |
-| Maven CVE index (CVEProject bundle, filtered) | `cve-data/maven-cve-index.json` | 24 h |
-| OSV per-dep lookups | `osv-cache/<ecosystem>__<g>__<a>__<v>.json` | 12 h |
-| OSV vuln details | `osv-cache/vuln_<id>.json` | 12 h |
-| NVD CVE records | `nvd-cache/<cveId>.json` | 7 d |
-| EPSS scores (FIRST.org) | `epss-cache.json` | 24 h |
-| CISA KEV catalogue | `kev-cache.json` | 24 h |
-| Go module proxy (latest) | `go-proxy-cache.json` | 24 h |
-| RubyGems (latest + licenses) | `rubygems-cache.json` | 24 h |
-| Binary identity (deps.dev + CIRCL by hash) | `hash-id-cache.json` | 24 h |
-| endoflife.date cycles | `eol-cache.json` | 7 d |
-| Maven Central latest versions | `version-cache.json` | 24 h |
-| Transitive POMs from Maven Central | `poms-cache/<g>__<a>__<v>.pom` | ∞ (immutable) |
-| retire.js findings | `retire-cache/<md5(src)>.json` | 24 h |
-| retire.js signature DB | `retire-signatures/jsrepository-v5.json` | warmed online, used offline |
-| User config (NVD key) | `config.json` (mode 0600) | — |
-
-Export the lot to share between machines:
+All cached data lives in `~/.fad-checker/` — every source is hit at most once per its
+TTL (12 h–7 d, transitive POMs forever as they're immutable). Full per-cache TTL table
+in [`docs/USAGE.md`](docs/USAGE.md). Export the lot to share between machines:
 
 ```bash
 fad-checker --export-cache fad-cache.tar.gz
@@ -317,66 +270,28 @@ DB is warmed online (phase 2) and carried by `--export-cache`.
 
 ## Custom repositories & registries
 
-Out of the box `fad-checker` queries each ecosystem's **public** registry (Maven Central, registry.npmjs.org, PyPI, RubyGems, the Go module proxy). If your project pulls artifacts from a private **Nexus / Artifactory / JBoss** (Maven), **Verdaccio / GitHub Packages** (npm), **devpi / Artifactory** (PyPI), **Gemfury / Geminabox** (Ruby) or a private **GOPROXY / Athens** (Go), register them so transitive resolution, outdated checks, deprecation and license lookups work end-to-end.
-
-Custom registries for **`maven`, `npm`, `pypi`, `ruby`, `go`**:
+Register private **Nexus / Artifactory / Verdaccio / devpi / GOPROXY** registries (for **`maven`, `npm`, `pypi`, `ruby`, `go`**) so transitive resolution, outdated/deprecation and license lookups reach them:
 
 ```bash
-# Persist a registry (lives in ~/.fad-checker/config.json, keyed by ecosystem)
-fad-checker --add-repo maven nexus     https://nexus.acme.com/repository/maven-public/ --auth alice:s3cr3t
-fad-checker --add-repo npm   verdaccio https://npm.acme.com/                            --token "$NPM_TOKEN"
-fad-checker --add-repo pypi  devpi     https://pypi.acme.com/root/pypi/+simple/         --auth alice:s3cr3t
-fad-checker --list-repos                 # grouped by ecosystem
-fad-checker --remove-repo npm verdaccio
-
-# One-off (not persisted) — repeatable, always ecosystem-scoped as <eco>=<url>
-fad-checker -s ./proj --repo npm=https://npm.acme.com/ --repo maven=https://nexus.acme.com/repository/maven-public/
-# Inline auth in the URL also works:
-fad-checker -s ./proj --repo maven=https://alice:s3cr3t@nexus.acme.com/repository/maven-public/
+fad-checker --add-repo maven nexus https://nexus.acme.com/repository/maven-public/ --auth alice:s3cr3t
+fad-checker --add-repo npm   verdaccio https://npm.acme.com/ --token "$NPM_TOKEN"
+fad-checker -s ./proj --repo npm=https://npm.acme.com/        # one-off, repeatable
 ```
 
-Registries are tried **in declared order, the public registry last**. Auth is `--auth user:pass` → `Basic <base64>` or `--token TOK` → `Bearer TOK` (inline `https://user:pass@host/` also works). Responses are cached per coordinate, so subsequent runs are free even against a private registry.
-
-> **PyPI / Ruby caveat:** the custom base must expose the **same JSON API** as the public one (`<base>/<pkg>/json`, `<base>/<gem>.json`). A pure PEP 503 *simple-index* mirror that only lists files won't yield latest/yanked/license metadata — point at the JSON-capable endpoint (Artifactory/devpi/Nexus all have one). **NuGet** and **Composer** private feeds aren't supported yet (their service-index / `packages.json` discovery is a separate follow-up).
+Tried in declared order, public registry last; auth via `--auth user:pass` / `--token TOK` / inline URL; responses cached per coordinate. NuGet/Composer private feeds aren't supported yet. **Full details, the PyPI/Ruby JSON-API caveat and `--list-repos`/`--remove-repo` → [`docs/USAGE.md`](docs/USAGE.md).**
 
 ---
 
 ## Configuration file & environment
 
-Don't retype flags every run. `fad-checker` reads defaults from three places, **lowest priority first**, all overridable on the command line:
-
-| Layer | Where | Format |
-| --- | --- | --- |
-| **CLI flags** | the command line | flags (always win) |
-| **Config file** | `--config <file.json>`, else `./.fad-env.json` | **JSON** object, keys = option names |
-| **`FAD_CHECKER_ENV`** | environment variable | a **string of CLI flags** (what you'd type) |
-| **Global config** | `~/.fad-checker/config.json` | persisted NVD key + `registries` |
-
-Effective precedence: **CLI flag > config file > `FAD_CHECKER_ENV` > global config > built-in defaults.** A file/env value only fills an option you did *not* pass on the CLI; **registries are merged (unioned) across every layer**, never overridden.
-
-```jsonc
-// ./.fad-env.json — JSON, keys mirror the CLI options (camelCase)
-{
-  "source": "./my-project",          // alias of --src (so is "src")
-  "exclude": "^(com\\.acme|client)\\.",
-  "excludePath": ["packages/legacy/**", "**/fixtures/**"],
-  "failOn": "high",
-  "noNuget": true,
-  "registries": {
-    "npm":  [{ "name": "verdaccio", "url": "https://npm.acme.com/", "token": "…" }],
-    "maven":[{ "name": "nexus", "url": "https://nexus.acme.com/repository/maven-public/", "auth": "user:pass" }]
-  }
-}
-```
+Don't retype flags every run. Precedence: **CLI flag > `--config <file.json>` / `./.fad-env.json` (JSON, keys = camelCase options) > `FAD_CHECKER_ENV` (a string of CLI flags) > `~/.fad-checker/config.json` > defaults.** A file/env value only fills an option you didn't pass; **registries are merged across every layer**.
 
 ```bash
-fad-checker --config ./ci/fad-env.json          # explicit file (beats ./.fad-env.json)
-FAD_CHECKER_ENV='--fail-on high --no-nuget --repo npm=https://npm.acme.com/' fad-checker -s ./proj
+fad-checker --config ./ci/fad-env.json
+FAD_CHECKER_ENV='--fail-on high --no-nuget' fad-checker -s ./proj
 ```
 
-The **source directory** accepts three spellings everywhere: `-s`, `--src`, `--source` (and the JSON key `"source"`/`"src"`).
-
-> **`-e/--exclude` vs `--exclude-path`:** `--exclude` is a regex on the **coordinate** (groupId/name) — it drops matching *dependencies*. `--exclude-path` is a gitignore-style glob on the **directory path** (relative to `--src`) — it prunes the *walk* so nothing under it is read. They compose. `--exclude-path` is repeatable, unioned across config layers, and `--no-default-excludes` lets you walk the normally-pruned dirs (`node_modules`, `vendor`, `target`, `.git`, …).
+`-s` / `--src` / `--source` are aliases. **`-e/--exclude`** is a regex on the **coordinate** (drops deps); **`--exclude-path`** is a gitignore-style glob on the **path** (prunes the walk). Full `.fad-env.json` schema → [`docs/USAGE.md`](docs/USAGE.md).
 
 ---
 

package/completions/fad-checker.bash

@@ -6,7 +6,7 @@ _fad_check_complete() {
 	COMPREPLY=()
 	cur="${COMP_WORDS[COMP_CWORD]}"
 	prev="${COMP_WORDS[COMP_CWORD-1]}"
-	opts="--src --target --exclude --verbose --no-report --no-transitive --no-all-libs --no-osv --no-nvd --no-epss --no-kev --no-licenses --no-retire --retire-refresh --report-output --report-html --report-doc --report-sbom --report-csaf --report-json --report-sarif --fail-on --ignore --vex --ignore-test --cve-refresh --cve-offline --snyk --transitive-depth --offline --ecosystem --no-maven --no-npm --no-yarn --no-nuget --no-composer --no-pypi --no-go --no-ruby --no-jars --no-js --set-nvd-key --show-config --completion --help --version -s -t -e -v"
+	opts="--src --target --exclude --verbose --no-report --no-transitive --no-all-libs --no-osv --no-nvd --no-epss --no-kev --licenses --no-retire --retire-refresh --report-output --report-html --report-doc --report-sbom --report-csaf --report-json --report-sarif --fail-on --ignore --vex --ignore-test --cve-refresh --cve-offline --snyk --transitive-depth --offline --ecosystem --no-maven --no-npm --no-yarn --no-nuget --no-composer --no-pypi --no-go --no-ruby --no-jars --no-js --set-nvd-key --show-config --completion --help --version -s -t -e -v"
 	case "$prev" in
 		--src|-s|--target|-t|--report-output)
 			COMPREPLY=( $(compgen -d -- "$cur") )

package/completions/fad-checker.zsh

@@ -42,6 +42,7 @@ _fad_check() {
 		'--no-pypi[skip the PyPI codec]'
 		'--no-js[alias: skip JS/npm/yarn]'
 		'--no-retire[skip retire.js vendored-JS scan]'
+		'--licenses[run license detection + copyleft policy (off by default)]'
 		'--completion[print shell completion]:shell:(bash zsh)'
 	)
 	_arguments $opts

package/fad-checker.js

@@ -25,6 +25,18 @@ const core = require("./lib/core");
 // (from $bunfs/root) and crashes with ENOENT. Keeps the bun builds fully standalone.
 const pkg = require("./package.json");
 
+// -------- compiled-binary retire mode --------
+// The bun-compiled single binary has no node_modules to spawn the retire CLI from,
+// and an air-gapped box has no `retire` on PATH. So lib/retire.js re-execs THIS
+// binary with __FAD_RETIRE__ set; here we hand off to the statically-bundled retire
+// CLI (it self-runs, reading process.argv — bun's argv mirrors node's). The entire
+// normal CLI body is gated behind `else` so fad's own commander setup never runs in
+// retire mode (retire shares commander's singleton `program`). Lets vendored-JS
+// scanning work fully offline from the one binary, no external retire needed.
+if (process.env.__FAD_RETIRE__) {
+	require("retire/lib/cli.js");
+} else {
+
 // -------- bash/zsh completion shortcut (must run before required-options parse) --------
 if (process.argv.includes("--completion")) {
 	const shellIdx = process.argv.indexOf("--completion") + 1;
@@ -210,7 +222,7 @@ program
 	.option("--fail-on <level>", "exit non-zero if a production finding meets <level>: low|medium|high|critical|kev|none", "none")
 	.option("--ignore <file>", "suppress findings listed in <file> (CVE ids / coords / globs, one per line)")
 	.option("--vex <file>", "ingest a CSAF VEX: suppress CVEs marked not_affected/fixed")
-	.option("--no-licenses", "skip license detection + copyleft policy check")
+	.option("--licenses", "run license detection + copyleft policy check (off by default)")
 	.option("--offline", "no network: use cached CVE/OSV/NVD/EPSS/KEV/POM data only")
 	.option("--set-nvd-key <key>", "save NVD API key to ~/.fad-checker/config.json (10× faster NVD enrichment)")
 	.option("--show-config", "print the persisted ~/.fad-checker/config.json")
@@ -248,6 +260,10 @@ program
 	.option("--auth <user:pass>", "Basic auth for --add-repo")
 	.option("--token <token>", "Bearer token for --add-repo")
 	.option("--completion <shell>", "print shell completion script (bash|zsh)");
+// Back-compat: license detection is now OFF by default (enable with --licenses).
+// A legacy `--no-licenses` is therefore a no-op — drop it so old invocations don't
+// trip commander's unknown-option error.
+if (process.argv.includes("--no-licenses")) process.argv = process.argv.filter(a => a !== "--no-licenses");
 program.parse(process.argv);
 
 const options = program.opts();
@@ -396,7 +412,7 @@ async function timedPhase(label, fn) {
 }
 
 (async function main() {
-	ui.banner();
+	ui.banner(pkg.version);
 
 	// Build the Maven repo list once: persisted repos (from ~/.fad-checker/config.json)
 	// + ad-hoc --repo URLs + Maven Central as final fallback. Used by transitive
@@ -432,7 +448,12 @@ async function timedPhase(label, fn) {
 	].filter(Boolean))];
 	const defaultExcludes = options.defaultExcludes !== false;
 	const walkOpts = { excludePath, defaultExcludes };
-	const runMode = options.importAnonymized ? "import descriptor" : (options.offline ? "offline" : "online");
+	// PASSI phase 1 (--export-anonymized) is a purely local operation — parse the tree,
+	// emit public coordinates, exit. Force offline so no source ever touches the network.
+	if (options.exportAnonymized) options.offline = true;
+	const runMode = options.exportAnonymized ? "offline (PASSI phase 1 · export descriptor)"
+		: options.importAnonymized ? "import descriptor"
+		: (options.offline ? "offline" : "online");
 	if (options.src) ui.kv("source", chalk.white(options.src));
 	if (mavenRepos.length > 1) ui.kv("repos", chalk.white(mavenRepos.map(r => r.name).join(chalk.dim(" → "))));
 	const otherRegs = Object.keys(regMap).filter(e => e !== "maven" && regMap[e].length);
@@ -544,6 +565,17 @@ async function timedPhase(label, fn) {
 		ui.ok(`${chalk.bold(descriptor.summary.total)} dep(s) (${ecoSummary || "none"}) → ${chalk.white(options.exportAnonymized)}`);
 		ui.info(chalk.dim("public coordinates only — no paths/URLs/host info. Review before transfer."));
 		if (!descriptor.summary.total) ui.warn("no dependencies collected — descriptor is empty");
+		// Guide the operator through the remaining two phases (the descriptor file +
+		// this run's --src are filled in so the commands are copy-paste ready).
+		const descFile = options.exportAnonymized;
+		const srcShown = options.src || "./proj";
+		ui.section("Next steps");
+		ui.info(`${chalk.dim("Phase 2 —")} ${chalk.cyan("ONLINE")} ${chalk.dim("(any box, no --src): warm the caches, then bundle them")}`);
+		ui.info("  " + chalk.white(`fad-checker --import-anonymized ${descFile}`));
+		ui.info("  " + chalk.white("fad-checker --export-cache fad-cache.tar.gz"));
+		ui.info(`${chalk.dim("Phase 3 —")} ${chalk.cyan("OFFLINE")} ${chalk.dim("(back here): import the cache, then run the full report")}`);
+		ui.info("  " + chalk.white("fad-checker --import-cache fad-cache.tar.gz"));
+		ui.info("  " + chalk.white(`fad-checker -s ${srcShown} --offline`));
 		return;
 	}
 
@@ -565,6 +597,18 @@ async function timedPhase(label, fn) {
 		}
 	}
 
+	// Mirror every non-Maven lockfile/manifest (npm/yarn/pnpm, composer, pypi, nuget,
+	// go, ruby) into the cleaned tree so `snyk test --all-projects` scans the WHOLE
+	// polyglot project, not just the cleaned POMs. Maven POMs are the rewrite above.
+	let copiedManifests = 0;
+	if (!readOnly) {
+		try {
+			const { copyEcosystemManifests } = require("./lib/manifest-copy");
+			const r = await copyEcosystemManifests(options.src, options.target, { excludePath, defaultExcludes });
+			copiedManifests = r.copied;
+		} catch (err) { console.error(chalk.red("  ✗ manifest copy failed:"), err.message); }
+	}
+
 	// ---------- Maven POM analysis summary (parents missing / excluded) ----------
 	let privateLibIds = [];
 	if (runMaven && mavenCtx) {
@@ -642,11 +686,15 @@ async function timedPhase(label, fn) {
 		else ui.info(chalk.dim(`${wrotePom} POM(s) cleanable (read-only — pass -t <dir> to write them)`));
 	}
 
+	if (!readOnly && copiedManifests) {
+		ui.ok(`${chalk.bold(copiedManifests)} non-Maven lockfile/manifest(s) mirrored → ${chalk.white(options.target)} ${chalk.dim("(so snyk --all-projects scans every ecosystem)")}`);
+	}
+
 	// ---------- Scan flow (CVE / EOL / Obsolete) ----------
 	// The scan always runs — it feeds the terminal summary, the file outputs and the
 	// CI gate. Which files get written is decided by the --report-* family inside
 	// (HTML + .doc by default; --no-report writes nothing).
-	await runReportFlow(resolved, { activeIds, runMaven, runNpm, privateLibIds, mavenRepos, regMap, collectWarnings });
+	await runReportFlow(resolved, { activeIds, runMaven, runNpm, privateLibIds, mavenRepos, regMap, collectWarnings, mavenPropsByPom: mavenCtx?.propsByPom, mavenStore: mavenCtx?.store });
 	if (!readOnly) {
 		ui.section("Next step");
 		ui.info(`run Snyk on the cleaned tree:`);
@@ -655,7 +703,7 @@ async function timedPhase(label, fn) {
 })();
 
 async function runReportFlow(resolved, ecoFlags = {}) {
-	const { activeIds = [], runMaven = true, runNpm = false, privateLibIds = [], mavenRepos = [], regMap = {}, collectWarnings = [] } = ecoFlags;
+	const { activeIds = [], runMaven = true, runNpm = false, privateLibIds = [], mavenRepos = [], regMap = {}, collectWarnings = [], mavenPropsByPom = null, mavenStore = null } = ecoFlags;
 	const registriesFor = eco => regMap[eco] || [];
 	const { expandWithTransitives } = require("./lib/cve-match");
 	const { writeReports, computeStats } = require("./lib/cve-report");
@@ -669,13 +717,9 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 	const npmWarnings = collectWarnings || [];
 	let scanWarnings = [];
 	const directCount = resolved.size;
-
-	// Scan-completeness signals: BOMs and unresolved-version deps mean fad-checker
-	// has gone as far as it can without running Maven/Snyk itself.
-	if (runMaven) {
-		const { detectScanCompletenessWarnings } = require("./lib/scan-completeness");
-		scanWarnings = detectScanCompletenessWarnings(resolved, { ranSnyk: !!options.snyk, ranTransitive: !!options.transitive });
-	}
+	// NOTE: scan-completeness (unresolved-versions) is computed LATER — after the BOM
+	// version-resolution step backfills external-BOM-managed versions — so it reflects
+	// what's *genuinely* still unresolved, not what a Maven Central BOM fetch will fix.
 
 	// ---- Vulnerability database update (global step progress) ----
 	ui.section("Vulnerability database update");
@@ -694,6 +738,17 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 	const otherRegistryIds = activeIds.filter(id => id !== "maven" && id !== "npm" && id !== "yarn" && getCodec(id)?.checkRegistry);
 	const willCve = !!cveScanner && (!(options.cveOffline || offline) || cveIndexExists);
 	const willTransitive = !!(options.transitive && runMaven);
+	// Per-module version mediation overlay: recover transitive versions the global
+	// transitive pass masks via cross-module depMgmt bleed. Runs after (and only when)
+	// the global pass runs, and needs the parsed store + per-module props.
+	const willOverlay = willTransitive && !!mavenPropsByPom && !!mavenStore;
+	// External import BOMs (e.g. spring-boot-dependencies): resolve their managed
+	// versions to backfill declared deps that pin no version of their own (the usual
+	// Spring Boot setup). Cached via poms-cache; offline-aware (uses warmed POMs,
+	// never the network — same as transitive resolution).
+	const importBoms = (runMaven && mavenPropsByPom)
+		? require("./lib/maven-bom").collectImportBoms(mavenPropsByPom) : [];
+	const willBom = importBoms.length > 0;
 	const willOsv = !!options.osv;
 	const willOutdated = !!options.allLibs;
 	const willNvd = !!options.nvd;
@@ -705,9 +760,18 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 	const willBinaryId = [...resolved.values()].some(d => d.provenance === "binary");
 	// License detection piggybacks on the registry passes (same fetched metadata),
 	// so it adds no progress step of its own.
-	const totalSteps = [willTransitive, willCve, /*EOL*/ true, willOutdated, /*npm reg*/ true, ...otherRegistryIds.map(() => true), willOsv, willNvd, willEpss, willKev, willRetire, willBinaryId].filter(Boolean).length;
+	const totalSteps = [willBom, willTransitive, willOverlay, willCve, /*EOL*/ true, willOutdated, /*npm reg*/ true, ...otherRegistryIds.map(() => true), willOsv, willNvd, willEpss, willKev, willRetire, willBinaryId].filter(Boolean).length;
 	const progress = new ui.Progress(totalSteps);
 
+	if (willBom) {
+		const st = progress.start("BOM version resolution (Maven Central)");
+		try {
+			const { resolveAndBackfill } = require("./lib/maven-bom");
+			const r = await resolveAndBackfill(mavenPropsByPom, resolved, { repos: mavenRepos, offline, verbose });
+			st.done(`${r.filled} dep version(s) from ${r.boms} import BOM(s)`);
+		} catch (err) { st.fail(err.message); }
+	}
+
 	if (willTransitive) {
 		const st = progress.start("Transitive resolution (Maven Central)");
 		await expandWithTransitives(resolved, {
@@ -720,6 +784,32 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		st.done(`+${resolved.size - directCount} transitive (total ${resolved.size})`);
 	}
 
+	if (willOverlay) {
+		const st = progress.start("Per-module version mediation (masked transitives)");
+		try {
+			const { expandPerModuleOverlay } = require("./lib/version-overlay");
+			const ov = await expandPerModuleOverlay(resolved, mavenStore, mavenPropsByPom, {
+				verbose,
+				offline,
+				maxDepth: parseInt(options.transitiveDepth, 10) || 6,
+				includeTestDeps: !options.ignoreTest,
+				repos: mavenRepos,
+			});
+			st.done(`+${ov.appended} masked version(s) recovered across ${ov.modules} module(s)`);
+			if (verbose && ov.recovered.length) {
+				for (const r of ov.recovered) console.log(`   ↳ ${r.coord}: +${r.version} (had ${r.had})  via ${r.module}`);
+			}
+		} catch (err) { st.fail(err.message); }
+	}
+
+	// Scan-completeness signals — computed NOW (after BOM backfill) so only the deps
+	// still without a concrete version (external BOM truly unreachable, or offline)
+	// are flagged, not the ones we just resolved from spring-boot-dependencies & co.
+	if (runMaven) {
+		const { detectScanCompletenessWarnings } = require("./lib/scan-completeness");
+		scanWarnings = detectScanCompletenessWarnings(resolved, { ranSnyk: !!options.snyk, ranTransitive: !!options.transitive });
+	}
+
 	// 1. CVE — native scanner contributed by the maven codec (local cvelistV5 index).
 	let cveMatches = [];
 	let cveDataDate = null;
@@ -887,6 +977,7 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 	// scanner is owned by the npm codec but runs whenever --retire is on.
 	let retireMatches = [];
 	let vendoredJsInventory = [];
+	let retireWarnings = [];
 	if (willRetire) {
 		const st = progress.start("retire.js (vendored JS)");
 		const sc = (getCodec("npm").nativeScanners || []).find(s => s.kind === "vendored");
@@ -898,8 +989,15 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 				retireMatches = r.matches || [];
 				if (options.vendoredJsInventory !== false) vendoredJsInventory = r.meta?.inventory || [];
 				const invN = vendoredJsInventory.length;
-				st.done(`${retireMatches.length} finding(s)${invN ? ` · ${invN} lib(s) inventoried` : ""}`);
-			} catch (err) { st.fail(err.message); }
+				if (r.meta?.error) {
+					// A genuine scan failure — surface it instead of letting an empty
+					// vendored-JS chapter look like "nothing found".
+					st.fail(r.meta.error);
+					retireWarnings.push({ type: "retire-failed", message: `${r.meta.error} — the vendored-JS scan (chapters 1D / 2) could not run, so any vendored \`.js\` (jQuery, Bootstrap, …) is NOT covered. Re-run with \`-v\` for the exact error; check the \`--src\` path exists and is readable.` });
+				} else {
+					st.done(`${retireMatches.length} finding(s)${invN ? ` · ${invN} lib(s) inventoried` : ""}`);
+				}
+			} catch (err) { st.fail(err.message); retireWarnings.push({ type: "retire-failed", message: `retire.js scan failed: ${err.message} — vendored-JS chapters (1D / 2) not covered.` }); }
 		}
 	}
 
@@ -1038,7 +1136,12 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		ui.warn(`${scanWarnings.length} scan-completeness note(s) — a real Maven/Snyk run may surface more:`);
 		for (const w of scanWarnings) {
 			ui.info(chalk.dim(`[${w.type}] ${w.message}`));
-			for (const it of (w.items || []).slice(0, 4)) console.log("      " + chalk.dim(`· ${it}`));
+			// Items may be plain strings or { id, manifestPaths } objects (the
+			// unresolved-versions warning carries the defining manifest paths).
+			for (const it of (w.items || []).slice(0, 4)) {
+				const id = typeof it === "string" ? it : it.id;
+				console.log("      " + chalk.dim(`· ${id}`));
+			}
 			if ((w.items || []).length > 4) console.log("      " + chalk.dim(`· …and ${w.items.length - 4} more`));
 		}
 	}
@@ -1102,6 +1205,7 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		}] : []),
 		...npmWarnings,
 		...scanWarnings,
+		...retireWarnings,
 		...(privateLibIds.length ? [{
 			type: "private-libs",
 			count: privateLibIds.length,
@@ -1231,3 +1335,5 @@ function mergeBySource(existing, additions) {
 	});
 	return merged;
 }
+
+} // end: compiled-binary retire-mode guard (see top of file)

package/lib/codecs/npm.codec.js

@@ -21,8 +21,8 @@ const retireScanner = {
 	kind: "vendored",   // résultats → chapitre vendored-JS (séparé des CVE)
 	async scan(_deps, opts = {}) {
 		const { scanWithRetireFull } = require("../retire");
-		const { matches, inventory } = await scanWithRetireFull(opts.src, { verbose: opts.verbose, force: !!opts.retireRefresh, offline: !!opts.offline });
-		return { matches, meta: { inventory } };
+		const { matches, inventory, error } = await scanWithRetireFull(opts.src, { verbose: opts.verbose, force: !!opts.retireRefresh, offline: !!opts.offline });
+		return { matches, meta: { inventory, error } };
 	},
 };
 

package/lib/cve-match.js

@@ -180,12 +180,17 @@ function matchOne(dep, entries, confidence) {
 	// the same g:a), not just the representative highest — otherwise a CVE that
 	// only affects a lower-versioned profile variant would be missed.
 	const versions = (dep.versions && dep.versions.length) ? dep.versions : [dep.version];
+	// Only CONCRETE, resolved versions can be matched. A dep whose version is null
+	// or an unresolved `${property}` (typically pinned by an external BOM like
+	// spring-boot-dependencies) carries NO version we can compare — matching it
+	// against every "affected" range would flag it as vulnerable to ALL the
+	// coordinate's CVEs (a flood of false CRITICALs with version "?"). Skip it;
+	// it's already reported in chapter 0 as an "unresolved-versions" warning.
+	const concrete = versions.filter(v => v && !/\$\{/.test(String(v)));
+	if (!concrete.length) return matches;
 	for (const e of entries) {
-		for (const ver of versions) {
-			const affected = (e.ranges || []).some(r => {
-				if (!ver) return r.status === "affected"; // unknown version → assume affected
-				return isVersionAffected(ver, r);
-			});
+		for (const ver of concrete) {
+			const affected = (e.ranges || []).some(r => isVersionAffected(ver, r));
 			if (affected) {
 				const vdep = ver === dep.version ? dep : { ...dep, version: ver };
 				matches.push({ dep: vdep, cve: { ...e }, confidence });