MortalYar/nvd-vault

# NVD Vault **English** · [Русский](README.ru.md) 一款用于开源资产清单漏洞审计的本地桌面应用程序，利用 CVSS、EPSS 和 CISA KEV 进行基于风险的补丁优先级排序。 接收 `inventory.json` 或 SBOM (CycloneDX / SPDX) 作为输入。生成一个链接了 Markdown 笔记（CVE / Product / CWE）的 **vault**，外加内置支持全文搜索、关系图和分析仪表盘的浏览器。     ## 为什么开发这个工具 标准安全工程师场景：“我们有 Kibana 8.19, Logstash 8.19, OpenSSL 3.0 和 nginx 1.24 —— 哪些是关键漏洞，我们应该优先修补哪些？” NVD Vault 会自动回答这些问题： 1. 提取软件和版本列表。 2. 调用 NVD API 并查找每个产品的所有 CVE。 3. 使用 EPSS 数据（被利用概率）和 CISA KEV（已知主动被利用）丰富结果。 4. 生成具有清晰分层的优先级列表：`critical_now` / `critical_likely` / `high` / `medium` / `low`。 5. 将所有内容以 Markdown 形式存储在本地 —— 可以在 Obsidian 中打开，交给审计员，或在内置 UI 中浏览。 与 Snyk 或 GitHub Dependabot 等 SaaS 扫描器不同，**一切都在本地运行** —— 你的资产清单永远不会离开本机。只有包含组件名称的公共 NVD API 请求会发送出去。 ## 功能 - 从 `inventory.json` 或 SBOM (CycloneDX / SPDX) 构建 vault - 通过 NVD CPE 字典自动发现供应商 - 精确的 CPE 2.3 匹配，支持版本范围和预发布版本 - 基于风险的优先级排序：**CVSS + EPSS + CISA KEV** - Markdown 知识图谱，在 CVE、产品和 CWE 之间带有 `[[wiki-links]]` - 带有 KPI 和风险分析的交互式仪表盘 - 通过 SQLite FTS5 进行全文搜索 - 通过 Cytoscape.js 实现交互式图表可视化（支持导出 PNG） - 将 vault 导出为 ZIP 压缩包 - GUI 和 CLI 模式 - CISA KEV 目录缓存（1 小时 TTL） —— 加速重复扫描 - 稳健的 NVD 速率限制处理，无误报失败 ## 快速开始 ### 安装 ``` git clone https://github.com/MortalYar/nvd-vault.git cd nvd-vault python -m pip install -e ".[dev]" ``` ### 启动 GUI ``` nvd-vault ``` 或等同命令： ``` python app.py ``` ### 通过 CLI 构建 vault ``` nvd-vault build examples/sample_inventory.json --out ./vault ``` 如果省略 `--out`，程序将以交互方式请求输出路径。 ## 清单格式 ``` { "vault_name": "Production_ELK_Cluster", "products": [ { "name": "kibana", "version": "8.19.9", "vendor": "elastic" }, { "name": "logstash", "version": "8.19.5", "vendor": "elastic" }, { "name": "openssl", "version": "3.0.11", "vendor": "openssl" } ] } ``` `vendor` 字段是可选的 —— 如果省略，NVD Vault 将尝试通过 CPE 字典自动查找供应商。如果存在多个候选供应商，GUI 将打开一个选择对话框。 ### 支持的 SBOM 格式 - **CycloneDX JSON**（`bomFormat: "CycloneDX"`） - **SPDX JSON**（存在 `spdxVersion` 字段） ``` nvd-vault build sbom.cyclonedx.json --input-format sbom --out ./vault ``` 格式自动检测基于 JSON 内容： ``` nvd-vault build sbom.cyclonedx.json --out ./vault ``` ## 生成的 vault 结构 ``` vault/ ├── meta.json # vault metadata (name, build date, statistics) ├── search.db # SQLite FTS5 index ├── cves/ │ ├── CVE-2024-XXXXX.md │ └── ... ├── products/ │ ├── kibana.md # vulnerability summary per product │ └── ... └── cwes/ ├── CWE-79.md └── ... ``` 每个 `.md` 笔记都有一个包含元数据（CVSS、EPSS、KEV、勒索软件标志、风险等级）的 YAML frontmatter，以及带有指向其他笔记的 `[[wiki-links]]` 的易读正文。 该 vault 完全**兼容 Obsidian** —— 你可以将该文件夹作为 Obsidian Vault 打开，并在其基础上使用其功能（图谱、搜索、插件）。 ## 风险优先级模型 | 等级 | 条件 | 操作建议 | |---|---|---| | `critical_now` | 列入 CISA KEV（在野外被主动利用） | **立即修补**，视为 P0 | | `critical_likely` | EPSS ≥ 0.7（未来 30 天内被利用的概率很高） | 在几天内修补 | | `high` | CVSS ≥ 8.0 或 EPSS ≥ 0.3 | 安排至下一个补丁窗口 | | `medium` | CVSS ≥ 5.0 | 标准工作流程 | | `low` | 其他所有情况 | 伺机修补 | ### 这些缩写代表什么 - **CVSS** (Common Vulnerability Scoring System) —— 范围从 0.0 到 10.0 的标准化严重程度评分。它考虑了攻击向量、利用复杂性、所需权限以及对机密性/完整性/可用性的影响。仅凭 CVSS 只能告诉你“如果被利用会有*多糟*”，而不知道“被利用的*可能性*有多大”。 - **EPSS** (Exploit Prediction Scoring System) —— 未来 30 天内被利用的概率，数值范围从 0.0 到 1.0。由 FIRST 使用基于真实攻击、漏洞利用工具包以及 Twitter/GitHub 提及训练的机器学习模型每日计算。它补充了 CVSS：高 CVSS + 低 EPSS 意味着“理论上有危险，但没有人攻击它”；低 CVSS + 高 EPSS 意味着“正在被主动利用”。 - **CISA KEV** (Known Exploited Vulnerabilities) —— **已确认被主动利用的**漏洞目录。由美国网络安全和基础设施安全局维护。如果某个 CVE 在 KEV 中，说明它正被用于真实攻击，你应该早就打好补丁了。 ## 获取 NVD API 密钥 对于包含 5-10 个以上产品的任何构建，**强烈建议**使用。 | 无密钥 | 有密钥 | |---|---| | 5 次请求 / 30 秒 | 50 次请求 / 30 秒 | | 构建 20 个产品 ≈ 2 分钟 | 构建 20 个产品 ≈ 12 秒 | 可在此处获取免费 API 密钥： 密钥将在几分钟内通过电子邮件发送。用法： ### PowerShell (Windows) ``` $env:NVD_API_KEY="your_api_key_here" ``` 或永久设置： ``` [Environment]::SetEnvironmentVariable("NVD_API_KEY", "your_api_key_here", "User") ``` ### Linux / macOS ``` export NVD_API_KEY="your_api_key_here" ``` CLI 也直接接受密钥： ``` nvd-vault build inventory.json --api-key your_api_key_here --out ./vault ``` ## 用户界面 应用程序有四个标签页： - **Build Vault** —— 资产清单编辑器 + 构建运行器。加载现有 JSON 或手动构建列表，通过 NVD 自动发现供应商。 - **Dashboard** —— vault 的 KPI（总 CVE、被利用、勒索软件、CISA 逾期）、顶级产品和 CWE、修复计划。 - **Graph** —— CVE、产品和 CWE 之间链接的 Cytoscape 可视化图表。按风险等级过滤，导出为 PNG。 - **Browse Vault** —— 笔记浏览器，带有风险等级高亮、KEV/勒索软件图标、全文搜索和 wiki-link 导航。 ## 与其他工具的比较 | 工具 | 类型 | 资产清单来源 | 风险评分 | 仅限本地 | 开源 | |---|---|---|---|---|---| | **NVD Vault** | 桌面 GUI | 手动 JSON / SBOM | CVSS + EPSS + KEV | 是 | 是 (MIT) | | Snyk | SaaS | git/SBOM 自动 | 专有 | 否 | 免费增值 | | GitHub Dependabot | SaaS | 仓库自动 | CVSS | 否 | 是（针对公开仓库） | | OWASP Dependency-Check | CLI | maven/gradle/npm 等 | CVSS | 是 | 是 | | Trivy | CLI | 容器/SBOM/仓库 | CVSS | 是 | 是 | | Grype | CLI | SBOM | CVSS | 是 | 是 | | Vulners | SaaS | 手动 API | CVSS+exploit | 否 | 免费增值 | **在以下情况下选择 NVD Vault：** - 你需要进行**本地**审计，而不将数据发送到云端。 - 你希望基于 EPSS+KEV 进行优先级排序，而不仅仅是 CVSS。 - 你希望得到**链接的 Markdown 笔记**以便进一步处理（报告、工单、文章），而不仅仅是一个扁平的 CVE 列表。 - 你的资产清单是“运行在生产服务器上的软件列表”，而不是构建产物。 **在以下情况下选择其他工具：** - 你需要在每次拉取请求时进行 CI/CD 集成 → Trivy / Grype / Dependabot。 - 你正在扫描 Docker 镜像 → Trivy / Grype。 - 你有包含包管理器依赖项的 Java/Node 项目 → OWASP Dependency-Check。 - 你需要供整个团队使用的企业级仪表盘 → Snyk / Vulners / 类似工具。 ## 常见问题 ### 我应该多久重建一次 vault？ 每当你的软件资产清单发生更改时，或者当你想要最新的 CVE/EPSS/KEV 数据时。NVD **每天**更新 CVE；EPSS 和 KEV 也是每天更新。使用 API 密钥重建一个包含 30 个产品的 vault 需要 30-60 秒。 ### NVD 不可用 / 403 / 速度慢 NVD 偶尔会出现中断。NVD Vault 能正确处理速率限制（无密钥 5 次请求/30秒，有密钥 50 次请求/30秒），并在遇到 5xx 错误时自动重试。如果你在没有密钥的情况下一直收到 403 —— 请获取一个密钥（见上文）。 ### 它可以离线工作吗？ 构建完成后 —— **可以**：vault 浏览、图表、搜索和 ZIP 导出都不需要网络。构建本身需要访问 `services.nvd.nist.gov`、`api.first.org` (EPSS) 和 `cisa.gov` (KEV)。 UI 部分依赖于 Google Fonts CDN —— 在没有互联网的情况下，字体将回退到系统默认值，但功能不受影响。JS 库（cytoscape, marked）在本地进行了 vendor 引入。 ### 启动时伴随 `ImportError: webview` 崩溃 Virtualenv 未激活或依赖未安装： ``` # Linux/macOS source venv/bin/activate python -m pip install -e ".[dev]" ``` ``` # Windows .\venv\Scripts\Activate.ps1 python -m pip install -e ".[dev]" ``` ### vault 显示“0 个产品，0 个 CVE” 很可能是因为未能自动检测到供应商。可能的原因： 1. 产品名称与 NVD 中的叫法不匹配（例如，`apache` 对应 `httpd`）。打开 ，找到你的产品，查看其 CPE 名称，并更新资产清单。 2. 缺少 vendor 字段且自动发现未返回结果。通过 GUI 手动设置（供应商输入框旁边的放大镜按钮）。 3. 版本格式是 NVD 无法识别的（例如，特定发行版的后缀）。尝试使用纯净的上游版本。 ### 我可以将其用于商业用途吗？ 可以 —— MIT 许可证。 ### 版本比较准确吗？ NVD Vault 使用 `packaging.version` (PEP 440)，它可以正确处理大多数开源版本方案，包括预发布版本（`1.0.0-rc2 < 1.0.0-rc10 < 1.0.0`）。对于特殊版本（例如，发行版风格的 `5.7.32-0ubuntu0.18.04.1`），有一个后备解析器。如果你遇到比较不正确的情况 —— 请提交 issue。 ### 我该怎么处理长长的 `critical_now` 列表？ `critical_now` 意味着“CISA 已确认存在主动利用”。即使 CVSS 不是最高，这些也是 P0 级别。按照在你基础设施中存在的顺序进行修补，从外部暴露的系统开始。 ## 故障排除 **问题：** 运行 `python app.py` 打开一个空白黑窗口 **修复：** 验证 `nvd_vault/webui/vendor/` 目录不为空（包含 5 个 JS 文件：marked、cytoscape、cose-bilkent 插件）。如果为空 —— 重新克隆仓库或按照 `vendor/` 中的 README 获取文件。 **问题：** `ModuleNotFoundError: No module named 'packaging'` **修复：** 你从旧版本升级了。再次运行 `pip install -e ".[dev]"` 以刷新依赖项。 **问题：** 所有 CVE 都显示为 `low` 级别，而它们本应是关键级别 **修复：** EPSS/KEV 丰富静默失败了。验证你的网络可以访问 `api.first.org` 和 `cisa.gov`。构建时的日志（`logger.warning`）将显示是否有任何请求失败。 **问题：** Vault 构建卡在单个产品上 **修复：** 该产品可能在 NVD 中有数千个 CVE，分页速度很慢。有了 API 密钥，速度会快很多。你可以在 GUI 构建日志（Build 标签页，底部的日志）中监控进度。 **：** 图表为空或看起来很奇怪 **修复：** 只有当 vault 中包含笔记之间的**链接**（通过 `[[wiki-link]]`）时，图表才会渲染。如果你只有没有 CVE 的产品 —— 就没有链接，图表也会是空的。这是预期行为。 ## 开发 ### 运行测试 ``` python -m pytest -v ``` CI 通过 GitHub Actions 配置，在每次推送和 PR 时运行。 ### 项目结构 ``` nvd-vault/ ├── app.py # entry point (CLI + GUI) ├── nvd_vault/ │ ├── core/ # business logic │ │ ├── nvd_client.py # NVD API HTTP client │ │ ├── enrichment.py # EPSS, KEV, risk score │ │ ├── matcher.py # CPE 2.3 + version comparison │ │ ├── frontmatter.py # YAML frontmatter parser │ │ ├── vault_builder.py # build orchestrator │ │ ├── markdown_writer.py │ │ ├── dashboard.py │ │ ├── graph_builder.py │ │ ├── search_index.py # SQLite FTS5 │ │ ├── remediation.py │ │ ├── inventory.py # inventory.json parser │ │ └── sbom.py # CycloneDX/SPDX parser │ ├── api/ │ │ └── bridge.py # JS↔Python API via pywebview │ └── webui/ │ ├── index.html │ ├── css/ │ ├── js/ │ └── vendor/ # vendored cytoscape, marked ├── tests/ └── examples/ # sample inventory and SBOM files ``` ### 贡献 欢迎提交 PR。提交前： 1. 运行测试（`pytest`）。 2. 如果你更改了逻辑 —— 请为其添加测试。 3. PR 描述使用任何一种语言（EN 或 RU）都可以。 ## 限制 - 针对目标是 **Application CPE** (`cpe:2.3:a:`)。不支持 OS-CPE 和 Hardware-CPE。 - 结果质量取决于 **NVD 中的 CPE 覆盖范围**。如果 NVD 尚未为产品标记 CPE，vault 将无法发现它。 - CVE 描述保留为**英文**（与 NVD 中一样）。 - 主要在 **Windows 11** 上进行开发和测试。Linux 和 macOS 应该可以工作（pywebview 是跨平台的），但测试不够全面。 - **不专为 Docker 镜像扫描设计** —— 请使用 Trivy 或 Grype。 ## 相关项目 - [nvd-scanner](https://github.com/MortalYar/nvd-scanner) —— 本项目的 CLI 前身 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。

标签：CISA KEV, CPE匹配, CVE审计, CVSS, CycloneDX, EPSS, GPT, Markdown, NVD API, Obsidian, Python, SBOM, SPDX, SQLite, 全文搜索, 无后门, 无线安全, 本地应用, 桌面应用, 漏洞管理, 硬件无关, 网络安全, 网络安全审计, 补丁优先级, 逆向工具, 隐私保护