Elkhan-Isayev/cve-scanner
GitHub: Elkhan-Isayev/cve-scanner
一款全栈 CVE 漏洞扫描器，通过将软件组件与实时 NVD 数据源进行 SemVer 版本匹配来检测已知漏洞，并提供交互式图表可视化和 PDF 报告导出功能。
Stars: 0 | Forks: 0
# 🛡️ CVE Scanner
一款全栈 CVE（常见漏洞和暴露）扫描器，可将您的软件组件与**实时 NVD 数据源**进行匹配，将结果可视化为交互式**图表**（使用 [React Flow](https://reactflow.dev) 构建），并生成可下载的 **PDF 报告**，其中包含针对每项发现的通俗语言解释和修复建议。
## 功能
- **实时 CVE 数据库** — 在启动时以及可配置的定时器上，从官方 [NVD 2.0 API](https://services.nvd.nist.gov/rest/json/cves/2.0) 拉取最近修改的 CVE。同时内置了一份精选的知名 CVE 种子数据集（Log4Shell、Heartbleed、原型链污染、ReDoS 等），因此扫描器完全可以离线工作。
- **逐个 CVE 的检测逻辑** — 一个感知 SemVer 的匹配引擎会根据每个受影响的版本范围（`versionStartIncluding` / `Excluding`、`versionEndIncluding` / `Excluding` 以及精确的 CPE 锁定）对每个组件进行评估。请参阅[检测逻辑的工作原理](#how-the-check-logic-works)。
- **交互式图表** — 扫描结果被渲染为 `扫描目标 → 组件 → CVE` 节点，其边缘根据严重程度进行着色和动画处理，并配有小地图和控制控件。
- **可下载的 PDF 报告** — 包含执行摘要、严重程度分类，以及每个 CVE 的详细部分（描述、CVSS、CWE、参考链接和具体的建议）。
- **全面测试** — 43 个单元/集成测试，涵盖版本比较器、范围匹配、扫描器、图表构建器、NVD 数据标准化和 HTTP API。
- **Docker 化** — 只需一条 `docker compose up` 命令即可启动 API 和 Web UI。
## 架构
```
┌─────────────────────────────┐ ┌──────────────────────────────────────┐
│ Frontend (React + Vite) │ │ Backend (Node + Express + TS) │
│ - React Flow graph │ HTTP │ - CveDatabase (NVD feed + seed) │
│ - Scan form / findings │ ─────▶ │ - Matching engine (matcher.ts) │
│ - PDF download │ │ - Scanner + graph builder │
│ served by nginx (:8080) │ │ - PDF report (pdfkit) (:4000) │
└─────────────────────────────┘ └──────────────────┬───────────────────┘
│ periodic refresh
▼
https://services.nvd.nist.gov (NVD 2.0)
```
## 快速开始（Docker）
```
# 实时的 NVD feed（默认）。添加 NVD_API_KEY 以获得更高的速率限制。
docker compose up --build
# 或者仅使用内置的种子 CVE 完全离线运行：
CVE_OFFLINE=true docker compose up --build
```
然后打开：
- **Web UI** → http://localhost:8080
- **API** → http://localhost:4000/api/health
## 快速开始（本地，不使用 Docker）
**后端**
```
cd backend
npm install
npm run dev # http://localhost:4000 (live NVD feed)
# CVE_OFFLINE=true npm run dev # 离线 / 仅限种子
```
**前端**
```
cd frontend
npm install
npm run dev # http://localhost:5173 (proxies /api to :4000)
```
## 检测逻辑的工作原理
数据库中的每个 CVE 都带有源自其 NVD CPE 匹配项的一个或多个**受影响范围**。当**同时**满足以下两个条件时，组件将被报告为容易受到某个 CVE 的攻击：
1. **产品匹配** — 组件名称（或其显式指定的 `product` 字段）等同于受影响的产品，比较时不区分大小写，并将 `_`/空格统一规范化为 `-`。
2. **版本在范围内** — [`backend/src/cve/matcher.ts`](backend/src/cve/matcher.ts) 中的 `versionInRange()` 会根据范围边界对版本进行评估：
| 范围字段 | 含义 |
|----------------------------|--------------------------------------|
| `exactVersion` | 仅当 `version == pin` 时存在漏洞 |
| `versionStartIncluding: X` | 要求 `version >= X` |
| `versionStartExcluding: X` | 要求 `version > X` |
| `versionEndIncluding: Y` | 要求 `version <= Y` |
| `versionEndExcluding: Y` | 要求 `version < Y` |
| *(无边界)* | 该产品的所有版本均受影响 |
版本比较（`compareVersions`）能够感知 SemVer：它会对版本进行标记化处理，按数字方式比较数字段，将末尾的零视为相等（`1.2 == 1.2.0`），并将预发布版本的等级排在其正式发布版本之下（`1.0.0-beta < 1.0.0`）。
然后，扫描器会为每项发现附加一个**建议的修复版本**（如果可用，则为较低的排他性结束边界）以及人类可读的**建议**。
## API
| 方法 | 路径 | 描述 |
|--------|--------------------------|---------------------------------------------------------|
| GET | `/api/health` | 服务状态 + 数据库大小 / 最后更新时间 |
| GET | `/api/database` | 数据库中的 CVE ID、严重程度、得分列表 |
| POST | `/api/database/refresh` | 强制从 NVD 实时拉取 |
| POST | `/api/scan` | 扫描组件 → `{ scan, graph }` |
| POST | `/api/report` | 扫描组件 → 可下载的 PDF 报告 |
**扫描请求体**
```
{
"components": [
{ "name": "log4j-core", "version": "2.14.1" },
{ "name": "lodash", "version": "4.17.20", "product": "lodash" }
]
}
```
试一试：
```
curl -X POST http://localhost:4000/api/scan \
-H 'Content-Type: application/json' \
-d @sample-sbom.json | jq '.scan.summary'
curl -X POST http://localhost:4000/api/report \
-H 'Content-Type: application/json' \
-d '{"components":[{"name":"log4j-core","version":"2.14.1"}]}' \
--output report.pdf
```
Web UI 接受自由格式的输入：每行一个 `name version`（或 `name@version`），或者粘贴的 `package.json` 依赖块。
## 配置（后端环境变量）
| 变量 | 默认值 | 描述 |
|-----------------------|---------|-------------------------------------------------------|
| `PORT` | `4000` | HTTP 端口 |
| `CVE_OFFLINE` | `false` | `true` 禁用实时 NVD 拉取（仅限种子数据） |
| `CVE_REFRESH_MINUTES` | `120` | 实时数据源的自动刷新间隔 |
| `CVE_WINDOW_DAYS` | `30` | 回溯拉取已修改 CVE 的时间跨度（NVD 上限为 120） |
| `NVD_API_KEY` | — | 可选的 NVD API 密钥，用于提高速率限制 |
## 测试
```
cd backend
npm test
```
涵盖版本比较器、范围匹配、产品匹配、扫描器严重程度排序 + 建议、图表构建、NVD 数据标准化，以及通过 supertest 进行的完整 HTTP API 测试（包括 PDF 的 `%PDF` 标头）。
## 项目布局
```
cve-scanner/
├── backend/
│ ├── src/
│ │ ├── cve/ # types, matcher, scanner, NVD client, database
│ │ ├── graph/ # React Flow graph builder
│ │ ├── report/ # PDF generation
│ │ ├── routes/ # Express API
│ │ ├── data/ # bundled seed CVEs
│ │ └── server.ts
│ └── tests/ # Jest test suites
├── frontend/
│ └── src/ # React + React Flow UI
├── docker-compose.yml
└── README.md
```
## 免责声明
CVE 匹配基于名称/版本，可能会产生误报，或者遗漏特定于供应商的细微差别。在采取行动之前，请务必根据您的实际环境验证结果。本工具仅供防御性安全及教育用途。
## 许可证
MIT
标签：CVE, MITM代理, 加密, 数字签名, 漏洞扫描器, 网络测绘, 自动化攻击, 请求拦截