fad-checker 2.2.2 → 2.2.4

package/README.md

@@ -5,42 +5,47 @@
 [![license](https://img.shields.io/npm/l/fad-checker.svg)](https://github.com/n8tz/fad-checker/blob/main/package.json)
 [![node](https://img.shields.io/node/v/fad-checker.svg)](https://nodejs.org)
 
-> **F**ucking **A**utonomous **D**ependency **C**hecker
-
-`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**.
+> **F**abulous **A**utonomous **D**ependency **C**hecker<br>
+> AKA **F**uckin' **A**utonomous **D**ependency **C**hecker<br>
 
+`fad-checker` audits **Maven · npm · Yarn · pnpm · Composer · PyPI · NuGet · Go · Ruby**, vendored JavaScript and committed native binaries 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://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" height="760"></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>
 
-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.
+## Features
 
-> **Supported ecosystems: Maven, npm, Yarn (v1 + Berry/v2+), pnpm, Composer, PyPI, NuGet, Go, Ruby + committed native binaries.** Each is a self-contained **codec** (`lib/codecs/`) — adding another is adding a codec, no orchestrator surgery. Vendored JS (jQuery, Bootstrap, PDF.js, etc.) is also scanned via retire.js. **Embedded JARs** committed into the tree — vendored libs, Spring-Boot fat-jars, shaded uber-jars inside `.jar`/`.war`/`.ear` — are unzipped in-memory and their Maven coordinates scanned too (disable with `--no-jars`). **Committed native binaries** (`.dll`/`.exe`/`.so`/`.dylib`) are detected (magic-byte confirmed, so images/assets are never picked up) and **identified by checksum** via deps.dev + CIRCL — to flag tampered/unknown files and libraries that ought to be declared dependencies (disable with `--no-binaries`).
+- **9 ecosystems in one pass** — Maven, 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).
+- **No build tools** — reads `pom.xml`, `package-lock`/`yarn.lock`/`pnpm-lock`, `composer.lock`, `poetry`/`Pipfile`/`uv`/`pdm` locks, `packages.lock.json`/`*.csproj`, `go.mod`, `Gemfile.lock` directly. No `mvn`/`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 / PASSI** — **zero network under `--offline`** (regression-tested), offline Maven transitive resolution, and `--osv-db` for cache-independent offline OSV recall. → [Air-gapped](#air-gapped--passi-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.
+- **Outputs & CI** — HTML + Word `.doc`, CycloneDX 1.6 SBOM, CSAF 2.0 VEX, SARIF 2.1.0, JSON; gate with `--fail-on`, triage with `--ignore`/`--vex`.
 
----
+📖 **[Usage & all flags](docs/USAGE.md)** · **[Architecture](docs/ARCHITECTURE.md)** · **[Comparison vs other tools](docs/COMPARISON.md)** · **[Data sources](docs/DATA-SOURCES.md)**
 
-## Why "Autonomous"?
+## Quick start
 
-Because it doesn't need anything you don't already have on disk:
+```bash
+npm install -g fad-checker
+fad-checker -s ./my-project          # → ./fad-checker-report/cve-report.html
+```
 
-| You don't need | Why |
-| --- | --- |
-| Maven installed | `pom.xml` files are parsed directly with xml2js. Properties, profiles and local BOMs are resolved in-process. Transitive deps fetched from Maven Central if `--transitive` (cached forever). |
-| `mvn dependency:tree` | Same as above. We walk the tree ourselves. |
-| `npm install` / a `node_modules/` | `package-lock.json` (v1/v2/v3), `yarn.lock` (v1 + Berry/v2+) and `pnpm-lock.yaml` (v5/v6/v9) are parsed as text/JSON/YAML. Versions come from the lockfile — no installation. |
-| `yarn install` / `pnpm install` | Same. We read `yarn.lock` (v1 + Berry) and `pnpm-lock.yaml` directly. |
-| `composer install` | `composer.lock` is parsed directly (concrete versions + transitive). `composer.json` alone → best-effort on pinned versions + warning. |
-| `pip` / `poetry` / a venv | `poetry.lock`, `Pipfile.lock`, `uv.lock`, `pdm.lock` are parsed for concrete versions; `pyproject.toml` (PEP 621 + poetry) and `requirements.txt` (following `-r`/`-c` includes) are best-effort on exact pins. Names normalised per PEP 503. |
-| `dotnet restore` | `packages.lock.json` is parsed; otherwise `*.csproj`/`*.fsproj`/`*.vbproj` (+ `Directory.Packages.props` Central Package Management) and legacy `packages.config`, best-effort on pinned versions. |
-| `go build` / a Go toolchain | `go.mod` is parsed (the full pruned graph on Go ≥1.17, `// indirect` → transitive); `go.sum` is the fallback. No module download. |
-| `bundle install` | `Gemfile.lock` is parsed for the resolved gem set. No Ruby, no bundler. |
-| `snyk` binary | Built-in CVE matching via CVEProject + OSV + NVD (merged), prioritised with EPSS + CISA KEV (see below). Snyk is *optional* (`--snyk`). |
-| A network connection | First run downloads CVE / OSV / EOL data; subsequent runs use cached copies (`--offline` to force). |
+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):
 
-Exactly **one** runtime dependencies must be on PATH (or installed automatically through npm): Node ≥ 20. Everything else is bundled or fetched lazily.
+```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 --osv-db --typosquat                     # offline-complete OSV + typosquat
+fad-checker -s ./proj --licenses --fail-on high                # license chapter + CI gate
+```
 
----
+A single self-contained binary (no Node), from-source install and shell completion are in → [docs/USAGE.md](docs/USAGE.md).
 
 ## What it finds
 
@@ -53,6 +58,7 @@ Exactly **one** runtime dependencies must be on PATH (or installed automatically
 | **1D. Unmanaged / vendored JavaScript** | [retire.js](https://retirejs.github.io/) (`--verbose`) | **Inventory of every standalone JS lib** committed into the tree (jQuery, Bootstrap, PDF.js, …) that no package manager governs — vulnerable *or not*. A cyber-hygiene constat: unknown provenance/integrity/patch story. `--no-vendored-js-inventory` to skip |
 | **2. Vendored JS (vulnerable)** | [retire.js](https://retirejs.github.io/) | The subset of the above with known CVEs/advisories — old jQuery/Bootstrap/Angular/PDF.js copies with no lockfile |
 | **3. CVE in dev deps** | same | Same as chapter 1, but for `test`/`provided` (Maven) and `dev`/`optional`/`peer` (npm) |
+| **Supply-chain risk** | 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`) |
 | **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 |
@@ -61,171 +67,18 @@ Exactly **one** runtime dependencies must be on PATH (or installed automatically
 
 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.
 
----
-
-## Quick start
-
-```bash
-npm install -g fad-checker
-fad-checker -s ./my-project
-```
-
-That's it. The report lands in `./fad-checker-report/cve-report.html`.
-
-Want a 10× faster NVD enrichment? [Get a free NVD API key](https://nvd.nist.gov/developers/request-an-api-key) (instant), then:
-
-```bash
-fad-checker --set-nvd-key YOUR_KEY
-```
-
----
-
-## Common runs
-
-```bash
-# Read-only full scan (default: all sources on)
-fad-checker -s ./proj
-
-# Exclude private/internal libs by groupId/name regex
-fad-checker -s ./proj -e "^(com\.acme|org\.private)\."
-
-# Ignore whole sub-paths during the walk (gitignore-style glob, relative to -s)
-fad-checker -s ./proj --exclude-path "packages/legacy/**" --exclude-path "**/fixtures/**"
-fad-checker -s ./proj --no-default-excludes          # walk everything (incl. node_modules/.git)
-
-# Also write cleaned POMs (private deps stripped, ready for Snyk)
-fad-checker -s ./proj -t ../proj-clean -e "^com\.acme\."
-
-# Then run Snyk on the cleaned tree and merge findings
-fad-checker -s ./proj -t ../proj-clean -e "^com\.acme\." --snyk
-
-# Faster: skip Maven Central / no transitive walk
-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
-fad-checker -s ./proj --no-nuget --no-composer     # or opt out per codec
-fad-checker -s ./proj --no-binaries                # skip the native-binary scan
-
-# Private registry + reusable defaults (see "Configuration file & environment")
-fad-checker --add-repo npm verdaccio https://npm.acme.com/ --token "$NPM_TOKEN"
-fad-checker --config ./ci/fad-env.json             # all options from a JSON file
-fad-checker --source ./proj                        # --source / --src are aliases
-```
-
-Run `fad-checker --help` for the full flag list.
-
----
-
-## What a report looks like
-
 <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>
 
-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 (retire.js)
-  • 2 EOL frameworks · 13 obsolete/deprecated · 172 outdated
-  • 4 scan-completeness alerts — see chapter 0
-```
-
-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).
-
----
-
-## Install
-
-### As a global CLI
-
-```bash
-npm install -g fad-checker
-```
-
-### From source
-
-```bash
-git clone <repo-url> fad-checker
-cd fad-checker
-npm install
-node fad-checker.js --help
-```
-
-### Single-binary build (no Node required)
-
-```bash
-npm install        # one-time, brings in bun
-npm run build      # → dist/fad-checker-linux + dist/fad-checker.exe
-```
-
-### Shell completion
-
-```bash
-fad-checker --completion bash > /etc/bash_completion.d/fad-checker
-# or for zsh:
-fad-checker --completion zsh  > ~/.zsh/completions/_fad-checker
-```
-
----
-
-## How it scans without any build tool
-
-**TL;DR** — `fad-checker` never runs your build. For each ecosystem it reads the **lockfile** (or, failing that, the manifest's pinned versions) straight off disk to learn the exact dependency versions, then matches those coordinates against vulnerability/EOL/registry data over the network (cached, `--offline`-able). No `mvn`, `npm install`, `pip`, `dotnet restore`, `go build` or `bundle` — and no `node_modules/`.
-
-| Ecosystem | Read directly | Transitive versions come from |
-| --- | --- | --- |
-| Maven | `pom.xml` (+ parents, BOMs, profiles) | child POMs fetched from Maven Central (cached) |
-| npm / Yarn / pnpm | `package-lock.json` · `yarn.lock` (v1+Berry) · `pnpm-lock.yaml` | the lockfile itself |
-| Composer | `composer.lock` (else `composer.json`) | the lockfile |
-| PyPI | `poetry.lock` · `Pipfile.lock` · `uv.lock` · `pdm.lock` (else `pyproject.toml`/`requirements.txt`) | the lockfile |
-| NuGet | `packages.lock.json` (else `*.csproj`/`packages.config`) | the lockfile |
-| Go | `go.mod` (`// indirect` → transitive; `go.sum` fallback) | the module graph in `go.mod` |
-| Ruby | `Gemfile.lock` (`specs:`) | the lockfile |
-| Vendored JS / binaries | the committed `.js` / `.jar` / `.so` files themselves | n/a (read in place) |
-
-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/` — 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:
+## Air-gapped / PASSI audits
 
-```bash
-fad-checker --export-cache fad-cache.tar.gz
-# on the other box:
-fad-checker --import-cache fad-cache.tar.gz
-```
-
-`--include-config` ships the NVD API key too (off by default).
-
-> The cache export bundles **everything** under `~/.fad-checker/` (except `config.json`),
-> including the retire.js findings **and** the warmed retire.js signature DB — so a
-> machine that imports it can scan vendored JavaScript fully offline.
-
----
-
-## Air-gapped / PASSI audits: anonymized dependency descriptor
+> **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
+> 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
+> an air-gapped multi-module project it finds the transitive CVEs they can't.
 
 When the audited system is **offline / confidential** (typical of a PASSI engagement) it
 can't reach OSV / NVD / Maven Central / npm. Split the work across machines while keeping
@@ -264,134 +117,16 @@ What the descriptor (`fad-deps/1`) contains vs. drops:
 
 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
-DB is warmed online (phase 2) and carried by `--export-cache`.
-
----
-
-## Custom repositories & registries
-
-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
-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
-```
-
-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. 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
-FAD_CHECKER_ENV='--fail-on high --no-nuget' fad-checker -s ./proj
-```
-
-`-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).
-
----
-
-## Data sources & acknowledgments
-
-`fad-checker` is glue around several outstanding public datasets. Each is used per its license terms.
-
-| Source | What we use | License | API / endpoint |
-| --- | --- | --- | --- |
-| [CVEProject `cvelistV5`](https://github.com/CVEProject/cvelistV5) | Daily bulk CVE bundle, filtered to Maven-relevant entries | CC0-1.0 | GitHub release asset (zip) |
-| [OSV.dev](https://osv.dev/) (Google + GitHub Security Lab) | Per-dep vulnerability lookup (Maven, npm, Packagist, PyPI, NuGet, …) | CC-BY 4.0 | `POST api.osv.dev/v1/querybatch`, `GET api.osv.dev/v1/vulns/{id}` |
-| [NIST NVD](https://nvd.nist.gov/) | Canonical CVE description + CVSS vectors + CPE configurations + CWE | US-gov public domain | `GET services.nvd.nist.gov/rest/json/cves/2.0?cveId=…` — free [API key](https://nvd.nist.gov/developers/request-an-api-key) bumps the rate limit 10× |
-| [FIRST.org EPSS](https://www.first.org/epss/) | Exploit-prediction score + percentile per CVE | CC-BY 4.0 | `GET api.first.org/data/v1/epss?cve=…` (batched) |
-| [CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) | Known-exploited-vulnerability catalogue membership | US-gov public domain | `GET cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json` |
-| [endoflife.date](https://endoflife.date/) | Framework / runtime EOL cycle data | MIT | `GET endoflife.date/api/{product}.json` |
-| [Maven Central](https://search.maven.org/) | Latest-version lookups + transitive POM fetches | Free public service | Solr `search.maven.org/solrsearch/select?q=…` + `repo1.maven.org/maven2/<coord>` |
-| [npm registry](https://registry.npmjs.org/) | Per-version `deprecated` + `dist-tags.latest` | Free public service | `GET registry.npmjs.org/<pkg>` |
-| [Packagist](https://packagist.org/) | Latest stable + `abandoned` flag | Free public service | `GET packagist.org/packages/<vendor>/<pkg>.json` |
-| [PyPI](https://pypi.org/) | Latest + `yanked` + "Inactive" classifier | Free public service | `GET pypi.org/pypi/<pkg>/json` |
-| [NuGet](https://www.nuget.org/) | Latest stable + per-version `deprecation` | Free public service | `GET api.nuget.org/v3/registration5-gz-semver2/<id>/index.json` |
-| [Go module proxy](https://proxy.golang.org/) | Latest module version (outdated) | Free public service | `GET proxy.golang.org/<module>/@latest` |
-| [RubyGems](https://rubygems.org/) | Latest stable + licenses | Free public service | `GET rubygems.org/api/v1/gems/<gem>.json` |
-| [deps.dev](https://deps.dev/) | Native-binary identity by checksum (→ package coordinate) | Free public API (CC-BY) | `GET api.deps.dev/v3/query?hash.type=SHA1&hash.value=<base64>` |
-| [CIRCL hashlookup](https://hashlookup.circl.lu/) | Known-good file identity (NSRL/distro/CDN) + KnownMalicious | Free public service | `GET hashlookup.circl.lu/lookup/sha256/<hash>` |
-| [retire.js](https://retirejs.github.io/retire.js/) | Vendored-JS signature DB + scanner | Apache-2.0 | npm package `retire`, executed locally |
-| [Snyk](https://snyk.io/) (optional) | Additional CVE source via `snyk test --all-projects --json` | Per Snyk EULA; needs a Snyk account | Local CLI `snyk` |
-| [MITRE CWE](https://cwe.mitre.org/) | Weakness category links in the report | Free public reference | Linked by URL only, no API call |
-
-Persistent caches mean each source is hit at most once per its TTL (see [Caching](#caching) table). No telemetry, no third-party analytics — every request listed above is made directly to the named endpoint with a `User-Agent: fad-checker-*` header.
-
----
-
-## Safety rails
-
-Built-in guardrails that fire **before** any disk write:
-
-- `--target` is required unless you're running read-only (no `-t`).
-- `--target` may not equal or be a subdirectory of `--src`.
-- `--target` is `rimraf`'d before being rewritten — never point it at anything precious.
-
----
-
-## Comparison
-
-`fad-checker` is **not** a Trivy/Grype competitor — those are container-and-SBOM supply-chain
-scanners. It targets a narrower job: a **zero-setup, multi-ecosystem audit of a source
-checkout, with an audit-ready report and a confidential / air-gapped workflow** — the kind
-of thing a security consultant or an ANSSI-PASSI engagement needs.
-
-| | **fad-checker** | OSV-Scanner | Trivy | Grype + Syft | OWASP DC | Snyk OSS |
-| --- | --- | --- | --- | --- | --- | --- |
-| Ecosystems it targets¹ | Maven, npm, Yarn, **pnpm**, Composer, PyPI, NuGet, Go, Ruby + vendored JS + **native binaries** | 11+ langs / 19+ lockfiles | 20+ | 20+ | Java/.NET (others exp.) | many |
-| Reads lockfiles without `install`/build | ✅ | ✅ | ✅ | ✅ | ⚠️ Java needs Maven Central/build | ❌ build required |
-| Best-effort when **no lockfile** (pinned versions) | ✅ | ❌ | ❌ | ❌ | ⚠️ | ⚠️ |
-| Vulnerability sources | CVEProject + OSV + NVD + EPSS + KEV + retire.js (+ Snyk), merged | OSV.dev | Aqua DB | Anchore DB | NVD / CPE | Snyk DB |
-| False-positive control | CPE/version cross-check | ecosystem-aware | ecosystem-aware | ecosystem-aware | ⚠️ CPE → noisy | ecosystem-aware |
-| **EOL** (end-of-life) detection | ✅ endoflife.date | ❌ | ❌ | ❌ | ❌ | ~ |
-| **Outdated / deprecated** | ✅ registries + curated | ❌ | ❌ | ❌ | ❌ | ~ |
-| Containers / OS packages | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ |
-| SBOM (CycloneDX/SPDX) | ✅ CycloneDX 1.6 (+ CSAF 2.0 VEX) | ✅ | ✅ | ✅ (Syft) | ~ | ✅ |
-| License compliance | ✅ SPDX + copyleft policy | ~ | ✅ | ~ | ❌ | ✅ |
-| EPSS / KEV prioritization | ✅ FIRST.org EPSS + CISA KEV | ~ | ✅ | ✅ | ❌ | ✅ |
-| CI gating (`--fail-on`) + triage | ✅ severity/KEV + ignore/VEX | ✅ | ✅ | ✅ | ⚠️ | ✅ |
-| Auto-remediation / PRs | ❌ (fix recipes only) | ✅ `fix` | ❌ | ❌ | ❌ | ✅ |
-| Offline | ✅ cache | ✅ local DB | ✅ | ✅ | ✅ feed | ❌ mostly online |
-| **Scan without exposing the codebase**² | ✅ anonymized descriptor | ❌ | ❌ | ❌ | ❌ | ❌ |
-| **Maven private-dep cleanup** (→ Snyk) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Output | **HTML + Word `.doc`** + JSON / SARIF / CycloneDX / CSAF | table/JSON/SARIF | table/JSON/SARIF | table/JSON/SARIF | HTML/XML/JSON | JSON / cloud UI |
-
-¹ Narrower language coverage — no Rust/Dart/Swift (Go and Ruby are now covered).
-
-² Phase 1 exports only public coordinates; the online scan never sees your source tree —
-see [Air-gapped / PASSI](#air-gapped--passi-audits-anonymized-dependency-descriptor). OSV-Scanner
-has an offline mode, but it still needs the **source on the scanning machine**.
-
-**Where it fits:** a one-shot audit of a polyglot checkout you may not be able to build, a
-presentable HTML/Word deliverable, and confidential / air-gapped engagements.
-
-**Where it doesn't:** container/OS scanning,
-reachability analysis, auto-fix PRs — reach for **Trivy** or **Grype + Syft**.
-
-You don't have to choose — `fad-checker` takes Snyk's results as input (`--snyk`) and merges them.
-
-> Sources: [OSV-Scanner lockfiles](https://google.github.io/osv-scanner/supported-languages-and-lockfiles/) ·
-> [Trivy Java/`pom.xml` (Maven Central, `--offline-scan`)](https://trivy.dev/docs/latest/coverage/language/java/) ·
-> [Syft `java-pom-cataloger` (source dirs)](https://github.com/anchore/syft/issues/676) ·
-> [OWASP DC needs internet/build for Java](https://jeremylong.github.io/DependencyCheck/data/index.html) ·
-> [Snyk requires building the project](https://docs.snyk.io/supported-languages/technical-specifications-and-guidance) ·
-> [EOL/outdated "most tools skip" (Aikido)](https://www.aikido.dev/code/outdated-eol-software)
-
----
+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, every workflow, examples.
+- [`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.
-- [`CHANGELOG.md`](CHANGELOG.md) — release history.
-- [`CLAUDE.md`](CLAUDE.md) — code-level orientation for contributors.
-
----
+- [`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.
 
 ## License
 

package/data/popular-packages.json

@@ -0,0 +1,39 @@
+{
+  "_comment": "Curated list of widely-used npm + PyPI packages used as TYPOSQUAT TARGETS by lib/malware.js#detectTyposquats. A resolved dep whose name is edit-distance 1 from one of these (but isn't it) is flagged as a suspected typosquat/slopsquat. Not exhaustive — focused on the most-impersonated packages. Add names here to widen proactive coverage.",
+  "npm": [
+    "react", "react-dom", "lodash", "express", "axios", "chalk", "commander", "request",
+    "debug", "async", "moment", "underscore", "jquery", "webpack", "babel-core", "vue",
+    "angular", "typescript", "eslint", "prettier", "jest", "mocha", "chai", "bluebird",
+    "yargs", "glob", "minimist", "colors", "dotenv", "body-parser", "cors", "mongoose",
+    "redux", "next", "gatsby", "rxjs", "classnames", "prop-types", "uuid", "bcrypt",
+    "jsonwebtoken", "passport", "nodemon", "node-fetch", "cross-env", "rimraf", "fs-extra",
+    "semver", "validator", "winston", "morgan", "helmet", "sequelize", "knex", "mysql",
+    "redis", "ioredis", "dayjs", "date-fns", "ramda", "immutable", "styled-components",
+    "tailwindcss", "postcss", "autoprefixer", "browserify", "rollup", "parcel", "esbuild",
+    "husky", "lint-staged", "concurrently", "nanoid", "form-data", "tslib", "core-js",
+    "socket.io", "nodemailer", "puppeteer", "playwright", "cheerio", "inquirer", "ora",
+    "execa", "chokidar", "ws", "got", "undici", "zod", "yup", "formik", "react-router",
+    "react-router-dom", "react-redux", "vuex", "pinia", "svelte", "preact", "ant-design",
+    "bootstrap", "jquery-ui", "three", "d3", "chart.js", "leaflet", "highlight.js",
+    "marked", "handlebars", "ejs", "pug", "nunjucks", "graphql", "apollo-server",
+    "mongodb", "pg", "typeorm", "prisma", "jsdom", "supertest", "sinon", "nyc", "ava",
+    "babel-loader", "ts-loader", "css-loader", "style-loader", "html-webpack-plugin",
+    "colord"
+  ],
+  "pypi": [
+    "requests", "numpy", "pandas", "flask", "django", "scipy", "matplotlib", "pillow",
+    "setuptools", "wheel", "urllib3", "certifi", "pytest", "six", "click", "jinja2",
+    "werkzeug", "sqlalchemy", "boto3", "botocore", "pyyaml", "cryptography",
+    "beautifulsoup4", "lxml", "scikit-learn", "tensorflow", "keras", "scrapy",
+    "celery", "psycopg2", "pymongo", "fastapi", "uvicorn", "pydantic", "aiohttp",
+    "httpx", "tqdm", "colorama", "rich", "typer", "python-dateutil", "pytz", "attrs",
+    "packaging", "idna", "charset-normalizer", "markupsafe", "openpyxl", "tornado",
+    "gunicorn", "redis", "selenium", "paramiko", "fabric", "pyjwt", "passlib", "bcrypt",
+    "marshmallow", "flask-sqlalchemy", "flask-cors", "flask-restful", "django-rest-framework",
+    "djangorestframework", "gevent", "greenlet", "asgiref", "starlette", "anyio",
+    "httpcore", "sniffio", "wrapt", "decorator", "more-itertools", "toml", "tomli",
+    "pyparsing", "jsonschema", "protobuf", "grpcio", "boto", "awscli", "google-api-python-client",
+    "opencv-python", "imageio", "networkx", "sympy", "statsmodels", "seaborn", "plotly",
+    "dash", "streamlit", "jupyter", "ipython", "notebook", "nbconvert", "cython"
+  ]
+}

package/fad-checker.js

@@ -236,7 +236,10 @@ program
 	.option("--ignore-test", "skip test-scoped dependencies in report")
 	.option("--cve-refresh", "force re-download of CVE database")
 	.option("--cve-offline", "use cached CVE index only (no download)")
+	.option("--osv-db", "import + match the full local OSV database (Maven) — offline-complete recall, independent of the per-dep OSV cache")
+	.option("--osv-db-refresh", "force re-download of the local OSV database")
 	.option("--snyk", "run snyk on cleaned POMs and merge into report (requires --target)")
+	.option("--typosquat", "flag npm/PyPI deps whose name is one edit from a popular package (heuristic typosquat/slopsquat detection)")
 	.option("--no-retire", "skip retire.js vendored-JS scan")
 	.option("--no-vendored-js-inventory", "don't list ALL identified vendored JS libs (chapter 1D) — keep only the vulnerable ones (chapter 2)")
 	.option("--retire-refresh", "ignore retire cache and re-scan")
@@ -750,6 +753,9 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		? require("./lib/maven-bom").collectImportBoms(mavenPropsByPom) : [];
 	const willBom = importBoms.length > 0;
 	const willOsv = !!options.osv;
+	// Local OSV DB import (Maven): offline-complete OSV recall, independent of the per-dep
+	// OSV.dev cache. Opt-in (downloads ~9 MB once); then matches online or offline.
+	const willOsvDb = !!options.osvDb && runMaven;
 	const willOutdated = !!options.allLibs;
 	const willNvd = !!options.nvd;
 	const willEpss = !!options.epss;
@@ -760,7 +766,7 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 	const willBinaryId = [...resolved.values()].some(d => d.provenance === "binary");
 	// License detection piggybacks on the registry passes (same fetched metadata),
 	// so it adds no progress step of its own.
-	const totalSteps = [willBom, willTransitive, willOverlay, willCve, /*EOL*/ true, willOutdated, /*npm reg*/ true, ...otherRegistryIds.map(() => true), willOsv, willNvd, willEpss, willKev, willRetire, willBinaryId].filter(Boolean).length;
+	const totalSteps = [willBom, willTransitive, willOverlay, willCve, /*EOL*/ true, willOutdated, /*npm reg*/ true, ...otherRegistryIds.map(() => true), willOsv, willOsvDb, willNvd, willEpss, willKev, willRetire, willBinaryId].filter(Boolean).length;
 	const progress = new ui.Progress(totalSteps);
 
 	if (willBom) {
@@ -912,6 +918,25 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		}
 	}
 
+	// 4b'. Local OSV database (Maven) — offline-COMPLETE recall. The per-dep OSV.dev
+	// queries above only cover deps cached online; the imported full OSV DB matches every
+	// dep offline, deterministically, regardless of cache warmth (the OSV-Scanner model).
+	if (willOsvDb) {
+		const st = progress.start("OSV database (local, Maven)");
+		try {
+			const { ensureOsvDb, matchOsvDbDeps } = require("./lib/osv-db");
+			const index = await ensureOsvDb({ offline, refresh: !!options.osvDbRefresh, verbose, ecosystem: "maven" });
+			if (!index) {
+				st.done(offline ? "no local OSV DB (run once online with --osv-db)" : "unavailable");
+			} else {
+				const dbMatches = matchOsvDbDeps(resolved, index);
+				const before = cveMatches.length;
+				cveMatches = mergeBySource(cveMatches, dbMatches);
+				st.done(`${index.count} advisories · ${dbMatches.length} matched · +${cveMatches.length - before} new`);
+			}
+		} catch (err) { st.fail(err.message); }
+	}
+
 	// 4c. NVD enrichment — canonical description + full CVSS for matched CVEs.
 	if (willNvd) {
 		const st = progress.start("NVD enrichment");
@@ -1019,6 +1044,22 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		}
 	}
 
+	// 6b. Supply-chain risk lane (pure + offline): flag KNOWN-MALICIOUS advisories
+	// (OSV MAL-… already in the match set) always, and detect suspected TYPOSQUATS
+	// (opt-in --typosquat, heuristic — names one edit from a popular package).
+	const { flagMalicious, detectTyposquats } = require("./lib/malware");
+	const maliciousCount = flagMalicious(cveMatches);
+	const typosquats = options.typosquat ? detectTyposquats(resolved) : [];
+	if (maliciousCount || typosquats.length) {
+		ui.section("Supply-chain risk");
+		if (maliciousCount) ui.warn(chalk.red.bold(`${maliciousCount} KNOWN-MALICIOUS package advisory(ies) (MAL-…) — treat the build as compromised`));
+		if (typosquats.length) {
+			ui.warn(`${typosquats.length} suspected typosquat(s) — heuristic, verify each is intentional:`);
+			for (const t of typosquats.slice(0, 15)) console.log("    " + chalk.yellow(t.name) + chalk.dim(` (${t.ecosystem}) ≈ ${t.resembles}`));
+			if (typosquats.length > 15) console.log(chalk.dim(`    …and ${typosquats.length - 15} more (see JSON export)`));
+		}
+	}
+
 	// Split prod vs dev based on the dep's isDev flag (set at collection time
 	// from Maven scope=test/provided and npm dev/devOptional/optional). Keep the
 	// full per-bucket list (including cpeFiltered) so the HTML report can render
@@ -1253,7 +1294,7 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		try {
 			const { writeFindings } = require("./lib/json-export");
 			await ensureDir(out.json);
-			writeFindings({ cveMatches, retireMatches, vendoredJsInventory, eolResults, obsoleteResults, outdatedResults, licenseResults, resolvedDeps: resolved, projectInfo, toolVersion: pkg.version }, out.json);
+			writeFindings({ cveMatches, retireMatches, vendoredJsInventory, eolResults, obsoleteResults, outdatedResults, licenseResults, resolvedDeps: resolved, projectInfo, toolVersion: pkg.version, typosquats }, out.json);
 			wrote.push(["Findings JSON", out.json]);
 		} catch (err) { ui.warn(`JSON export failed: ${err.message}`); }
 	}
@@ -1280,9 +1321,12 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		const { evaluateGate } = require("./lib/gate");
 		// Embedded-binary findings are real production risk → gate on them too.
 		const gate = evaluateGate([...prodActive, ...embeddedActive], options.failOn);
-		if (gate.failed) {
+		// A known-malicious package always blocks, regardless of the --fail-on level.
+		const maliciousActive = [...prodActive, ...embeddedActive].filter(m => m.malicious);
+		if (gate.failed || maliciousActive.length) {
 			ui.section("Gate");
-			console.log(chalk.red(`✗ --fail-on ${options.failOn}: ${gate.reason}`));
+			if (maliciousActive.length) console.log(chalk.red.bold(`✗ ${maliciousActive.length} known-malicious package(s) detected — always blocks`));
+			if (gate.failed) console.log(chalk.red(`✗ --fail-on ${options.failOn}: ${gate.reason}`));
 			process.exitCode = 1;
 		} else if (verbose) {
 			ui.info(chalk.dim(`--fail-on ${options.failOn}: no blocking finding`));