fad-checker 2.4.3 → 2.4.5

package/AI_POLICY.md

@@ -0,0 +1,74 @@
+# AI policy
+
+## How this project is built
+
+`fad-checker` is based on a personal project then enhanced with heavy use of Claude Code. `CLAUDE.md` in the repo root is exactly
+what it looks like: the orientation map the assistant works from.
+
+I would rather state that plainly than have someone discover it and wonder what else was not
+said. For a security tool the provenance of the code is a fair question, so here is what the
+work is actually held to.
+
+## What the code is held to
+
+None of this is a claim about how the code was written. All of it is checkable by you:
+
+- **606 tests**, run with `npm test`. No test touches the network.
+- **`test/offline-guarantee.test.js`** is a tripwire: it installs a fetcher that throws if
+  anything reaches for the network under `--offline`, on a cold cache. The zero-network
+  guarantee is a test, not a promise. It is also reproducible outside the suite:
+  `unshare -rn node fad-checker.js -s ./proj --offline` runs in a namespace with no network
+  interface at all.
+- **Incremental history.** The work is spread across the commit log, not dropped in one
+  initial commit.
+- **Measured, not asserted.** Coverage numbers in the docs come from comparison against a
+  Snyk baseline on a real multi-module project, with the methodology stated where they appear.
+- **Fixtures come from real-world shapes.** Parsing behaviour is locked by a fixture in
+  `test/fixtures/`, derived from a manifest layout that actually occurs, not from an
+  invented one.
+
+The honest counterweight: this is a young single-maintainer project and it has false positives
+and false negatives. The [README says so](README.md), and the
+[accuracy issue template](.github/ISSUE_TEMPLATE/false_positive.yml) exists because those
+reports are the most valuable thing the project can receive.
+
+## Where review actually mattered
+
+One example, because it is the kind of failure that matters for a scanner.
+
+The first implementation of per-module Maven version mediation
+(`lib/version-overlay.js`) re-resolved each module using only that module's own
+`<dependencies>`. That is wrong: Maven inherits `<dependencies>` from the parent chain into
+every child, where they stay direct and beat any transitive of the same coordinate. The
+consequence was that a parent-declared, reactor-wide remediation was invisible, so the overlay
+"recovered" the very version that remediation overrides, and reported CVEs against a version
+no classpath holds.
+
+Fabricating findings is worse for a security tool than missing them. The fix walks the local
+parent chain, and `test/version-overlay-inherited-direct.test.js` locks the behaviour in both
+directions: the masked version must surface, and the overridden one must not.
+
+The general rule this project follows: a plausible-looking finding is not a finding. Unresolved
+versions are excluded from matching rather than assumed vulnerable, CPE configurations are
+cross-checked against the actual version, and there is no `!version means affected` shortcut
+anywhere in the matcher.
+
+## What is expected of contributions
+
+The same bar, regardless of how the code was produced:
+
+- A test that fails before the change and passes after it.
+- For parsing changes, a fixture derived from a real-world shape.
+- No claim in the docs that is not backed by something a reader can run.
+- You understand the change well enough to explain it in review without assistance.
+
+Use whatever tools you like to get there. What is not welcome is a change whose author cannot
+answer questions about it, because reviewing that costs more than writing it did. See
+[`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Reports generated by this tool
+
+`fad-checker` uses **no LLM at runtime**. Findings come from public vulnerability databases
+(CVEProject, OSV.dev, NVD), registry metadata and deterministic parsers. Severity, priority and
+version matching are computed, not generated. Nothing in a report is written by a language
+model, and the tool makes no network call to any AI service, ever.

package/CHANGELOG.md

@@ -5,7 +5,178 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Added
+- **`--nvd-cpe-match` (opt-in, off by default): match dependencies against NVD's CPE version
+  ranges.** OSV/GHSA declare affected ranges per release *branch*; NVD declares them for every
+  affected branch. For `CVE-2020-9546`, OSV covers 2.9.0–2.9.10.4 while NVD also covers
+  2.0.0–2.7.9.7 — so `jackson-databind:2.5.2` is affected and never got a fix. fad already had
+  that data in its NVD cache and only ever used it **subtractively**, to filter false positives.
+  This uses it additively, restricted to coordinates with an **unambiguous 1:1** entry in
+  `data/cpe-coord-map.json` (no name heuristics), and only for CVEs already enriched, so it adds
+  no network path.
+
+  **It is off by default because its measured precision is poor, and the reason is structural.**
+  On Apache Dubbo 2.7.8 it adds 76 findings of which **9 (12%) are corroborated by Snyk**. CPE
+  products are *framework*-level (`spring_framework`, `netty`, `log4j`) while Maven coordinates
+  are *artifact*-level, so a framework CVE lands on every artifact of that framework —
+  `CVE-2016-1000027` is a spring-web flaw and CPE puts it on spring-core, `CVE-2019-20444` is
+  netty-codec-http and CPE puts it on netty-common. Curation cannot fix a granularity mismatch;
+  allowing the map's deliberate 1:N entries made it worse still (262 findings, 8% corroborated).
+  Shipped as a triage aid ("what might I be missing?"), never as a default. Locked by
+  `test/nvd-cpe-match.test.js`, including a test asserting that a coordinate with no curated
+  entry is not matched even when the name heuristic would have accepted it.
+
+  The investigation behind it also settled what fad's 118 benchmark misses actually are, and
+  the answer is not flattering: **they are real misses, not the other scanner's noise.** All 87
+  public-CVE ones were checked against NVD — 7 confirmed, 13 where NVD's own range disagrees,
+  67 where NVD names no CPE for the artifact. Both minorities were traced. The "NVD is silent"
+  bulk are public-database coverage gaps: `CVE-2023-6481` on `logback-classic@1.2.2` exists in
+  OSV with **no Maven package binding at all** (only a GIT range), while its own fixed-version
+  list `1.2.12, 1.3.13, 1.4.13` shows the 1.2.x branch was affected and fixed at 1.2.12 — so
+  1.2.2 is vulnerable and no public-source scanner can see it. The "NVD contradicts" cases are
+  NVD contradicting itself: sibling jackson-databind gadget CVEs published weeks apart declare
+  `2.0.0–2.7.9.7 / 2.8.0–2.8.11.6 / 2.9.0–2.9.10.4` (CVE-2020-9546) versus `2.9.0–2.9.10.4`
+  alone (CVE-2020-10672). Public advisory data declares ranges per release *branch* and old
+  unpatched branches are routinely absent; a hand-curated commercial database fills that in and
+  aggregating public sources does not reproduce it. Documented in `docs/BENCHMARK.md` rather
+  than left as "not yet diagnosed".
+
 ### Fixed
+- **An imported BOM's `<properties>` leaked into the importing project — and won.**
+  `<scope>import</scope>` imports a BOM's `<dependencyManagement>` and **nothing else**: the
+  BOM resolves its managed versions in its own property context, and its `<properties>` never
+  become the importer's. `core.js` merged them, and merged them so the BOM won
+  (`{...merged.properties, ...imported.properties}`), so a BOM silently redefined the
+  importing project's own property values. On Apache Dubbo 2.7.8 the reactor root sets
+  `<hibernate_validator_version>5.2.4.Final</hibernate_validator_version>` and
+  `dubbo-dependencies-bom` redefines it to `5.4.1.Final`, so `dubbo-filter-validation`'s
+  `<version>${hibernate_validator_version}</version>` resolved to the wrong version — and a
+  different version is a different CVE set. (`mvn dependency:tree` reports
+  `hibernate-validator:jar:5.2.4.Final:test` for that module.) The BOM's managed entries are
+  now interpolated against the BOM's own properties at the import boundary and the properties
+  are dropped, mirroring what `transitive.js#effectivePom` already did for EXTERNAL import
+  BOMs. Locked by `test/bom-property-leak.test.js`, which guards both directions: the leak
+  must stop **and** importing a BOM must still supply managed versions.
+- **A version declared only at test scope is now reported as dev.** `isDev` lives on the
+  coord-wide record, so a version declared solely at `<scope>test</scope>` inherited the
+  coordinate's production flag whenever the same coordinate was production at some other
+  version — counting toward the production total and the `--fail-on` gate. Per-version scopes
+  are now recorded next to per-version paths (`versionScopes`, mirror of `versionPaths`), and
+  attribution applies the same widest-wins rule already used for overlay-recovered versions.
+  On Dubbo, `hibernate-validator:5.2.4.Final` moves to the dev chapter, attributed to
+  `dubbo-filter-validation` — exactly what Maven reports.
+
+  Air-gapped recall on the public benchmark reaches **657/657 (100%)** of OSV-Scanner's own
+  online finding set, up from 653.
+
+### Changed
+- **The benchmark now measures every scanner at full capability, not just air-gapped.**
+  `docs/BENCHMARK.md` carries two tables, because they answer different questions. **Full
+  capability** (all five online, best configuration, populated `~/.m2`, union 908 pairs):
+  fad-checker 790 (87.0%), OSV-Scanner 657, Snyk 603, Trivy 546, Grype+Syft 45. **No tool
+  finds everything, fad included** — its 118 misses all come from Snyk, 30 of them under a
+  proprietary `SNYK-*` id no public database carries, and **88 genuine public-CVE misses that
+  remain undiagnosed**. **No network** (`unshare -rn`, against OSV-Scanner's online output):
+  fad 657/657, Grype+Syft 45, Trivy 40, OSV-Scanner 37.
+  Also documented: Trivy's result is identical online and with a fully populated `~/.m2` (the
+  local repository substitutes for the network entirely), Grype+Syft does not move at all
+  between default and fully-enabled configuration, and the `settings.xml` mirror trick for
+  reproducing the run when Maven Central rate-limits the IP.
+- **The per-module overlay could not recover a version held only on a TEST classpath.**
+  The overlay exists because the global transitive pass dedupes by `g:a` across the whole
+  reactor and keeps one version per coordinate — but it hardcoded
+  `includedScopes: ["compile","runtime","provided"]`, so a version reachable only through a
+  test-scoped dependency was structurally unreachable. Measured on Apache Dubbo 2.7.8, this
+  one omission accounted for **every one** of the 78 findings OSV-Scanner reported that fad
+  missed (`jackson-databind:2.8.4:test` in dubbo-registry-sofa,
+  `hibernate-validator:5.2.4.Final:test` in dubbo-filter-validation, `okhttp:3.11.0` /
+  `okio:1.14.0` in dubbo-configcenter-apollo, `commons-compress:1.18:test` in
+  dubbo-remoting-etcd3 — each verified against `mvn dependency:tree`).
+  Air-gapped recall on that project: **579 → 653 of 657 (88.1% → 99.4%)**, production
+  findings unchanged at 651, dev findings 11 → 147, **zero production finding lost**.
+- **A version is now dev only when EVERY module resolving it does so at test scope.**
+  On Dubbo, `jackson-databind:2.10.4` is test-scoped in `dubbo-config-spring` but
+  **compile**-scoped in `dubbo-configcenter-nacos`. Reading the first recorded provenance
+  called the version dev and dropped a genuine production finding out of the count and out
+  of the `--fail-on` gate.
+- **The overlay records provenance per module even when the version is already known.**
+  It used to `continue` on the first module to contribute a version, so a second module
+  resolving the same version at a different scope left no trace at all — which is exactly
+  what made the previous item invisible.
+- **A DECLARED version now wins over any transitive provenance for the same version.**
+  `xstream:1.4.10` is declared outright in `dubbo-registry-eureka` *and* reached as a
+  test-scoped transitive of `dubbo-config-api`; letting the transitive provenance win
+  demoted 35 findings, one of them KEV, into the dev chapter. A manifest that writes
+  `<version>` for a coordinate is the authority on that version.
+
+### Previously fixed
+- **The transitive closure of a test-scoped dependency was never scanned.** Maven's scope
+  matrix says `test → compile = test`: the compile dependencies of a test-scoped dependency
+  are on the test classpath, and so are theirs, recursively (only `test → test` is omitted).
+  `expandWithTransitives` passed test-scoped roots into resolution (`includeTestDeps`, on
+  unless `--ignore-test`) but `resolveTransitiveDeps` then filtered accepted propagated
+  scopes to `compile/runtime/provided`, so **every child of a test root was discarded at the
+  first hop**. Net effect: the dev chapter only ever listed *directly declared* test
+  dependencies, never their transitives. On Apache Dubbo 2.7.8 this hid
+  `spring-boot:1.5.17.RELEASE` and `spring-boot-autoconfigure:1.5.17.RELEASE`, four hops down
+  `registry-test → registry-server-integration → spring-boot-starter`, all of which
+  `mvn dependency:tree` reports at scope=test.
+- **Scope is now widened, never narrowed, when a coord is reached by several paths.** This is
+  the half of the fix above that matters most. The traversal dedupes by `g:a` and keeps the
+  first chain walked, so marking everything under a test root as dev let **BFS order decide
+  the scope**: a coordinate reachable from *both* a test root and a compile root got stamped
+  test if the test path happened to be walked first. Measured: 6 production findings
+  (`spring-core:4.3.16.RELEASE`, `commons-lang:2.6`, …) silently moved into the dev chapter,
+  dropping out of the production count **and out of the `--fail-on` gate**. A false negative
+  on the production classpath is worse than the gap being fixed. A revisit now upgrades
+  `test` to the wider propagated scope and never the reverse. Locked by
+  `test/transitive-test-scope.test.js` (6 tests, including the both-paths case and the
+  `test → test` omission).
+  Net on Dubbo: **575 → 579** recovered pairs, production findings **unchanged at 650**, dev
+  findings 7 → 11.
+- **Maven hard-pin versions (`[1.2.3]`) are now normalised to the bare version.**
+  Maven's `[x]` syntax means *exactly* x — a concrete version wearing range brackets —
+  and real upstream POMs use it (`io.grpc:grpc-netty:1.22.1` declares
+  `<version>[4.1.35.Final]</version>`). fad kept the brackets verbatim, so the coordinate
+  was wrong **everywhere downstream**: the report, the purl, and every SBOM/CSAF/SARIF/JSON
+  export carried `netty-codec-http2@[4.1.35.Final]`, which cannot be joined with any other
+  tool's output for the same dependency. Fixed by `lib/maven-version.js#normalizeHardPin`,
+  applied on both paths that produce a version — `cve-match.js#resolveDepVersion` (declared
+  deps, after `${…}` interpolation, so `[${netty.version}]` works) and `lib/transitive.js`
+  (deps read out of upstream POMs, which is where this actually came from). A **genuine
+  range keeps its brackets**: choosing a version out of `[1.0,2.0)` is resolution, not
+  normalisation, and it must keep surfacing as unresolved rather than silently becoming
+  concrete. Found by the new public benchmark, where it cost **9 recovered findings**
+  (566 → 575 of OSV-Scanner's reference set on Apache Dubbo 2.7.8). Note that the OSV cache
+  is keyed by coordinate **and** version, so this fix invalidates entries warmed under the
+  old string — an offline re-run needs a cache re-warm to see the corrected coordinate.
+- **Docs referenced a `--transitive` flag that does not exist.** Transitive resolution is
+  **on by default**; `--no-transitive` disables it. Corrected in `ARCHITECTURE.md` and
+  `COMPARISON.md`.
+
+### Added
+- **`docs/BENCHMARK.md` — a reproducible air-gapped recall benchmark.** Replaces the
+  unverifiable private-project figure that headlined the README. Measured on **Apache Dubbo
+  2.7.8** (105-module reactor, pinned commit), with both scanners run under `unshare -rn` in
+  a namespace with **no network interface**, and graded against **OSV-Scanner's own online
+  output** as the reference set (657 distinct `package@version | vulnerability` pairs) rather
+  than against fad's own notion of a finding: **fad-checker recovers 575 (87.5%)**,
+  **OSV-Scanner recovers 37 (5.6%)**. Documents the exact commands, the tool versions, the
+  82 pairs fad misses **and why** (version-mediation divergence, plus two genuinely
+  unresolved `spring-boot` coordinates), and the caveats — a warmed cache is required, and
+  one project is one shape.
+
+### Changed
+- `docs/COMPARISON.md`: four competitor cells corrected after re-verification against
+  upstream docs and source. Syft **does** have Maven transitive resolution
+  (`java.resolve-transitive-dependencies`, opt-in, off by default); Trivy consults a local
+  `~/.m2` before the network; Trivy **does** report end-of-service-life, but only for OS
+  distributions (the EOL row is now scoped to *application* frameworks); and the
+  "scan without exposing the codebase" row now concedes the SBOM-then-scan-online route,
+  keeping only the two differences that are sourceable. Adds a version stamp for every tool
+  compared and an explicit note that no ⚠️/❌ cell means "unmaintained".
+
+### Previously fixed
 - **External `<parent>` POMs (spring-boot-starter-parent) now backfill their managed
   versions.** A versionless dep whose version is inherited from an external `<parent>`
   (e.g. `spring-boot-starter-actuator` under `spring-boot-starter-parent`, whose own

package/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing
+
+Thanks for looking. This is a young single-maintainer project, so the most valuable
+contribution isn't necessarily code — it's **telling me where the output is wrong**.
+
+## The most useful thing you can do
+
+Run it on a real project and report what it got wrong:
+
+```bash
+npx fad-checker -s ./your-project
+```
+
+A [false positive / false negative report](https://github.com/9pings/fad-checker/issues/new?template=false_positive.yml)
+with the coordinate and the manifest snippet that produced it is worth more than a feature
+request. Dependency resolution has a long tail of real-world shapes — inherited BOMs, profile
+matrices, `replace` directives, vendored jars — and the only way to cover them is to be shown
+one that breaks.
+
+## Development setup
+
+Node ≥ 20, no other tooling required.
+
+```bash
+npm install
+npm test                      # 606 tests via node --test
+node --test test/core.test.js # a single file
+node fad-checker.js -s test/fixtures/monorepo-mixed --offline --no-report
+```
+
+Building the single-file binaries needs [bun](https://bun.sh): `npm run build`.
+
+## Ground rules for changes
+
+- **Tests must not touch the network.** Every fixture-driven test drives an in-memory
+  registry/fetcher. `test/offline-guarantee.test.js` is a tripwire that fails if any code path
+  reaches for the network under `--offline` — don't work around it.
+- **Add a fixture, not just an assertion.** New parsing behaviour belongs in
+  `test/fixtures/`, next to the shapes that already live there.
+- **A parse failure must never kill the run.** One malformed manifest logs a warning and the
+  scan continues; there is no `process.exit(1)` mid-pipeline.
+- **New ecosystem = new codec.** Implement the interface in
+  `lib/codecs/codec.interface.js`, register it, and the orchestrator needs no edits. See
+  [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+- Commit messages follow Conventional Commits (`fix(maven): …`, `feat(gradle): …`).
+- [`CLAUDE.md`](CLAUDE.md) is the code-level orientation map — conventions, invariants and the
+  reasoning behind the non-obvious ones. Read it before a non-trivial change; it will save you
+  from "simplifying" something that's load-bearing.
+
+## On AI-assisted development
+
+This codebase is written with heavy use of Claude Code, and I'm not going to pretend
+otherwise — `CLAUDE.md` in the repo root is exactly what it looks like. What I ask of my own
+changes and of contributions is the same either way: a test that fails before and passes
+after, a fixture derived from a real-world shape, and no claim in the docs that isn't backed
+by something you can run. If you find a place where the code doesn't meet that bar, that's a
+bug report I want.
+
+## Reporting a vulnerability in fad-checker itself
+
+See [`SECURITY.md`](SECURITY.md) — please report privately, not as a public issue.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pp9Ping
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,34 +2,35 @@
 
 [![npm version](https://img.shields.io/npm/v/fad-checker.svg)](https://www.npmjs.com/package/fad-checker)
 [![npm downloads](https://img.shields.io/npm/dm/fad-checker.svg)](https://www.npmjs.com/package/fad-checker)
-[![license](https://img.shields.io/npm/l/fad-checker.svg)](https://github.com/9pings/fad-checker/blob/main/package.json)
+[![license](https://img.shields.io/npm/l/fad-checker.svg)](LICENSE)
 [![node](https://img.shields.io/node/v/fad-checker.svg)](https://nodejs.org)
+[![CI](https://github.com/9pings/fad-checker/actions/workflows/ci.yml/badge.svg)](https://github.com/9pings/fad-checker/actions/workflows/ci.yml)
 
 > **F**abulous **A**utonomous **D**ependency **C**hecker<br>
 > AKA **F**uckin' **A**utonomous **D**ependency **C**hecker<br>
 
-`fad-checker` audits **Maven · Gradle · npm · Yarn · pnpm · Composer · PyPI · NuGet · Go · Ruby**, vendored JavaScript, committed native binaries and cryptographic material (certificates & private/public keys) in any source tree — multi-module, monorepo, polyglot — and produces a self-contained **HTML + Word report** (CVE prioritised by EPSS + CISA KEV, EOL, obsolete, outdated, licenses) plus **CycloneDX SBOM / CSAF VEX / SARIF / JSON** exports. **No build tools, no Docker, no network needed** — it reads lockfiles and manifests straight off disk.
+`fad-checker` audits **Maven · Gradle · npm · Yarn · pnpm · Composer · PyPI · NuGet · Go · Ruby**, vendored JavaScript, committed native binaries and cryptographic material (certificates & private/public keys) in any source tree; multi-module, monorepo, polyglot; and produces a self-contained **HTML + Word report** (CVE prioritised by EPSS + CISA KEV, EOL, obsolete, outdated, licenses) plus **CycloneDX SBOM / CSAF VEX / SARIF / JSON** exports. **No build tools, no Docker, no network needed**; it reads lockfiles and manifests straight off disk.
 
 🌐 **[Project site & docs →](https://9pings.github.io/fad-checker/)**
 
 > [!WARNING]
-> **Young project — expect rough edges.** fad-checker is new and under active development, so it may still contain bugs (including false positives and false negatives). Treat its output as a strong first pass, **double-check anything critical**, and please [report issues](https://github.com/9pings/fad-checker/issues) — they get fixed fast.
+> **Young project; expect rough edges.** fad-checker is new and under active development, so it may still contain bugs (including false positives and false negatives). Treat its output as a strong first pass, **double-check anything critical**, and please [report issues](https://github.com/9pings/fad-checker/issues); they get fixed fast.
 
-<p align="center"><img src="docs/assets/demo.gif" alt="fad-checker animated terminal demo — a [n/N] checklist warming each vulnerability database, then CVE findings coloured by severity with KEV badges" height="600"></p>
+<p align="center"><img src="docs/assets/demo.gif" alt="fad-checker animated terminal demo; a [n/N] checklist warming each vulnerability database, then CVE findings coloured by severity with KEV badges" height="600"></p>
 
 ## Features
 
-- **10 ecosystems in one pass** — Maven, **Gradle**, npm/Yarn/pnpm, Composer (PHP), PyPI, NuGet, Go, Ruby; plus **vendored JS** (retire.js), committed **native binaries** (`.dll`/`.exe`/`.so`/`.dylib`, identified by checksum via deps.dev + CIRCL) and **embedded JARs** (fat-jars/war/ear, unzipped in-memory).
-- **Crypto material** — committed **certificates** (X.509, PEM/DER), **private &amp; public keys** (PEM / OpenSSH every algorithm / PuTTY / PGP / one-line SSH) and **keystores** (JKS/JCEKS/PKCS#12). Each key is labelled **private** (a committed secret → critical) or **public**; certs are checked for **expiry, weak key (RSA<2048), weak signature (MD5/SHA1) and self-signed** — all parsed offline with the built-in X.509 parser, no network. `--no-certs` to disable.
-- **No build tools** — reads `pom.xml`, `build.gradle(.kts)`/`gradle.lockfile`/`libs.versions.toml`, `package-lock`/`yarn.lock`/`pnpm-lock`, `composer.lock`, `poetry`/`Pipfile`/`uv`/`pdm` locks, `packages.lock.json`/`*.csproj`, `go.mod`, `Gemfile.lock` directly. No `mvn`/`gradle`/`npm install`/`pip`/`dotnet restore`/`go build`/`bundle`, no `node_modules/`. → [how it stays build-free](docs/COMPARISON.md#how-its-autonomous-no-build-tools)
-- **CVE, merged & prioritised** — CVEProject + OSV.dev + NVD, CPE/version cross-checked to cut false positives, ranked **CISA KEV → EPSS → CVSS**.
-- **Per-module Maven version mediation** — recovers vulnerable transitive versions that a global `<dependencyManagement>` pin hides in another module (lifted Snyk-corroborated coverage **156 → 181** on a real 25-module reactor, finding CVEs a single Snyk scan missed).
-- **Air-gapped** — **zero network under `--offline`** (regression-tested), offline Maven transitive resolution, and `--osv-db` for cache-independent offline OSV recall. → [Air-gapped](#air-gapped-audits)
-- **Supply-chain risk** — known-**malicious** advisories (`MAL-`, always block the CI gate) + suspected **typosquats** (`--typosquat`).
-- **Lifecycle** — EOL (endoflife.date), obsolete/deprecated, outdated — across every ecosystem.
-- **Licenses** *(opt-in `--licenses`)* — SPDX-normalised, copyleft/proprietary flagged.
-- **Audit-grade & reproducible** — every report carries a **provenance manifest** (data-source freshness + run config) and a **Methodology, data sources & limitations** chapter; artifacts ship a **`SHA256SUMS`** integrity manifest (`sha256sum -c`); **differential audits** diff against a prior run (`--baseline`, or `fad diff a.json b.json`) and CI can gate on *new* findings (`--fail-on-new`).
-- **Outputs & CI** — HTML + Word `.doc`, CycloneDX 1.6 SBOM, CSAF 2.0 VEX, SARIF 2.1.0, JSON; gate with `--fail-on` / `--fail-on-new`, triage with `--ignore`/`--vex`. Private registries for Maven, npm, PyPI, Ruby, Go, **NuGet** and **Composer**.
+- **10 ecosystems in one pass**; Maven, **Gradle**, npm/Yarn/pnpm, Composer (PHP), PyPI, NuGet, Go, Ruby; plus **vendored JS** (retire.js), committed **native binaries** (`.dll`/`.exe`/`.so`/`.dylib`, identified by checksum via deps.dev + CIRCL) and **embedded JARs** (fat-jars/war/ear, unzipped in-memory).
+- **Crypto material**; committed **certificates** (X.509, PEM/DER), **private &amp; public keys** (PEM / OpenSSH every algorithm / PuTTY / PGP / one-line SSH) and **keystores** (JKS/JCEKS/PKCS#12). Each key is labelled **private** (a committed secret → critical) or **public**; certs are checked for **expiry, weak key (RSA<2048), weak signature (MD5/SHA1) and self-signed**; all parsed offline with the built-in X.509 parser, no network. `--no-certs` to disable.
+- **No build tools**; reads `pom.xml`, `build.gradle(.kts)`/`gradle.lockfile`/`libs.versions.toml`, `package-lock`/`yarn.lock`/`pnpm-lock`, `composer.lock`, `poetry`/`Pipfile`/`uv`/`pdm` locks, `packages.lock.json`/`*.csproj`, `go.mod`, `Gemfile.lock` directly. No `mvn`/`gradle`/`npm install`/`pip`/`dotnet restore`/`go build`/`bundle`, no `node_modules/`. → [how it stays build-free](docs/COMPARISON.md#how-its-autonomous-no-build-tools)
+- **CVE, merged & prioritised**; CVEProject + OSV.dev + NVD, CPE/version cross-checked to cut false positives, ranked **CISA KEV → EPSS → CVSS**.
+- **Per-module Maven version mediation**; recovers vulnerable transitive versions that a global `<dependencyManagement>` pin hides in another module, applying Maven's own nearest-wins semantics per module rather than resolving the whole reactor as one tree.
+- **Air-gapped**; **zero network under `--offline`** (regression-tested), offline Maven transitive resolution, and `--osv-db` for cache-independent offline OSV recall. Benchmarked on **Apache Dubbo 2.7.8** (105 modules) against OSV-Scanner, Snyk, Trivy and Grype+Syft: at **full capability** fad finds 790 of a 908-pair union (87%, the highest of the five, and it still misses 118 that Snyk finds); **under `unshare -rn` with no network interface** it recovers **657/657** of OSV-Scanner's *online* result, versus 45 / 40 / 37 for the others. → [Benchmark](docs/BENCHMARK.md) · [Air-gapped](#air-gapped-audits)
+- **Supply-chain risk**; known-**malicious** advisories (`MAL-`, always block the CI gate) + suspected **typosquats** (`--typosquat`).
+- **Lifecycle**; EOL (endoflife.date), obsolete/deprecated, outdated; across every ecosystem.
+- **Licenses** *(opt-in `--licenses`)*; SPDX-normalised, copyleft/proprietary flagged.
+- **Audit-grade & reproducible**; every report carries a **provenance manifest** (data-source freshness + run config) and a **Methodology, data sources & limitations** chapter; artifacts ship a **`SHA256SUMS`** integrity manifest (`sha256sum -c`); **differential audits** diff against a prior run (`--baseline`, or `fad diff a.json b.json`) and CI can gate on *new* findings (`--fail-on-new`).
+- **Outputs & CI**; HTML + Word `.doc`, CycloneDX 1.6 SBOM, CSAF 2.0 VEX, SARIF 2.1.0, JSON; gate with `--fail-on` / `--fail-on-new`, triage with `--ignore`/`--vex`. Private registries for Maven, npm, PyPI, Ruby, Go, **NuGet** and **Composer**.
 
 📖 **[Usage & all flags](docs/USAGE.md)** · **[Architecture](docs/ARCHITECTURE.md)** · **[Comparison vs other tools](docs/COMPARISON.md)** · **[Data sources](docs/DATA-SOURCES.md)**
 
@@ -40,18 +41,25 @@ npm install -g fad-checker
 fad-checker -s ./my-project          # → ./fad-checker-report/cve-report.html
 ```
 
-A free [NVD API key](https://nvd.nist.gov/developers/request-an-api-key) (instant) gives 10× faster enrichment: `fad-checker --set-nvd-key YOUR_KEY`. A few common runs — full list via `fad-checker --help` or [docs/USAGE.md](docs/USAGE.md):
+A free [NVD API key](https://nvd.nist.gov/developers/request-an-api-key) (instant) gives 10× faster enrichment: `fad-checker --set-nvd-key YOUR_KEY`. A few common runs; full list via `fad-checker --help` or [docs/USAGE.md](docs/USAGE.md):
 
 ```bash
 fad-checker -s ./proj -e "^com\.acme\."                        # exclude private libs (coord regex)
 fad-checker -s ./proj -t ../clean -e "^com\.acme\." --snyk     # cleaned POM tree + merge Snyk
-fad-checker -s ./proj --offline                                # fully offline (zero network)
+fad-checker -s ./proj --offline                                # fully offline (zero network, needs a warmed cache)
 fad-checker -s ./proj --osv-db --typosquat                     # offline-complete OSV + typosquat
 fad-checker -s ./proj --licenses --fail-on high                # license chapter + CI gate
 fad-checker -s ./proj --report-json --baseline last.json --fail-on-new   # differential audit: fail CI on NEW findings
 fad-checker diff last.json this.json                           # standalone diff of two findings JSONs
 ```
 
+> [!IMPORTANT]
+> **`--offline` reads the cache, it doesn't replace it.** On a *cold* cache there is nothing to
+> match against, so an offline first run legitimately reports **0 CVE / 0 EOL / 0 outdated**;
+> that's an empty cache, not a clean project. Warm it once (a normal online run on any project,
+> or `--import-cache`), then `--offline` returns the full result set with zero network calls.
+> Air-gapped machines get their cache via [`--export-cache` / `--import-cache`](#air-gapped-audits).
+
 A single self-contained binary (no Node), from-source install and shell completion are in → [docs/USAGE.md](docs/USAGE.md).
 
 ## What it finds
@@ -61,51 +69,51 @@ The report is organised into **root chapters** (each grouping related sub-chapte
 | Chapter | Source | What it catches |
 | --- | --- | --- |
 | **0. Warnings** *(top)* | local heuristics | Missing lockfiles, unresolved Maven versions (BOM-managed), private libs not on Maven Central |
-| **Δ. Changes since baseline** *(top, with `--baseline`)* | diff vs prior JSON | New / fixed / unchanged findings per category + the list of **new production CVEs** — for repeat audits and `--fail-on-new` CI gating |
-| **1. CVE** *(X direct, Y indirect, Z dev)* | CVEProject + OSV.dev + NVD + CPE | **1.1 Production** — public CVE / GHSA in prod deps, per ecosystem, per manifest, **prioritised** by CISA KEV + EPSS + CVSS · **1.2 Vendored JS vulns** ([retire.js](https://retirejs.github.io/)) · **1.3 Dev** (`test`/`provided`, `dev`/`optional`/`peer`) · **1.4 Likely false positives** (CPE-filtered) |
-| **2. Unmanaged / unversioned components** | deps.dev + CIRCL (by checksum), retire.js, built-in X.509 | **2.1 Embedded binaries** — CVEs in libs shipped inside committed `.jar`/`.war`/`.ear` (fat-jars, shaded uber-jars) · **2.2 Native binaries** (`.dll`/`.exe`/`.so`/`.dylib`) identified by hash, flagged should-be-managed / name≠checksum / unknown / malicious · **2.3 Vendored JavaScript** inventory (jQuery, Bootstrap, …) vulnerable *or not* · **2.4 Certificates &amp; key material** — committed certs (expiry / weak key / weak signature / self-signed), **private vs public keys** (PEM/OpenSSH/PuTTY/PGP/SSH) and keystores, all parsed offline |
+| **Δ. Changes since baseline** *(top, with `--baseline`)* | diff vs prior JSON | New / fixed / unchanged findings per category + the list of **new production CVEs**; for repeat audits and `--fail-on-new` CI gating |
+| **1. CVE** *(X direct, Y indirect, Z dev)* | CVEProject + OSV.dev + NVD + CPE | **1.1 Production**; public CVE / GHSA in prod deps, per ecosystem, per manifest, **prioritised** by CISA KEV + EPSS + CVSS · **1.2 Vendored JS vulns** ([retire.js](https://retirejs.github.io/)) · **1.3 Dev** (`test`/`provided`, `dev`/`optional`/`peer`) · **1.4 Likely false positives** (CPE-filtered) |
+| **2. Unmanaged / unversioned components** | deps.dev + CIRCL (by checksum), retire.js, built-in X.509 | **2.1 Embedded binaries**; CVEs in libs shipped inside committed `.jar`/`.war`/`.ear` (fat-jars, shaded uber-jars) · **2.2 Native binaries** (`.dll`/`.exe`/`.so`/`.dylib`) identified by hash, flagged should-be-managed / name≠checksum / unknown / malicious · **2.3 Vendored JavaScript** inventory (jQuery, Bootstrap, …) vulnerable *or not* · **2.4 Certificates &amp; key material**; committed certs (expiry / weak key / weak signature / self-signed), **private vs public keys** (PEM/OpenSSH/PuTTY/PGP/SSH) and keystores, all parsed offline |
 | **3. Maintenance / lifecycle** *(X EOL, Y obsolete, Z outdated)* | endoflife.date · curated + registry flags · Maven Central / npm / Packagist / PyPI / NuGet | **3.1 End-of-Life** frameworks · **3.2 Obsolete / deprecated / abandoned / yanked** · **3.3 Outdated** (newer version available, with release dates) |
 | **4. 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 |
 | **5. Fix Recommendations** | computed | Per-ecosystem pin recipes: Maven `<dependencyManagement>`, Gradle `constraints { }`, npm `overrides`, yarn `resolutions`, `composer require`, `pip install`, `dotnet add package` |
 | **6. Scan context & limitations** | provenance manifest + walk | **6.1 Scanned descriptors** (every manifest parsed) · **6.2 Ignored directories** (pruned paths + rule) · **6.3 Methodology, data sources & limitations** (data-source freshness, run config, explicit statement of **what fad-checker does *not* assess**) |
-| **Supply-chain risk** *(cross-cutting)* | OSV `MAL-…` + name heuristic | **Known-malicious** packages (always block the CI gate, any `--fail-on` level) and **suspected typosquats** (`--typosquat`: an npm/PyPI name one edit from a popular package — `lodahs`↔`lodash`) |
+| **Supply-chain risk** *(cross-cutting)* | OSV `MAL-…` + name heuristic | **Known-malicious** packages (always block the CI gate, any `--fail-on` level) and **suspected typosquats** (`--typosquat`: an npm/PyPI name one edit from a popular package; `lodahs`↔`lodash`) |
 
 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.
 
-<p align="center"><img src="docs/assets/report.png" alt="fad-checker HTML report — executive summary with severity tiles and a detailed CVE table with CWE, descriptions and fix versions" width="900"></p>
+<p align="center"><img src="docs/assets/report.png" alt="fad-checker HTML report; executive summary with severity tiles and a detailed CVE table with CWE, descriptions and fix versions" width="900"></p>
 
 ## Air-gapped audits
 
 > **Zero-data-sent guarantee.** Under `--offline`, fad-checker makes **no network calls
-> whatsoever** — it reads only the warmed `~/.fad-checker/` caches and never transmits a
+> whatsoever**; it reads only the warmed `~/.fad-checker/` caches and never transmits a
 > dependency, path or finding off the machine. It is regression-tested
 > (`test/offline-guarantee.test.js`, a tripwire fetcher that throws if touched) and
 > auditor-reproducible: `unshare -rn node fad-checker.js -s ./proj --offline …` runs it in a
 > namespace with **no network interface** and yields byte-identical findings. Unlike the
-> mainstream OSS scanners, fad also resolves the **Maven transitive graph** offline — so on
+> mainstream OSS scanners, fad also resolves the **Maven transitive graph** offline; so on
 > an air-gapped multi-module project it finds the transitive CVEs they can't.
 
 When the audited system is **offline / confidential** (typical of a regulated or air-gapped audit) it
 can't reach OSV / NVD / Maven Central / npm. Split the work across machines while keeping
 **zero environment information** off the secure enclave: an anonymized descriptor carries
-only **public package coordinates** — no filesystem paths, no registry URLs, no
-hostnames/usernames — and the **detailed report is produced back on the offline machine**.
+only **public package coordinates**; no filesystem paths, no registry URLs, no
+hostnames/usernames; and the **detailed report is produced back on the offline machine**.
 
 The transfer relies on a property of fad-checker's caches: they are keyed by *coordinate*
 or *vuln id*, never by path, so they are **machine-independent**. The online step just
 **warms the caches**; the offline step replays the scan and gets cache hits.
 
 ```bash
-# ── Phase 1 — OFFLINE (audited machine): export the anonymized descriptor ──
+# ── Phase 1; OFFLINE (audited machine): export the anonymized descriptor ──
 # Exclude private/internal packages with -e (offline we can't tell private from public).
 fad-checker -s ./proj -e "^(client|internal)\." --export-anonymized deps.json
 #   → deps.json: public coordinates only. Review it before it leaves the enclave.
 
-# ── Phase 2 — ONLINE (any machine, no source needed): warm the caches ──
+# ── Phase 2; ONLINE (any machine, no source needed): warm the caches ──
 fad-checker --import-anonymized deps.json     # scans coordinates → OSV/NVD/CVE/registry/EOL + retire signatures
 fad-checker --export-cache fad-cache.tar.gz   # bundle the warmed ~/.fad-checker/
 
-# ── Phase 3 — OFFLINE (audited machine): full report, all local context ──
+# ── Phase 3; OFFLINE (audited machine): full report, all local context ──
 fad-checker --import-cache fad-cache.tar.gz
 fad-checker -s ./proj --offline               # re-collect locally (real paths) + cache hits
 #   → full HTML/.doc report with manifests & structure, generated inside the enclave.
@@ -121,18 +129,36 @@ What the descriptor (`fad-deps/1`) contains vs. drops:
 | scope, isDev | parent chains, lockfile type |
 
 The online phase report is itself path-free; vendored-JavaScript (retire.js) findings are
-produced **offline in phase 3**, since retire needs the actual `.js` files — its signature
+produced **offline in phase 3**, since retire needs the actual `.js` files; its signature
 DB is warmed online (phase 2) and carried by `--export-cache`. Full offline/cache control →
 [`docs/USAGE.md`](docs/USAGE.md).
 
 ## Docs
 
-- [`docs/USAGE.md`](docs/USAGE.md) — every flag and workflow: offline/cache control, private registries, config files, recipes, safety rails.
-- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — internals: codecs, collection, matching, report pipeline.
-- [`docs/COMPARISON.md`](docs/COMPARISON.md) — vs OSV-Scanner / Trivy / Grype / OWASP DC / Snyk, and how it stays build-free.
-- [`docs/DATA-SOURCES.md`](docs/DATA-SOURCES.md) — the public datasets fad-checker uses + their licenses.
-- [`CHANGELOG.md`](CHANGELOG.md) · [`CLAUDE.md`](CLAUDE.md) — release history · code-level orientation for contributors.
+- [`docs/USAGE.md`](docs/USAGE.md); every flag and workflow: offline/cache control, private registries, config files, recipes, safety rails.
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md); internals: codecs, collection, matching, report pipeline.
+- [`docs/COMPARISON.md`](docs/COMPARISON.md); vs OSV-Scanner / Trivy / Grype / OWASP DC / Snyk, and how it stays build-free.
+- [`docs/BENCHMARK.md`](docs/BENCHMARK.md) — reproducible air-gapped recall benchmark vs OSV-Scanner on a public 105-module project.
+- [`docs/DATA-SOURCES.md`](docs/DATA-SOURCES.md); the public datasets fad-checker uses + their licenses.
+- [`CHANGELOG.md`](CHANGELOG.md) · [`CLAUDE.md`](CLAUDE.md); release history · code-level orientation for contributors.
+
+## Contributing
+
+The most useful contribution to a young scanner is **telling it where it's wrong**: run it on a
+real project and file a [false positive / false negative report](https://github.com/9pings/fad-checker/issues/new?template=false_positive.yml)
+with the coordinate and the manifest snippet that produced it. Dev setup, ground rules and the
+codec extension point → [`CONTRIBUTING.md`](CONTRIBUTING.md). Vulnerabilities in fad-checker
+itself → [`SECURITY.md`](SECURITY.md) (please report privately).
+
+**On AI assistance:** this codebase is written with heavy use of Claude Code; [`CLAUDE.md`](CLAUDE.md)
+in the repo root is exactly what it looks like. The bar it's held to is the one you can check
+yourself: **606 tests** (`npm test`), the zero-network guarantee enforced by a tripwire test and
+reproducible under `unshare -rn`, and coverage numbers measured against a Snyk baseline rather
+than asserted. `fad-checker` itself uses **no LLM at runtime**; findings come from public
+vulnerability databases and deterministic parsers, and no report text is generated. Full
+statement, including where review actually caught a bad finding →
+[`AI_POLICY.md`](AI_POLICY.md). Where the code doesn't meet that bar, that's a bug report I want.
 
 ## License
 
-MIT — see [`LICENSE`](LICENSE).
+MIT; see [`LICENSE`](LICENSE).

package/SECURITY.md

@@ -0,0 +1,60 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Report vulnerabilities in `fad-checker` itself **privately**, via
+[GitHub private security advisories](https://github.com/9pings/fad-checker/security/advisories/new).
+If that isn't available to you, email `pp9Ping@gmail.com` with `fad-checker security` in the
+subject.
+
+Please don't open a public issue for a vulnerability. This is a single-maintainer project —
+expect a first response within **7 days**, and a fix or a plan within **30 days** for anything
+confirmed. Credit is given in the release notes unless you'd rather stay anonymous.
+
+Findings *about your own dependencies* that fad-checker reported are not vulnerabilities in
+this project — those belong in a normal issue (the
+[false positive / false negative](https://github.com/9pings/fad-checker/issues/new?template=false_positive.yml)
+template).
+
+## Supported versions
+
+Only the latest released version on npm is supported. There are no backport branches.
+
+## Threat model
+
+fad-checker parses **untrusted input**: manifests, lockfiles, archives and certificates from a
+source tree you may not control. The parsing surface is where security bugs are expected, and
+reports there are especially welcome. In particular:
+
+- **Archive extraction** — `.jar`/`.war`/`.ear` are unzipped **in memory** (`fflate`), never to
+  disk, and nested archives are recursed to a bounded depth. Path traversal (zip-slip) has no
+  filesystem to reach, but resource exhaustion (zip bombs) is a valid report.
+- **Certificate and key parsing** — X.509 goes through Node's built-in `crypto.X509Certificate`.
+  Key material is **classified and hashed, never decrypted**, and its contents are never written
+  to the report.
+- **XML / YAML / TOML parsing** — `pom.xml` (xml2js), lockfiles (js-yaml, smol-toml). XXE and
+  entity-expansion reports are in scope.
+- **Command execution** — the only subprocesses are `snyk` (opt-in `--snyk`), `retire`, and
+  `curl`/`unzip` for the CVE bundle download.
+
+## What leaves your machine
+
+Under `--offline`, **nothing**: no network call is made at all, only the warmed
+`~/.fad-checker/` caches are read. This is enforced by a regression test
+(`test/offline-guarantee.test.js`, a tripwire fetcher that throws if touched) and is
+reproducible in a network-free namespace:
+
+```bash
+unshare -rn node fad-checker.js -s ./proj --offline
+```
+
+Online, fad-checker sends **package coordinates and versions** to the data sources listed in
+[`docs/DATA-SOURCES.md`](docs/DATA-SOURCES.md) (OSV.dev, NVD, Maven Central, npm, Packagist,
+PyPI, NuGet, RubyGems, proxy.golang.org, endoflife.date, FIRST.org EPSS, CISA KEV, deps.dev,
+CIRCL hashlookup) — plus **file checksums** for committed native binaries. It never uploads
+source code, file paths or manifest contents. If you consider your dependency list itself
+sensitive, use the anonymized air-gapped workflow described in the README.
+
+Configuration, including your NVD API key, lives in `~/.fad-checker/config.json` with mode
+`0600`. Registry credentials given via `--add-repo --auth`/`--token` are stored there too —
+they are sent only to the registry they belong to, and never appear in a report or export.