9pings/fad-checker

# fad-checker [](https://www.npmjs.com/package/fad-checker) [](https://www.npmjs.com/package/fad-checker) [](https://github.com/n8tz/fad-checker/blob/main/package.json) [](https://nodejs.org) `fad-checker` 审计任意源代码树中的 **Maven · npm · Yarn · pnpm · Composer · PyPI · NuGet · Go · Ruby**、vendored JavaScript 以及提交的 native binaries —— 支持多模块、monorepo、多语言混合环境 —— 并生成一个自包含的 **HTML + Word 报告**（按 EPSS + CISA KEV 确定优先级的 CVE、EOL、过时、废弃、许可证），以及 **CycloneDX SBOM / CSAF VEX / SARIF / JSON** 导出。**无需构建工具，无需 Docker，无需联网** —— 它直接从磁盘读取 lockfiles 和 manifests。 🌐 **[项目站点与文档 →](https://n8tz.github.io/fad-checker/)**

## 功能特性 - **一次扫描覆盖 9 大生态系统** —— Maven, npm/Yarn/pnpm, Composer (PHP), PyPI, NuGet, Go, Ruby；以及 **vendored JS**（retire.js）、提交的 **native binaries**（`.dll`/`.exe`/`.so`/`.dylib`，通过 deps.dev + CIRCL 校验和识别）和 **embedded JARs**（fat-jars/war/ear，在内存中解压）。 - **无需构建工具** —— 直接读取 `pom.xml`、`package-lock`/`yarn.lock`/`pnpm-lock`、`composer.lock`、`poetry`/`Pipfile`/`uv`/`pdm` locks、`packages.lock.json`/`*.csproj`、`go.mod`、`Gemfile.lock`。无需 `mvn`/`npm install`/`pip`/`dotnet restore`/`go build`/`bundle`，无需 `node_modules/`。 → [它是如何做到免构建的](docs/COMPARISON.md#how-its-autonomous-no-build-tools) - **合并与优先级排序的 CVE** —— CVEProject + OSV.dev + NVD，交叉比对 CPE/版本以减少误报，按 **CISA KEV → EPSS → CVSS** 排序。 - **基于模块的 Maven 版本调停** —— 恢复被全局 `` 锁定在另一个模块中隐藏的脆弱传递依赖版本（在一个真实的 25 模块 reactor 中，将 Snyk 佐证的覆盖率从 **156 提升至 181**，发现了单次 Snyk 扫描遗漏的 CVE）。 - **Air-gapped / PASSI** —— 在 `--offline` 下**零网络请求**（已经过回归测试），离线 Maven 传递依赖解析，以及 `--osv-db` 用于独立于缓存的离线 OSV 查询。 → [Air-gapped](#air-gapped--passi-audits) - **供应链风险** —— 已知**恶意**安全公告（`MAL-`，始终拦截 CI gate）+ 疑似 **typosquats**（`--typosquat`）。 - **生命周期** —— EOL (endoflife.date)、过时/废弃、版本落后 —— 覆盖所有生态系统。 - **许可证** *(可选启用 `--licenses`)* —— SPDX 标准化，标记 copyleft/专有许可证。 - **输出与 CI** —— HTML + Word `.doc`、CycloneDX 1.6 SBOM、CSAF 2.0 VEX、SARIF 2.1.0、JSON；使用 `--fail-on` 设置拦截门，通过 `--ignore`/`--vex` 进行分类处理。 📖 **[用法与所有 flags](docs/USAGE.md)** · **[架构](docs/ARCHITECTURE.md)** · **[与其他工具的对比](docs/COMPARISON.md)** · **[数据源](docs/DATA-SOURCES.md)** ## 快速开始 ``` npm install -g fad-checker fad-checker -s ./my-project # → ./fad-checker-report/cve-report.html ``` 获取一个免费的 [NVD API key](https://nvd.nist.gov/developers/request-an-api-key)（即刻生效）可以使数据丰富速度提升 10 倍：`fad-checker --set-nvd-key YOUR_KEY`。以下是一些常见的运行方式 —— 完整列表请通过 `fad-checker --help` 或查看 [docs/USAGE.md](docs/USAGE.md)： ``` 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 ``` 单一自包含二进制文件（无需 Node）、源码安装及 shell 补全功能请见 → [docs/USAGE.md](docs/USAGE.md)。 ## 它能发现什么 | 章节 | 数据来源 | 检测内容 | | --- | --- | --- | | **0. 警告** | 本地启发式检测 | 缺失的 lockfiles、未解析的 Maven 版本（由 BOM 管理）、Maven Central 上不存在的私有库 | | **1. CVE（生产环境）** | CVEProject + OSV.dev + NVD + CPE | 生产环境依赖中的公开 CVE / GHSA，按生态系统、manifest 文件划分 —— 每一行均按 CISA KEV + EPSS + CVSS **排定优先级** | | **1B. 嵌入式二进制文件** | 同上（从归档中读取坐标） | **提交的 `.jar`/`.war`/`.ear`** 内部包含的库中的 CVE（vendored 库，Spring-Boot fat-jars，shaded uber-jars） —— 未在任何 `pom.xml` 中声明。按包含它们的归档文件分组 | | **1C. 未管理的 / vendored 二进制文件** | deps.dev + CIRCL（通过校验和） | 没有包管理器控制的、已提交的 **native binaries**（`.dll`/`.exe`/`.so`/`.dylib`） —— 通过哈希识别，并标记为 **应纳入管理**（存在于 registry 中）、**名称≠校验和**（文件名与哈希不符）、**未知**（无来源知晓）或 **恶意**（来自免费的 CIRCL 信号） | | **1D. 未管理的 / vendored JavaScript** | [retire.js](https://retirejs.github.io/) (`--verbose`) | **对提交到代码树中、不受任何包管理器控制的独立 JS 库进行全面盘点**（jQuery, Bootstrap, PDF.js, …） —— 无论是否有漏洞。这是一份网络卫生审查：未知的来源/完整性/补丁情况。使用 `--no-vendored-js-inventory` 跳过 | | **2. Vendored JS（存在漏洞）** | [retire.js](https://retirejs.github.io/) | 上述项中存在已知 CVE/安全公告的子集 —— 没有 lockfile 的陈旧 jQuery/Bootstrap/Angular/PDF.js 副本 | | **3. 开发依赖中的 CVE** | 同上 | 与第 1 章相同，但针对的是 `test`/`provided` (Maven) 以及 `dev`/`optional`/`peer` (npm) | | **供应链风险** | OSV `MAL-…` + 名称启发式检测 | **已知恶意**的包（在任何 `--fail-on` 级别下始终拦截 CI gate）和 **疑似 typosquats**（`--typosquat`：与流行包名称仅有一个编辑距离的 npm/PyPI 名称 —— 如 `lodahs`↔`lodash`） | | **4. EOL 框架** | endoflife.date | Spring Boot 2.5, Hibernate 4.x, EOL JDKs, AngularJS, Laravel/Symfony, Django, .NET 等 | | **5. 废弃的库** | 精选列表 (Maven) + registry 维护者标记 | log4j 1.x, jackson-mapper-asl, joda-time, …；npm `deprecated`、Composer `abandoned`、PyPI `yanked`/不活跃、NuGet `deprecation` | | **6. 过时的库** | Maven Central + npm / Packagist / PyPI / NuGet registries | 可用的更新版本，及其发布日期 | | **7. 许可证** *(可选启用: `--licenses`)* | registry 元数据 + Maven POMs → SPDX 策略 | 每个依赖的许可证被标准化为 SPDX 并进行分类；标记 copyleft (GPL/AGPL/LGPL/MPL)、专有及未知许可证以供审查 | | **8. 修复建议** | 计算生成 | 各生态系统的版本锁定指南：Maven ``、npm `overrides`、yarn `resolutions`、`composer require`、`pip install`、`dotnet add package` | HTML 报告可在任何浏览器中打开，包含所有细节（CVSS 向量、参考链接、完整描述、CPE 配置、传递依赖的 via-paths），并提供与其内容一致的 Word 兼容 `.doc` 副本。每一个匹配项都带有一个 **综合优先级**（KEV 被利用 > EPSS 可能性 > CVSS 严重性），并且运行过程还能额外输出一份 **CycloneDX 1.6 SBOM**（`--report-sbom`，内联包含漏洞信息）和一份 **CSAF 2.0 VEX**（`--report-csaf`），供下游工具使用。

