fad-checker

Fucking Autonomous Dependency Checker

fad-checker scans Maven, npm, Yarn, Composer (PHP), PyPI (Python), NuGet (C#/.NET) and vendored JavaScript in any source tree — multi-module, monorepo, polyglot, whatever you've got — and produces a single self-contained HTML report with CVE, EOL, obsolete and outdated findings, plus per-ecosystem fix recipes.

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.

Supported ecosystems: Maven, npm, Yarn (v1 + Berry/v2+), pnpm, Composer, PyPI, NuGet. 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.

Why "Autonomous"?

Because it doesn't need anything you don't already have on disk:

Exactly two runtime dependencies must be on PATH (or installed automatically through npm): Node ≥ 20 and retire (the npm package, installed by npm install). Everything else is bundled or fetched lazily.

What it finds

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.

Quick start

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 (instant), then:

fad-checker --set-nvd-key YOUR_KEY

Common runs

# Read-only full scan (default: all sources on)
fad-checker -s ./proj

# Exclude private/internal libs by groupId regex
fad-checker -s ./proj -e "^(com\.acme|org\.private)\."

# 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

# 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

Run fad-checker --help for the full flag list.

What a report looks like

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
  • 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).

Install

As a global CLI

npm install -g fad-checker

From source

git clone <repo-url> fad-checker
cd fad-checker
npm install
node fad-checker.js --help

Single-binary build (no Node required)

npm install        # one-time, brings in bun
npm run build      # → dist/fad-checker-linux + dist/fad-checker.exe

Shell completion

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

This is the surprising bit. The whole point is that you can run fad-checker against a checkout with no build environment.

• 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.
• 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 and scans .js / .min.js files by signature, catching old jQuery / Bootstrap / Angular / PDF.js copies that no lockfile knows about.
• 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, …).

Caching

All cached data lives in ~/.fad-checker/:

Export the lot to share between machines:

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

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 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.

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.

# ── 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 ──
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 ──
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.

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 Maven repositories

Out of the box fad-checker queries Maven Central for transitive POMs and latest versions. If your project depends on artifacts that live on a private Nexus / Artifactory / JBoss repo, add them so transitive resolution and outdated checks work end-to-end.

# Persist a repo (lives in ~/.fad-checker/config.json)
fad-checker --add-repo nexus       https://nexus.acme.com/repository/maven-public/
fad-checker --add-repo nexus-priv  https://nexus.acme.com/repository/maven-private/  --auth alice:s3cr3t
fad-checker --list-repos
fad-checker --remove-repo nexus-priv

# One-off (not persisted) — repeatable
fad-checker -s ./proj --repo https://nexus.acme.com/repository/maven-public/
# Inline auth in the URL also works:
fad-checker -s ./proj --repo https://alice:s3cr3t@nexus.acme.com/repository/maven-public/

Repos are tried in declared order, Maven Central last. Auth is sent as a Basic <base64> header. POMs and maven-metadata.xml are cached per coord, so subsequent runs are free even against a private repo.

Data sources & acknowledgments

fad-checker is glue around several outstanding public datasets. Each is used per its license terms.

Persistent caches mean each source is hit at most once per its TTL (see 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.

Compared to…

You don't have to choose — fad-checker will use any of them as input (--snyk) and merge results.

Docs

• docs/USAGE.md — every flag, every workflow, examples.
• docs/ARCHITECTURE.md — internals: codecs, collection, matching, report pipeline.
• CHANGELOG.md — release history.
• CLAUDE.md — code-level orientation for contributors.

License

MIT — see LICENSE.