fad-checker 2.2.0 → 2.2.1

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;
 	}
 
@@ -887,6 +919,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 +931,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.` }); }
 		}
 	}
 
@@ -1102,6 +1142,7 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		}] : []),
 		...npmWarnings,
 		...scanWarnings,
+		...retireWarnings,
 		...(privateLibIds.length ? [{
 			type: "private-libs",
 			count: privateLibIds.length,
@@ -1231,3 +1272,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-report.js

@@ -13,6 +13,7 @@ const path = require("path");
 const { getCodec, allCodecs, ORDER } = require("./codecs");
 const { computePriority, sortByPriority } = require("./priority");
 const { buildInventory } = require("./unmanaged");
+const { buildEmbeddedInventory } = require("./embedded");
 
 // CWE-id → short human name. Loaded once at module init. Unknown CWEs fall
 // back to the raw id (with a "—" placeholder name where the row asks for one).
@@ -935,17 +936,42 @@ function renderRecommendationsForEco(slice, meta) {
 	return blocks.join("");
 }
 
+// Where a dependency comes from in the tree. A transitive dep (no defining
+// manifest) carries `via` — the chain of g:a from a root direct dep down to it —
+// recorded by the transitive resolver. Show that chain so an EOL/CVE finding on a
+// "dep of a dep" is traceable to the direct dependency that pulls it in. A direct
+// dep falls back to its defining manifest(s).
+function renderDepOrigin(dep, srcRoot) {
+	if (dep.via && dep.via.length) {
+		const chain = dep.via.map(c => `<code>${esc(c)}</code>`).join(" → ");
+		const tail = `<code>${esc(`${dep.groupId}:${dep.artifactId}`)}</code>`;
+		const alt = (dep.viaPaths && dep.viaPaths.length > 1) ? ` <span class="defined-more">+${dep.viaPaths.length - 1} more path${dep.viaPaths.length > 2 ? "s" : ""}</span>` : "";
+		return `<div class="defined-in"><span class="defined-label">pulled in via:</span> ${chain} → ${tail}${alt}</div>`;
+	}
+	return renderDefinedIn(dep, srcRoot);
+}
+
+// The source of an EOL verdict: the endoflife.date product queried, and which
+// mapping rule (data/eol-mapping.json) matched the dep to that product.
+function renderEolSource(e) {
+	const slug = e.productSlug || "";
+	const link = slug ? `endoflife.date/${esc(slug)}` : "endoflife.date";
+	const rule = e.via ? `<br><span style="color:#6b7280">matched via ${esc(e.via)} = <code>${esc(e.viaKey || "")}</code></span>` : "";
+	return `<span>${link}</span>${rule}`;
+}
+
 function renderEolTable(eolResults) {
 	if (!eolResults?.length) return `<div class="empty">No end-of-life frameworks detected.</div>`;
 	const rows = eolResults.map(e => `<tr>
 		<td class="dep">${esc(e.product)}</td>
-		<td class="dep">${esc(depDisplayName(e.dep))}<br><span style="color:#6b7280">${esc(e.dep.version || "?")}</span>${renderDefinedIn(e.dep, RENDER_CTX.srcRoot)}</td>
+		<td class="dep">${esc(depDisplayName(e.dep))}<br><span style="color:#6b7280">${esc(e.dep.version || "?")}</span>${renderDepOrigin(e.dep, RENDER_CTX.srcRoot)}</td>
 		<td>${esc(e.eol || "")}</td>
 		<td>${esc(e.latest || "")}</td>
+		<td class="dep">${renderEolSource(e)}</td>
 		<td class="desc">${esc(e.notes || "")}</td>
 	</tr>`).join("\n");
 	return `<table>
