fad-checker

Fucking Autonomous Dependency Checker

fad-checker scans Maven, npm, Yarn, Composer (PHP), PyPI (Python), NuGet (C#/.NET), Go, Ruby 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 (prioritised by EPSS + CISA KEV), EOL, obsolete, outdated and license findings, plus per-ecosystem fix recipes. It also exports a CycloneDX 1.6 SBOM and a CSAF 2.0 VEX.

🌐 Project site & docs →

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, Go, Ruby. 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).

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

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

The console prints a summary; the full detail lives in the self-contained HTML/.doc:

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.
• Go — go.mod require entries are the selected versions (full pruned graph on Go ≥1.17; // indirect → transitive), go.sum as fallback. OSV "Go" ecosystem for recall, the Go module proxy for outdated.
• Ruby — Gemfile.lock specs: give the resolved gem set. OSV "RubyGems" for recall, the RubyGems API for outdated + licenses.
• Lockfile-first, best-effort fallback — when a lockfile is present it wins. When it's absent, the loose manifest (package.json / composer.json / pyproject.toml / requirements.txt / *.csproj) is still parsed for its pinned exact versions, with ranges skipped and a no-lockfile warning in chapter 0 flagging the partial coverage.
• Vendored JavaScript — retire.js shells out and scans .js / .min.js files by signature, catching old jQuery / Bootstrap / Angular / PDF.js copies that no lockfile knows about.
• Embedded JARs — committed .jar / .war / .ear archives are unzipped in memory (via fflate — nested fat-jar libs are recursed without ever touching disk, so there's no zip-slip risk) and each artifact's Maven coordinate is read from META-INF/maven/.../pom.properties (authoritative), then MANIFEST.MF, then the file name. Those coordinates run through the same CVE/OSV/NVD matching as declared deps but report in their own Embedded binaries chapter, grouped by containing archive. An archive whose coordinate can't be resolved is flagged in chapter 0 rather than scanned blindly. Auto when archives are present; disable with --no-jars. (Embedded coords don't trigger Maven Central transitive resolution — a fat-jar already ships its dependencies, which the recursion finds directly.)
• CVE data — three independent sources merged:
  • CVEProject (the canonical cvelistV5 bundle, filtered to Maven-relevant entries)
  • OSV.dev (Google + GitHub Security Lab, multi-ecosystem)
  • NVD (official NIST records, used for enrichment: full CVSS, references, CPE configurations)
• CPE refinement — once a CVE is matched, its NVD CPE configurations are checked against the dep version range. A match outside the vulnerable range is flagged cpeFiltered: true (likely false positive). A curated data/cpe-coord-map.json maps CPE vendor:product to Maven g:a (60+ entries seeded: log4j, jackson, spring, tomcat, jetty, netty, …).
• Prioritization — each matched CVE is enriched with EPSS (FIRST.org exploit-prediction percentile) and CISA KEV (known-exploited catalogue), then scored: KEV (exploited in the wild) outranks EPSS-weighted CVSS. The report sorts by this composite priority and badges KEV/EPSS.
• Licenses — each dependency's license is resolved (registry metadata, no extra request; Maven from cached POMs), normalised to SPDX and classified against a copyleft policy (data/license-policy.json) — permissive / weak / strong / network copyleft / proprietary / unknown.
• Unified outputs — one --report-<type> flag per output, each with an OPTIONAL path (omit it → a default name under --report-output): --report-html, --report-doc, plus the machine-readable --report-sbom (CycloneDX 1.6, vulnerabilities inline / VDR), --report-csaf (CSAF 2.0 VEX), --report-json (flat findings, diff-friendly) and --report-sarif (SARIF 2.1.0 for GitHub/GitLab code scanning). With no --report-* flag, HTML + .doc are written by default; --no-report writes nothing (gate-only). purls per ecosystem.
• CI gating & triage — --fail-on <low|medium|high|critical|kev> sets a non-zero exit code (kev = fail only on a CISA-known-exploited finding). --ignore <file> (CVE/coord/glob rules) and --vex <file> (ingest a CSAF VEX) suppress accepted-risk / false-positive findings from the report and the gate, while keeping them flagged in the exports — so re-audits stay signal-rich.

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.

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.

¹ Narrower language coverage — no Rust/Dart/Swift (Go and Ruby are now covered). ² Reading lockfiles without a build is the norm today: OSV-Scanner, Trivy and Grype/Syft do it too. For Maven pom.xml specifically, every tool — fad-checker included — must reach Maven Central (or rely on a real build / CycloneDX SBOM) to resolve transitive versions; Trivy can resolve wrong transitive versions in that mode, while fad-checker flags what it can't resolve in chapter 0. The genuine "no build" win is vs Snyk (requires building the project) and OWASP DC (needs Maven Central access for Java accuracy). ³ Phase 1 exports only public coordinates; the online scan never sees your source tree — see Air-gapped / PASSI. 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: continuous CI supply-chain security, container/OS scanning, reachability analysis, auto-fix PRs — reach for Trivy or Grype + Syft. (It now does emit CycloneDX/CSAF and flag licenses + EPSS/KEV, but it isn't a gating CI daemon.)

You don't have to choose — fad-checker takes Snyk's results as input (--snyk) and merges them.

Sources: OSV-Scanner lockfiles · Trivy Java/pom.xml (Maven Central, --offline-scan) · Syft java-pom-cataloger (source dirs) · OWASP DC needs internet/build for Java · Snyk requires building the project · EOL/outdated "most tools skip" (Aikido)

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.