## Air-gapped / PASSI 审计 当被审计系统处于 **离线 / 保密** 状态时（PASSI 项目的典型情况），它 无法访问 OSV / NVD / Maven Central / npm。在确保安全隔离区 **零环境信息** 外泄的前提下，将工作分配到不同机器上完成：一份匿名化的描述文件仅携带 **公开的包坐标** —— 没有文件系统路径，没有 registry URLs， 没有主机名/用户名 —— 并且 **详细的报告会在离线机器上重新生成**。 这种传输依赖于 fad-checker 缓存的一个特性：它们以 *坐标* 或 *漏洞 ID* 为键， 从不以路径为键，因此它们是 **与机器无关的**。联网步骤仅仅是 **预热缓存**；离线步骤重放扫描过程并获得缓存命中。 ``` # ── 阶段 1 — OFFLINE (被审计机器)：导出匿名化 descriptor ── # 使用 -e 排除私有/内部包（离线状态下我们无法区分私有与公开）。 fad-checker -s ./proj -e "^(client|internal)\." --export-anonymized deps.json # → deps.json：仅包含公开 coordinates。在离开 enclave 前对其进行审查。 # ── 阶段 2 — ONLINE (任意机器，无需源码)：预热 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/ # ── 阶段 3 — OFFLINE (被审计机器)：完整报告，所有本地上下文 ── fad-checker --import-cache fad-cache.tar.gz fad-checker -s ./proj --offline # re-collect locally (real paths) + cache hits # → 包含 manifests 和结构的完整 HTML/.doc 报告，在 enclave 内部生成。 ``` 描述文件（`fad-deps/1`）保留与丢弃的内容对比： | 保留（扫描所需） | 丢弃（环境信息） | | --- | --- | | ecosystem, ecosystemType | manifest 路径 / pom 路径 | | namespace, name | 已解析的 registry URLs | | version, versions | 完整性哈希 | | scope, isDev | 父级链、lockfile 类型 | 在线阶段的报告本身也不包含路径；vendored-JavaScript（retire.js）的发现 是在 **第 3 阶段离线生成的**，因为 retire 需要实际的 `.js` 文件 —— 它的特征库 在联网时（第 2 阶段）被预热，并通过 `--export-cache` 传输。完整的离线/缓存控制 → [`docs/USAGE.md`](docs/USAGE.md)。 ## 文档 - [`docs/USAGE.md`](docs/USAGE.md) — 所有 flags 与工作流：离线/缓存控制、私有 registries、配置文件、使用指南、安全防护。 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — 内部原理：编解码器、收集、匹配、报告流水线。 - [`docs/COMPARISON.md`](docs/COMPARISON.md) — 对比 OSV-Scanner / Trivy / Grype / OWASP DC / Snyk，以及它是如何做到免构建的。 - [`docs/DATA-SOURCES.md`](docs/DATA-SOURCES.md) — fad-checker 使用的公开数据集及其许可证。 - [`CHANGELOG.md`](CHANGELOG.md) · [`CLAUDE.md`](CLAUDE.md) — 发布历史 · 面向贡献者的代码级导航。 ## 许可证 MIT — 详见 [`LICENSE`](LICENSE)。

标签：MITM代理, SBOM生成, 依赖审计, 安全合规, 文档结构分析, 暗色界面, 网络代理, 自定义脚本