-		<thead><tr><th>Product</th><th>Dependency</th><th>EOL date</th><th>Latest</th><th>Notes</th></tr></thead>
+		<thead><tr><th>Product</th><th>Dependency</th><th>EOL date</th><th>Latest</th><th>Source</th><th>Notes</th></tr></thead>
 		<tbody>${rows}</tbody>
 	</table>`;
 }
@@ -1338,7 +1364,7 @@ const LICENSE_CAT_ORDER = ["network-copyleft", "strong-copyleft", "proprietary",
 
 function renderLicenseChapter(licenseResults) {
 	if (!licenseResults || !licenseResults.assessed?.length) {
-		return `<div class="empty">No license data resolved (offline, or registries returned none).</div>`;
+		return `<div class="empty">No license data — the license scan is off by default (enable with <code>--licenses</code>); also empty when offline or registries return none.</div>`;
 	}
 	const { byCategory } = licenseResults;
 	const blocks = LICENSE_CAT_ORDER.filter(cat => byCategory[cat]?.length).map(cat => {
@@ -1397,7 +1423,8 @@ function buildBody({ cveMatches, devCveMatches, embeddedMatches, retireMatches,
 	const licenseContent   = renderLicenseChapter(licenseResults);
 	const licenseTotal     = licenseResults?.assessed?.length || 0;
 	const licenseFlagged   = licenseResults?.flagged?.length || 0;
-	const embeddedContent  = renderEmbeddedChapter(embMatchesActive, projectInfo?.src);
+	const embeddedInventory = buildEmbeddedInventory(resolvedDeps || new Map(), embMatchesActive);
+	const embeddedContent  = renderEmbeddedChapter(embeddedInventory, embMatchesActive, projectInfo?.src);
 	const unmanagedInventory = buildInventory(resolvedDeps || new Map());
 	const unmanagedContent = renderUnmanagedInventory(unmanagedInventory, projectInfo?.src);
 	const vendoredJsInv    = vendoredJsInventory || [];
@@ -1433,7 +1460,7 @@ function buildBody({ cveMatches, devCveMatches, embeddedMatches, retireMatches,
 		outdatedTotal: outdatedResults?.length || 0,
 		licenseTotal,
 		licenseFlagged,
-		embeddedTotal: embStats.total,
+		embeddedTotal: embeddedInventory.length,
 		unmanagedTotal: unmanagedInventory.length,
 		vendoredJsTotal: vendoredJsInv.length,
 		fpTotal: prodMatchesFP.length + devMatchesFP.length + embMatchesFP.length,
@@ -1455,7 +1482,7 @@ function buildBody({ cveMatches, devCveMatches, embeddedMatches, retireMatches,
 
 		${(warnings?.length || 0) ? majorSection(`0. Warnings & scan-completeness (${warnings.length})`, renderWarnings(warnings), { open: true, id: "ch0" }) : ""}
 		${majorSection(`1. CVE Vulnerabilities — production (${prodStats.total})`, cveContent, { id: "ch1" })}
-		${embStats.total ? majorSection(`1B. Embedded binaries — JAR/WAR/EAR (${embStats.total})`, embeddedContent, { open: embStats.total <= 50, id: "ch1e" }) : ""}
+		${embeddedInventory.length ? majorSection(`1B. Embedded binaries — JAR/WAR/EAR (${embeddedInventory.length})`, embeddedContent, { open: embeddedInventory.length <= 50, id: "ch1e" }) : ""}
 		${unmanagedInventory.length ? majorSection(`1C. Unmanaged / vendored binaries (${unmanagedInventory.length})`, unmanagedContent, { open: unmanagedInventory.length <= 50, id: "ch1c" }) : ""}
 		${vendoredJsInv.length ? majorSection(`1D. Unmanaged / vendored JavaScript (${vendoredJsInv.length})`, vendoredJsContent, { open: vendoredJsInv.length <= 50, id: "ch1d" }) : ""}
 		${majorSection(`2. Vendored JS scan — retire.js (${retireMatches.length})`, vendoredContent, { open: retireMatches.length > 0 && retireMatches.length <= 50, id: "ch2" })}
@@ -1520,22 +1547,39 @@ function renderToc({ hasWarnings, prodTotal, embeddedTotal, unmanagedTotal, vend
 	return `<nav class="toc">${entries.map(e => `<a href="#${e.id}">${esc(e.label)}</a>`).join("")}</nav>`;
 }
 
-// Embedded-binary CVE chapter: group findings by their top-level archive (the
-// part of the manifestPath before the first "!/"), so a fat-jar lists all the
-// vulnerable libraries shaded inside it.
-function renderEmbeddedChapter(matches, srcRoot) {
-	if (!matches.length) return `<div class="empty">No CVEs found in embedded binaries.</div>`;
-	const intro = `<div class="fp-intro">Maven coordinates discovered inside committed <code>.jar</code>/<code>.war</code>/<code>.ear</code> binaries (vendored libs, fat-jars) — not declared in any <code>pom.xml</code>. Patch by rebuilding/replacing the containing archive.</div>`;
+// Embedded-binary inventory chapter (1B): every embedded coordinate grouped by its
+// top-level archive (the part of the manifestPath before the first "!/"), with its
+// CVE status. Vulnerable coords additionally get the full CVE detail table.
+function renderEmbeddedChapter(inventory, embeddedMatches, srcRoot) {
+	if (!inventory.length) return `<div class="empty">No embedded JAR/WAR/EAR coordinates found.</div>`;
+	const vulnN = inventory.filter(e => e.vulnCount > 0).length;
+	const intro = `<div class="fp-intro">Maven coordinates discovered inside committed <code>.jar</code>/<code>.war</code>/<code>.ear</code> binaries (vendored libs, fat-jars, shaded uber-jars) — <strong>not declared in any <code>pom.xml</code></strong>. Unmanaged third-party code: unknown provenance and patch story even when not vulnerable. <strong>${vulnN}</strong> of ${inventory.length} carry known CVEs (patch by rebuilding/replacing the containing archive).</div>`;
+	// CVE matches keyed by archive, for the per-archive detail tables.
+	const matchesByArchive = new Map();
+	for (const m of (embeddedMatches || [])) {
+		const top = String((m.dep?.manifestPaths || [])[0] || "(unknown archive)").split("!/")[0];
+		if (!matchesByArchive.has(top)) matchesByArchive.set(top, []);
+		matchesByArchive.get(top).push(m);
+	}
 	const byArchive = new Map();
-	for (const m of matches) {
-		const mp = (m.dep?.manifestPaths || [])[0] || "(unknown archive)";
-		const top = String(mp).split("!/")[0];
-		if (!byArchive.has(top)) byArchive.set(top, []);
-		byArchive.get(top).push(m);
+	for (const e of inventory) {
+		if (!byArchive.has(e.archive)) byArchive.set(e.archive, []);
+		byArchive.get(e.archive).push(e);
 	}
-	const blocks = [...byArchive.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([archive, list]) =>
-		minorSection(`📦 <code class="path">${esc(archive)}</code> (${list.length})`, renderCveTable(list), { open: list.length <= 30 })
-	).join("\n");
+	const blocks = [...byArchive.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([archive, list]) => {
+		const rows = list.map(e => {
+			const coord = `${e.groupId}:${e.artifactId}:${e.version}`;
+			const status = e.vulnCount > 0
+				? pill(`${e.vulnCount} CVE${e.vulnCount > 1 ? "s" : ""}${e.maxSeverity ? " · " + e.maxSeverity : ""}`, "#b91c1c")
+				: pill("no known CVE", "#15803d");
+			return `<tr><td class="dep"><code>${esc(coord)}</code></td><td>${status}</td></tr>`;
+		}).join("\n");
+		const invTable = `<table><thead><tr><th>Coordinate (groupId:artifactId:version)</th><th>Status</th></tr></thead><tbody>${rows}</tbody></table>`;
+		const cveDetail = matchesByArchive.has(archive)
+			? `<div class="defined-in" style="margin-top:8px"><span class="defined-label">CVE detail:</span></div>` + renderCveTable(matchesByArchive.get(archive))
+			: "";
+		return minorSection(`📦 <code class="path">${esc(archive)}</code> (${list.length})`, invTable + cveDetail, { open: list.length <= 30 });
+	}).join("\n");
 	return intro + blocks;
 }
 
@@ -1984,6 +2028,7 @@ async function writeReports({ cveMatches, devCveMatches, embeddedMatches, retire
 
 module.exports = {
 	computeStats,
+	buildEmbeddedInventory,
 	generateHtmlReport,
 	generateWordReport,
 	writeReports,

package/lib/embedded.js

@@ -0,0 +1,57 @@
+/**
+ * lib/embedded.js — inventory of Maven coordinates discovered inside committed
+ * .jar/.war/.ear archives (provenance:"embedded"), whether or not they carry a CVE.
+ *
+ * This is a governance / cyber-hygiene signal: the JAR twin of the native-binary
+ * inventory (lib/unmanaged.js → chapter 1C) and the vendored-JS inventory
+ * (lib/retire.js → chapter 1D). Code that ships inside a committed binary which no
+ * pom.xml declares has unknown provenance and patch story even when not vulnerable.
+ *
+ * Pure: shared by the HTML report (chapter 1B) and the JSON export so both list the
+ * SAME set. CVE counts/severity are cross-referenced from the embedded CVE matches
+ * by coordKey.
+ */
+
+const EMB_SEV_RANK = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1, NONE: 0, UNKNOWN: 0 };
+
+/**
+ * @param resolvedDeps Map of all resolved deps (embedded ones carry provenance:"embedded").
+ * @param embeddedMatches CVE matches whose dep is embedded (subset of the scan's matches).
+ * @returns sorted array of { archive, groupId, artifactId, version, coordKey, manifestPath, vulnCount, maxSeverity }
+ */
+function buildEmbeddedInventory(resolvedDeps, embeddedMatches) {
+	const cveByCoord = new Map(); // coordKey → { ids:Set, maxSeverity }
+	for (const m of (embeddedMatches || [])) {
+		const key = m.dep?.coordKey;
+		if (!key) continue;
+		let e = cveByCoord.get(key);
+		if (!e) { e = { ids: new Set(), maxSeverity: null }; cveByCoord.set(key, e); }
+		e.ids.add(m.cve?.id);
+		const sev = m.cve?.severity || "UNKNOWN";
+		if (!e.maxSeverity || (EMB_SEV_RANK[sev] || 0) > (EMB_SEV_RANK[e.maxSeverity] || 0)) e.maxSeverity = sev;
+	}
+	const out = [];
+	for (const dep of (resolvedDeps?.values?.() || [])) {
+		if (dep.provenance !== "embedded") continue;
+		const manifestPath = (dep.manifestPaths || [])[0] || "(unknown archive)";
+		const archive = String(manifestPath).split("!/")[0];
+		const cve = cveByCoord.get(dep.coordKey);
+		out.push({
+			archive,
+			groupId: dep.groupId || dep.namespace || "",
+			artifactId: dep.artifactId || dep.name || "",
+			version: dep.version || "",
+			coordKey: dep.coordKey,
+			manifestPath,
+			vulnCount: cve ? cve.ids.size : 0,
+			maxSeverity: cve ? cve.maxSeverity : null,
+		});
+	}
+	out.sort((a, b) =>
+		(EMB_SEV_RANK[b.maxSeverity] || 0) - (EMB_SEV_RANK[a.maxSeverity] || 0)
+		|| String(a.archive).localeCompare(String(b.archive))
+		|| `${a.groupId}:${a.artifactId}:${a.version}`.localeCompare(`${b.groupId}:${b.artifactId}:${b.version}`));
+	return out;
+}
+
+module.exports = { buildEmbeddedInventory, EMB_SEV_RANK };

package/lib/json-export.js

@@ -72,6 +72,10 @@ function buildFindings(payload = {}) {
 	const { buildInventory } = require("./unmanaged");
 	const unmanaged = resolvedDeps ? buildInventory(resolvedDeps) : [];
 
+	const { buildEmbeddedInventory } = require("./embedded");
+	const embeddedMatches = cveMatches.filter(m => m.dep?.provenance === "embedded");
+	const embedded = resolvedDeps ? buildEmbeddedInventory(resolvedDeps, embeddedMatches) : [];
+
 	const sevCounts = Object.fromEntries(SEV.map(s => [s, 0]));
 	let kev = 0;
 	for (const m of cveMatches) {
@@ -94,16 +98,18 @@ function buildFindings(payload = {}) {
 			licensesFlagged: licenseResults?.flagged?.length || 0,
 			vendored: retireMatches.length,
 			unmanaged: unmanaged.length,
+			embedded: embedded.length,
 			vendoredJs: vendoredJsInventory.length,
 			suppressed: cveMatches.filter(m => m.suppressed).length,
 		},
 		cve: cveMatches.map(cveFinding),
 		vendored: retireMatches.map(cveFinding),
-		eol: eolResults.map(e => ({ product: e.product, eol: e.eol, dep: depBrief(e.dep) })),
+		eol: eolResults.map(e => ({ product: e.product, productSlug: e.productSlug || null, via: e.via || null, viaKey: e.viaKey || null, eol: e.eol, dep: depBrief(e.dep) })),
 		obsolete: obsoleteResults.map(o => ({ reason: o.reason || null, replacement: o.replacement || null, source: o.source || null, dep: depBrief(o.dep) })),
 		outdated: outdatedResults.map(o => ({ latest: o.latest, releaseDate: o.releaseDate || null, dep: depBrief(o.dep) })),
 		licenses: (licenseResults?.assessed || []).map(e => ({ category: e.category, licenses: e.ids.concat(e.raw), source: e.source || null, dep: depBrief(e.dep) })),
 		unmanaged,
+		embedded,
 		vendoredJs: vendoredJsInventory,
 	};
 }

package/lib/outdated.js

@@ -42,6 +42,13 @@ function isEolCacheFresh(maxAge = EOL_CACHE_MAX_AGE_MS) {
 
 // -------- EOL via endoflife.date --------
 
+// Tag the matched mapping entry with HOW it matched (which rule + which key), so
+// the report can show where an EOL verdict comes from. Returns a COPY — the shared
+// EOL_MAPPING objects must never be mutated (they're reused across deps).
+function withOrigin(entry, via, viaKey) {
+	return entry ? { ...entry, via, viaKey } : null;
+}
+
 function findEolProduct(dep) {
 	// npm packages — and WebJars, which are client-side JS shipped as Maven
 	// artifacts — resolve by JS library name, not Maven coordinate. npm deps
@@ -49,36 +56,39 @@ function findEolProduct(dep) {
 	// first (org.webjars:angularjs → "angularjs", org.webjars.npm:angular__core
 	// → "@angular/core"). The npm package literally named "angular" is AngularJS
 	// 1.x; modern Angular is the @angular/* scope — hence the name vs. scope maps.
+	const isWebjar = dep.ecosystem !== "npm" && webjarToNpm(dep) != null;
 	const npmName = dep.ecosystem === "npm" ? (dep.artifactId || "") : webjarToNpm(dep)?.name;
 	if (npmName != null) {
 		const byName = EOL_MAPPING.by_npm_name?.[npmName];
-		if (byName) return byName;
+		if (byName) return withOrigin(byName, isWebjar ? "webjar" : "npm-name", npmName);
 		const scopes = Object.keys(EOL_MAPPING.by_npm_scope || {})
 			.sort((a, b) => b.length - a.length);
 		for (const s of scopes) {
-			if (npmName.startsWith(s)) return EOL_MAPPING.by_npm_scope[s];
+			if (npmName.startsWith(s)) return withOrigin(EOL_MAPPING.by_npm_scope[s], isWebjar ? "webjar" : "npm-scope", s);
 		}
 		return null;
 	}
 	if (dep.ecosystem === "composer") {
 		const full = `${dep.namespace || dep.groupId || ""}/${dep.name || dep.artifactId}`.toLowerCase();
-		return EOL_MAPPING.by_composer_name?.[full] || null;
+		return withOrigin(EOL_MAPPING.by_composer_name?.[full], "composer-name", full);
 	}
 	if (dep.ecosystem === "pypi") {
-		return EOL_MAPPING.by_pypi_name?.[(dep.name || dep.artifactId || "").toLowerCase()] || null;
+		const k = (dep.name || dep.artifactId || "").toLowerCase();
+		return withOrigin(EOL_MAPPING.by_pypi_name?.[k], "pypi-name", k);
 	}
 	if (dep.ecosystem === "nuget") {
-		return EOL_MAPPING.by_nuget_name?.[(dep.name || dep.artifactId || "").toLowerCase()] || null;
+		const k = (dep.name || dep.artifactId || "").toLowerCase();
+		return withOrigin(EOL_MAPPING.by_nuget_name?.[k], "nuget-name", k);
 	}
 	const key = `${dep.groupId}:${dep.artifactId}`;
 	const direct = EOL_MAPPING.by_group_artifact?.[key];
-	if (direct) return direct;
+	if (direct) return withOrigin(direct, "group-artifact", key);
 	// Match longest groupId prefix
 	const prefixes = Object.keys(EOL_MAPPING.by_group_prefix || {})
 		.sort((a, b) => b.length - a.length);
 	for (const p of prefixes) {
 		if (dep.groupId === p || dep.groupId.startsWith(p + ".")) {
-			return EOL_MAPPING.by_group_prefix[p];
+			return withOrigin(EOL_MAPPING.by_group_prefix[p], "group-prefix", p);
 		}
 	}
 	return null;
@@ -154,6 +164,8 @@ async function checkEolDeps(resolvedDeps, opts = {}) {
 			dep,
 			product: product.label || product.product,
 			productSlug: product.product,
+			via: product.via || null,
+			viaKey: product.viaKey || null,
 			cycle: cycle.cycle,
 			eol: cycle.eol === true ? "true" : String(cycle.eol),
 			latest: cycle.latest || null,

package/lib/retire.js

@@ -36,15 +36,38 @@ const RETIRE_SIG_DIR = path.join(os.homedir(), ".fad-checker", "retire-signature
 const RETIRE_SIG_FILE = path.join(RETIRE_SIG_DIR, "jsrepository-v5.json");
 const RETIRE_REPO_URL = "https://raw.githubusercontent.com/RetireJS/retire.js/master/repository/jsrepository-v5.json";
 
+// retire always emits ABSOLUTE file paths (it resolves --jspath). Make them
+// relative to the scan root robustly — resolving BOTH sides so it works whether
+// the caller passed -s as a relative ("./proj") or absolute path. The old
+// `file.startsWith(srcDir)` guard silently left paths absolute for a relative -s.
+function relToSrc(srcDir, file) {
+	if (!file) return file;
+	if (!srcDir) return file;
+	try {
+		const rel = path.relative(path.resolve(srcDir), path.resolve(file));
+		return rel && !rel.startsWith("..") ? rel : file;
+	} catch { return file; }
+}
+
 function cacheKey(srcDir) {
 	return crypto.createHash("md5").update(path.resolve(srcDir)).digest("hex") + ".json";
 }
 
+// Cache schema version. Bumped to 2 when retire started running with `--verbose`
+// (so the cached body carries the FULL vendored-JS inventory, not just vulnerable
+// hits). A cached entry without `_schema >= 2` was written by a pre-verbose build
+// (e.g. 1.0.6) and its body holds vuln-only data — trusting it would silently empty
+// the inventory chapter (1D) on an offline re-run. We treat such an entry as a
+// cache MISS so the normal path re-scans (online, or offline with local signatures)
+// and the offline report reproduces the online one.
+const RETIRE_CACHE_SCHEMA = 2;
+
 function readCache(srcDir) {
 	const p = path.join(RETIRE_CACHE_DIR, cacheKey(srcDir));
 	if (!fs.existsSync(p)) return null;
 	try {
 		const data = JSON.parse(fs.readFileSync(p, "utf8"));
+		if (!(data._schema >= RETIRE_CACHE_SCHEMA)) return null; // legacy / pre-verbose → re-scan
 		if (Date.now() - data._fetchedAt < RETIRE_CACHE_TTL_MS) return data.body;
 	} catch { /* ignore */ }
 	return null;
@@ -53,7 +76,7 @@ function readCache(srcDir) {
 function writeCache(srcDir, body) {
 	fs.mkdirSync(RETIRE_CACHE_DIR, { recursive: true });
 	fs.writeFileSync(path.join(RETIRE_CACHE_DIR, cacheKey(srcDir)),
-		JSON.stringify({ _fetchedAt: Date.now(), body }));
+		JSON.stringify({ _schema: RETIRE_CACHE_SCHEMA, _fetchedAt: Date.now(), body }));
 }
 
 function findRetireBin() {
@@ -62,6 +85,28 @@ function findRetireBin() {
 	return "retire"; // fall back to PATH
 }
 
+// Decide HOW to launch retire. The compiled (bun) binary has no node_modules to
+// spawn the retire CLI from and the air-gapped box has no `retire` on PATH — so it
+// re-execs ITSELF with __FAD_RETIRE__ set, and the entry point (fad-checker.js)
+// hands off to the statically-bundled retire CLI. Pure for testability.
+//   - localBin present (node dev / node_modules) → run it directly.
+//   - else running under bun (compiled binary)   → self-invoke this executable.
+//   - else                                       → `retire` on PATH (last resort).
+function chooseRetireLauncher({ localBin, isBun, execPath }) {
+	if (localBin) return { cmd: localBin, env: null };
+	if (isBun) return { cmd: execPath, env: { __FAD_RETIRE__: "1" } };
+	return { cmd: "retire", env: null };
+}
+
+function findRetireLauncher() {
+	const local = path.join(__dirname, "..", "node_modules", ".bin", "retire");
+	return chooseRetireLauncher({
+		localBin: fs.existsSync(local) ? local : null,
+		isBun: !!(process.versions && process.versions.bun),
+		execPath: process.execPath,
+	});
+}
+
 /**
  * Fetch retire's signature DB to a stable file inside ~/.fad-checker/ so it can
  * be bundled by --export-cache and reused offline via --jsrepo. Network call —
@@ -117,6 +162,19 @@ function buildRetireArgs({ srcDir, outPath, ignoredDirs, jsRepo }) {
 
 const SEV_RANK = { critical: 5, high: 4, medium: 3, low: 2, none: 1 };
 
+// Pick the human-meaningful line out of retire's stderr for a failure message.
+// retire dumps a multi-line stack trace; the useful part is the first non-empty,
+// non-stack-frame line (preferring an ENOENT / "no such file" / permission line).
+function retireFailureReason(stderr, fallback) {
+	const lines = String(stderr || "")
+		.split("\n")
+		.map(l => l.trim())
+		.filter(l => l && !/^at\s/.test(l));
+	if (!lines.length) return fallback;
+	const hot = lines.find(l => /ENOENT|no such file|permission denied|EACCES/i.test(l));
+	return hot || lines[0];
+}
+
 /**
  * Extract the full inventory of identified vendored JS libraries (vulnerable or
  * not) from retire's --verbose output. Each entry: the standalone library, where
@@ -131,7 +189,7 @@ function extractVendoredInventory(raw, srcDir) {
 	const files = Array.isArray(raw) ? raw : (raw.data || []);
 	for (const f of files) {
 		const file = f.file;
-		const relFile = srcDir && file?.startsWith(srcDir) ? path.relative(srcDir, file) : file;
+		const relFile = relToSrc(srcDir, file);
 		for (const res of f.results || []) {
 			if (!res.component) continue;
 			const vulns = res.vulnerabilities || [];
@@ -169,6 +227,10 @@ function extractVendoredInventory(raw, srcDir) {
  */
 async function runRetire(srcDir, opts = {}) {
 	const { verbose, force, offline } = opts;
+	// Optional diagnostics collector: callers (scanWithRetireFull) read diag.error to
+	// surface a genuine SCAN FAILURE (retire crashed / produced no parseable output)
+	// as a report warning — instead of letting it masquerade as "no vendored JS found".
+	const diag = opts.diag || {};
 	// No source tree (e.g. --import-anonymized) → nothing to scan for vendored JS.
 	if (!srcDir) { if (verbose) console.warn("retire: no source dir — skipped"); return null; }
 	// Findings-cache fast path (path-keyed). Works online and offline.
@@ -189,7 +251,7 @@ async function runRetire(srcDir, opts = {}) {
 		return null;
 	}
 
-	const bin = findRetireBin();
+	const launcher = findRetireLauncher();
 	const ignoredDirs = [
 		"node_modules", "bower_components", "jspm_packages",
 		".git", ".idea", ".vscode", ".gradle", ".mvn",
@@ -202,15 +264,27 @@ async function runRetire(srcDir, opts = {}) {
 	const args = buildRetireArgs({ srcDir, outPath: tmpOut, ignoredDirs, jsRepo: haveSig ? RETIRE_SIG_FILE : null });
 	if (verbose) console.log(`retire: scanning ${srcDir}…${haveSig ? " (local signatures)" : ""}`);
 
+	let execErr = null;
 	try {
 		// retire.js exits with code 13 when it finds vulnerabilities — that's
 		// expected. Catch and ignore the non-zero exit; the JSON file is still
 		// produced.
-		await execFileP(bin, args, { maxBuffer: 1024 * 1024 * 64 });
+		await execFileP(launcher.cmd, args, {
+			maxBuffer: 1024 * 1024 * 64,
+			env: launcher.env ? { ...process.env, ...launcher.env } : process.env,
+		});
 	} catch (err) {
-		// exit code 13 (or anything where the output file exists) is OK
-		if (!fs.existsSync(tmpOut)) {
-			if (verbose) console.warn(`retire: failed to run — ${err.message}`);
+		execErr = err;
+		// exit code 13 (or anything where a non-empty output file exists) is OK.
+		// A missing OR empty (0-byte) output file means retire crashed mid-walk
+		// (e.g. ENOENT on the source path, an unreadable file) — a real failure.
+		let size = -1;
+		try { size = fs.statSync(tmpOut).size; } catch { /* missing */ }
+		if (size <= 0) {
+			const reason = retireFailureReason(err.stderr, err.message);
+			diag.error = `retire.js scan failed: ${reason}`;
+			if (verbose) console.warn(`retire: failed to run — ${reason}`);
+			try { fs.unlinkSync(tmpOut); } catch { /* best effort */ }
 			return null;
 		}
 	}
@@ -220,6 +294,8 @@ async function runRetire(srcDir, opts = {}) {
 		const body = fs.readFileSync(tmpOut, "utf8");
 		parsed = JSON.parse(body);
 	} catch (err) {
+		const reason = retireFailureReason(execErr && execErr.stderr, err.message);
+		diag.error = `retire.js scan failed: ${reason}`;
 		if (verbose) console.warn(`retire: could not parse output — ${err.message}`);
 		return null;
 	} finally {
@@ -262,7 +338,7 @@ function normaliseRetireResults(raw, srcDir) {
 	const files = Array.isArray(raw) ? raw : (raw.data || []);
 	for (const f of files) {
 		const file = f.file;
-		const relFile = srcDir && file?.startsWith(srcDir) ? path.relative(srcDir, file) : file;
+		const relFile = relToSrc(srcDir, file);
 		for (const res of f.results || []) {
 			const component = res.component;
 			const version = res.version;
@@ -319,11 +395,13 @@ async function scanWithRetire(srcDir, opts = {}) {
  * JavaScript"). One retire run feeds both.
  */
 async function scanWithRetireFull(srcDir, opts = {}) {
-	const raw = await runRetire(srcDir, opts);
-	if (!raw) return { matches: [], inventory: [] };
+	const diag = {};
+	const raw = await runRetire(srcDir, { ...opts, diag });
+	if (!raw) return { matches: [], inventory: [], error: diag.error || null };
 	return {
 		matches: normaliseRetireResults(raw, srcDir),
 		inventory: extractVendoredInventory(raw, srcDir),
+		error: null,
 	};
 }
 
@@ -334,9 +412,16 @@ module.exports = {
 	runRetire,
 	normaliseRetireResults,
 	findRetireBin,
+	findRetireLauncher,
+	chooseRetireLauncher,
 	warmRetireSignatures,
 	ensureSignatures,
 	buildRetireArgs,
+	retireFailureReason,
+	readCache,
+	writeCache,
+	cacheKey,
+	RETIRE_CACHE_SCHEMA,
 	RETIRE_CACHE_DIR,
 	RETIRE_SIG_DIR,
 	RETIRE_SIG_FILE,

package/lib/scan-completeness.js

@@ -53,15 +53,24 @@ function detectScanCompletenessWarnings(resolvedDeps, opts = {}) {
 	}
 
 	if (unresolved.length) {
-		// Dedupe by g:a (same coord may appear in several modules)
-		const seenKeys = new Set();
-		const items = [];
+		// Dedupe by g:a (same coord may appear in several modules), MERGING the
+		// manifest paths so the report can show WHERE each unresolved dep is declared.
+		// Items are objects ({ id, manifestPaths }) — renderWarningItems() renders the
+		// "defined in: <pom.xml>" line for that shape (same as the private-libs warning).
+		const byKey = new Map();
 		for (const d of unresolved) {
 			const k = `${d.groupId}:${d.artifactId}`;
-			if (seenKeys.has(k)) continue;
-			seenKeys.add(k);
-			items.push(`${k}${d.version ? " (" + d.version + ")" : " (no version resolved)"}`);
+			const paths = (d.manifestPaths && d.manifestPaths.length) ? d.manifestPaths
+				: (d.pomPaths && d.pomPaths.length) ? d.pomPaths
+				: [];
+			let entry = byKey.get(k);
+			if (!entry) {
+				entry = { id: `${k}${d.version ? " (" + d.version + ")" : " (no version resolved)"}`, manifestPaths: [] };
+				byKey.set(k, entry);
+			}
+			for (const p of paths) if (!entry.manifestPaths.includes(p)) entry.manifestPaths.push(p);
 		}
+		const items = [...byKey.values()];
 		warnings.push({
 			type: "unresolved-versions",
 			count: items.length,

package/lib/ui.js

@@ -17,11 +17,12 @@ const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇",
 const TITLE_A = "fad-checker";
 const TITLE_B = "Autonomous Dependency Checker";
 
-function banner() {
-	const raw = `${TITLE_A} · ${TITLE_B}`;
+function banner(version) {
+	const ver = version ? `v${version}` : "";
+	const raw = `${TITLE_A} ${ver} · ${TITLE_B}`.replace("  ", " ");
 	const bar = "─".repeat(raw.length + 2);
 	console.log(chalk.cyan(`\n╭${bar}╮`));
-	console.log(chalk.cyan("│ ") + chalk.bold.white(TITLE_A) + chalk.cyan(" · ") + chalk.whiteBright(TITLE_B) + chalk.cyan(" │"));
+	console.log(chalk.cyan("│ ") + chalk.bold.white(TITLE_A) + (ver ? " " + chalk.dim(ver) : "") + chalk.cyan(" · ") + chalk.whiteBright(TITLE_B) + chalk.cyan(" │"));
 	console.log(chalk.cyan(`╰${bar}╯`));
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fad-checker",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Scan ALL Maven, npm, Yarn, Composer, Python, C#/.NET, Go & Ruby dependencies — plus embedded JARs (fat-jars/war/ear) — in a source tree ONE SHOT without mvn/python/etc — CVE (EPSS/KEV-prioritised), EOL, obsolete, outdated & licenses, with SBOM/CSAF/SARIF/JSON exports, CI gating and fix recos",
   "keywords": [
     "sca",