more-than-hacking/Dementor-SCA-Scanner

# Dementor — SCA 扫描器 **真正能触达你代码的 CVE。** **具备可达性感知的软件成分分析（SCA）。** 大多数 SCA 工具会把你淹没在那些你几乎没怎么用到的库的“严重”CVE 中。Dementor 只回答那个最关键的问题： **漏洞代码在你的代码中是否真正可达 —— 并且能否被利用？** 它在**两种模式**下运行： - **常规扫描** *（默认，无需 API key，免费）* — 使用 tree-sitter 调用图 + 符号分析进行确定性的可达性检测。告诉你一个已知的漏洞函数在你的代码中是否被真正**调用**（`latent` → `imported-unused` → `reachable`）。 - **AI 扫描** *（自带 LLM key）* — 包含常规扫描的所有功能，**外加**一层判断*可利用性*的 AI 分析：不可信的输入是否到达了调用点？是否已被缓解？是否是真实的主动漏洞利用？它将“64 个可怕的严重漏洞”转化为“6 个真正重要且有证据支撑的漏洞”。 完全开源。漏洞数据（OSV、EPSS、CISA KEV）**无需 key 且免费**。AI 层采用**自带 key** 模式 —— 在 Google Gemini 免费层上是免费的，规模化使用也只需几美分。 ## 它是如何决策的（各个层级） | 层级 | 需要 key？ | 解决的问题 | |---|---|---| | **1. 检测** — 依赖解析 + 与 [OSV](https://osv.dev) 进行精确版本匹配，包括 **transitive** 依赖（lockfiles） | ❌ | *存在哪些易受攻击的库？* | | **2. 优先级排序** — [EPSS](https://www.first.org/epss/) 漏洞利用概率 + [CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) | ❌ | *哪些 CVE 在现实中正被积极利用？* | | **3. 可达性** — tree-sitter 调用图 + 易受攻击符号匹配 | ❌ | *漏洞函数是否在我的代码的实际调用路径上？* | | **4. 可利用性** — 感知 CVE 的 LLM 分析，具备缓解感知能力 | ✅ (AI 扫描) | *可达**且**可利用 —— 带有证明链和缓解措施。* | 第 1–3 层是**确定性的事实**。第 4 层是 **AI 辅助的判断** —— 具有非确定性，旨在供人工审查。这种分离是刻意为之的：我们绝不会将猜测作为事实呈现。 ## 快速开始 (Docker) ``` git clone dementor cd dementor cp .env.example .env # then edit .env docker compose up --build # 打开 http://localhost:5000 ``` **常规扫描**（无 AI）所需的最低限度 `.env` 配置： ``` GITHUB_TOKEN=ghp_your_token_here # repo (private) or public_repo; read:org for whole-org scans ORG_NAME=your-github-org ``` 添加以下配置以解锁 **AI 扫描**（自带 key —— 支持 Gemini 免费层）： ``` LLM_PROVIDER=gemini # gemini | openai | anthropic LLM_API_KEY=your_key # https://aistudio.google.com/apikey LLM_MODEL=gemini-2.5-flash ``` 有关所有选项（rate-limit backoff、worker 数量、定价覆盖等），请参见 [`.env.example`](.env.example)。 ### 不使用 Docker 运行 ``` pip install -r requirements.txt python server.py # http://localhost:5000 (PORT=5050 to change) ``` ## 导入代码库 — GitHub *或* 本地上传 | 来源 | 方式 | |---|---| | **GitHub** | Config 标签页 → 保存 token + 组织 → **Fetch all from GitHub**，或通过 `owner/repo` / URL 进行扫描 | | **本地上传** | Repositories 标签页 → **Upload repo(s)** → 选择一个或多个 **`.zip`** 文件（无需 GitHub，无需 token） | 上传的代码库会在本地解压（带有 zip-slip 保护），标记为 **local**，并像克隆的代码库一样进行扫描 —— 非常适合扫描你无法或不愿推送到 GitHub 的代码。 ## 使用仪表盘 1. **Config** — token + 组织（可选），选择 **Scan mode**：*Normal*（默认）或 *AI scan*。 2. **Repositories** — 从 GitHub 获取或上传 `.zip` 文件；对每一个进行 **Scan** / **Re-scan**；固定 **Keep** 以保留克隆；**Clear findings**（保留克隆）或 **Delete repo**（移除克隆及扫描结果）。 3. **Scans** — 每个任务有实时流式日志；随时 **Stop** 正在运行的扫描；历史记录在重启后依然保留。 4. **Results** — 扫描结果根据可达性 + 威胁情报进行排名；支持逐行 **Delete**；点击某一行可查看证据：高亮的漏洞代码行、调用路径、缓解措施和 CVE 详情。 5. **Reachability** — 包含其数据流路径的可利用性扫描结果。 ### 可达性判定结果的含义 | 判定 | 含义 | |---|---| | **Latent** | 在清单文件中声明，但未在代码中导入/使用 | | **Imported-unused** | 使用了该库，但未调用*有漏洞的*函数 | | **Reachable** | 漏洞函数实际上被调用了（确定性） | | **Active exploit** *(仅限 AI 扫描)* | 可达**且**存在触发条件，无缓解措施 | ## 磁盘与留存 - **Git 克隆默认在每次扫描后释放**（扫描结果保留在报告中；重新扫描会再次克隆）。保持磁盘占用极小 —— 这在 Docker 中很重要。 - 在任何代码库上固定 **Keep** 即可保留其源码（用于数据流视图 + 快速重新扫描）。 - **上传的代码库始终会被保留** —— 它们的文件是唯一的副本。 ## 支持的语言 / 生态系统 | 语言 | 清单文件 | 传递性解析 | 调用图 | |---|---|---|---| | Python | `requirements.txt`, `Pipfile.lock`, `poetry.lock`, `pyproject.toml` | ✅ lockfiles | ✅ | | Node.js | `package.json`, `package-lock.json` (v1/v2/v3) | ✅ lockfiles | ✅ | | Java (Maven) | `pom.xml` | ✅ `mvn dependency:tree` (可选开启) | ✅ | | Go | `go.mod`, `go.sum` | ✅ `go list -m all` (可选开启) | ✅ | 基于工具的传递性解析（Maven/Go）可通过 `DEMENTOR_TOOL_RESOLVE=1` 选择开启。所有生态系统都会从 OSV 获取 CVE 数据。基础设施文件（Dockerfiles、shell、CI YAML）也会被扫描。 ## 架构 ``` dependency_parser → OSV match (+ transitive) → EPSS/KEV enrich │ reachability_scan ┌────────────┴─────────────┐ Normal (no AI) AI scan (LLM) tree-sitter call graph + exploitability / mitigation + symbol matching judgment on the reachable set └────────────┬─────────────┘ reconciled verdict → dashboard ``` 关键模块：[`server.py`](dementor_sca/server.py) (Flask API + SSE), [`scan_runner.py`](dementor_sca/scan_runner.py) (后台编排器), [`reachability_scan.py`](dementor_sca/reachability_scan.py) (检测 + 确定性/AI 可达性分析), [`callgraph.py`](dementor_sca/callgraph.py) (tree-sitter 调用图), [`pipeline_zero_fp.py`](dementor_sca/pipeline_zero_fp.py) (OSV + 符号提取), [`threat_intel.py`](dementor_sca/threat_intel.py) (EPSS/KEV), [`transitive_resolver.py`](dementor_sca/transitive_resolver.py)。 ## 测试 ``` for t in tests/test_*.py; do python "$t"; done # 15 test suites python benchmark/run_benchmark.py # reachability micro-benchmark ``` 基准测试是一个针对*确定性*引擎（无 LLM）的**精选微型基准测试**：包含 14 个手写的 Python/JS/Java/Go 案例 —— 其中 8 个真正可达，6 个为 latent —— 它们会通过真实的 tree-sitter 调用图运行。在这个受控集合中，它能将 reachable 和 latent 完全区分开，没有任何假阳性/假阴性（相比之下，简单的“标记一切”基线准确率仅为 ~57%）。这是该引擎在构造案例上的演示，**并非**声称在任意的真实代码上具备完美的准确性；它还**记录了其已知遗漏的缺口**（变量/数据流别名），而不是将其隐藏。 ## 客观的局限性 - **确定性可达性是由符号驱动的。** 当安全公告指明了漏洞函数时（大多数都会这么做），常规模式能精准定位它。当 OSV 列出*没有*函数名时，常规模式只能确认该库已被导入 —— **AI 扫描**会阅读 CVE 描述来填补这一空白。 - **AI 可利用性判定是非确定性的**，偶尔可能会夸大或低估风险。它旨在*为人类进行优先级排序*，而不是取代人工审查。底层事实（检测、版本匹配、调用路径）是确定性且可复现的。 - **尚无运行时/动态分析**（eBPF/IAST）—— 可达性目前是静态的。请参见 `ROADMAP.md`。 ## 配置参考 | 环境变量 | 用途 | 默认值 | |---|---|---| | `GITHUB_TOKEN`, `ORG_NAME` | GitHub 访问权限 | — | | `LLM_PROVIDER` / `LLM_API_KEY` / `LLM_MODEL` / `LLM_API_URL` | AI 扫描 (自带 key) | gemini / — / gemini-2.5-flash | | `PORT` | 服务器端口 | 5000 | | `REACHABILITY_WORKERS` | 并行可达性分析 worker 数 | 4 | | `LLM_MAX_RETRIES` / `LLM_BACKOFF_BASE` / `LLM_BACKOFF_MAX` | Rate-limit backoff | 5 / 2 / 60 | | `DEMENTOR_TOOL_RESOLVE` | 启用 Maven/Go 传递性解析 | off | | `DEMENTOR_MAX_UPLOAD_MB` | 最大代码库上传大小 | 500 | 凭据也可以存放在 `config/org_config.yaml` 中（已在 gitignore 中忽略）；环境变量优先级更高。 ## License **MIT** — 详见 [`LICENSE`](LICENSE)。© More Than Hacking (MTH) — Yaswanth Sivadanam。第三方 依赖许可证（全部与 MIT 兼容；无 GPL/AGPL）已记录在 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) 中。漏洞数据 © 其各自来源 (OSV, FIRST/EPSS, CISA)。

标签：人工智能, 可达性分析, 漏洞优先级评估, 用户模式Hook绕过, 请求拦截, 逆向工具