fad-checker

Fucking Autonomous Dependency Checker

fad-checker scans Maven, npm, Yarn, Composer (PHP), PyPI (Python), NuGet (C#/.NET), Go, Ruby, vendored JavaScript and committed native binaries in any source tree — multi-module, monorepo, polyglot, whatever you've got — and produces a single self-contained HTML report with CVE (prioritised by EPSS + CISA KEV), EOL, obsolete, outdated and license findings, plus per-ecosystem fix recipes. It also exports a CycloneDX 1.6 SBOM and a CSAF 2.0 VEX.

🌐 Project site & docs →

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

Why "Autonomous"?

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

Exactly one runtime dependencies must be on PATH (or installed automatically through npm): Node ≥ 20. 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/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

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

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

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

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

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.

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.

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.

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

² 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: 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 · 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.