VulnReach

运行时感知的 SCA —— 证明哪些 CVE 实际可达，而不仅仅是已安装。

VulnReach 现已成为官方 OWASP 项目。 🎉

演示

第 1 步 —— SCA 在依赖项中暴露出 74 个 CVE

第 2 步 —— VulnReach 证明其中哪些实际可达

---

发现结果 —— 每个 CVE 的证据链

仪表盘 —— 9 个仓库中确认 42 个可达

语言支持： Python 已完全达到生产就绪（污点分析、AST、路由、运行时）。Java 和 JavaScript 具备可用的调用图分析，处于实验阶段。Go、C# 和 PHP 在路线图中。详情见 ROADMAP.md。

VulnReach 在标准 SCA 输出之上构建，通过添加可达性上下文——借助静态分析、污点追踪和实时运行时覆盖，证明检测到的 CVE 中哪些实际可在你的应用程序中到达。

---

项目状态

最新开发进展（已发布）

• 依赖感知的并行运行器流水线，加快扫描速度
• Python 可达性 —— 生产就绪（污点分析、AST、路由、运行时各层均可用）
• Java 可达性 —— 可用的调用图，支持 Maven/Gradle 依赖解析（实验性）
• JavaScript 可达性 —— 可用的调用图，支持路由入口点检测（实验性）
• 扫描取消 —— POST /scan/{id}/cancel 停止进行中的扫描
• 稳定的扫描响应契约：GET /scan/{id} 上的 summary + 分类桶
• API 与包本地模式之间共享的扫描响应规范化（一致性）
• 默认安全的运行时边界：
  • 基础 compose 运行时无需挂载 Docker socket
  • 动态扫描需通过 VULNREACH_ALLOW_DOCKER_DAEMON=true 显式选择启用
  • 运行时配置文件使用受限的 docker-socket-proxy
• CI 中针对 Java/JavaScript/Go 的确定性夹具质量门禁
• 被接纳为官方 OWASP 项目 —— owasp.community/projects/vulnreach
• AI 后续步骤端点 —— POST /findings/{id}/next-steps 为确定性发现结果生成面向分析师的修复指导（即时操作、验证探针、升级路径、监控）。惰性/按需：扫描从不调用 LLM，LLM 失败时优雅降级。确定性判定为只读。见 docs/api.md。

实验性

• scan.runtime.ebpf 追踪模式（面向 Linux，需显式选择启用）
• AI 辅助的 OpenAPI 生成和智能 DAST 流程

参见：

• docs/incubator-readiness.md
• docs/threat-model.md

---

工作原理

每个 CVE 通过五层证据链进行分类：

1. SCA (Trivy)              → is the package installed and vulnerable?
2. Taint analysis (tainter) → does user input flow to the vulnerable sink?
3. AST analysis             → is the vulnerable function in your call graph?
4. Route exposure           → is the call path reachable from an HTTP endpoint?
5. Runtime coverage         → was the vulnerable code actually executed?

结果是一个带有四个层级的优先级发现列表：

层级	含义
DYNAMICALLY_REACHABLE	运行时覆盖确认执行 —— 立即修复
STATICALLY_REACHABLE	代码路径经 AST/污点分析证明 —— 高优先级
UNCERTAIN	仅有弱信号 —— 需调查
NOT_REACHABLE	无证据 —— 从告警队列中抑制

---

快速开始

使用 Docker Compose（推荐）

安全提示 —— 启动前，将 .env.example 复制为 .env.local，并将 每个 CHANGE_ME 值替换为强随机密钥。
在未设置真实凭据并配置 CORS_ORIGINS 的情况下，切勿将 VulnReach 暴露在公共网络上。

git clone https://github.com/ihrishikesh0896/vulnreach.git
cd vulnreach

# 1. Create your local config
cp .env.example .env.local

# 2. Fill in every CHANGE_ME — generate secrets with: openssl rand -hex 32
$EDITOR .env.local

# 3. Start the stack
docker compose up --build

# Optional: enable dynamic runtime scans (Docker daemon access via restricted socket proxy)
# docker compose -f docker-compose.yml -f docker-compose.runtime.yml up --build

运行扫描

认证选项：

• 短期 JWT：POST /login
• 长期 API 令牌（API 密钥）：在 UI 中 Settings -> API Keys 创建，然后作为 Authorization: Bearer <API_KEY> 使用

# Get a token (replace with the credentials you set in .env.local)
TOKEN=$(curl -s -X POST http://localhost:8000/login \
  -H "Content-Type: application/json" \
  -d '{"username":"<your-admin-user>","password":"<your-admin-password>"}' | jq -r .access_token)

# Start scan from a GitHub repo
curl -X POST http://localhost:8000/scan \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_url":"https://github.com/yourorg/yourapp"}'

# Poll for results
curl http://localhost:8000/scan/<scan_id> \
  -H "Authorization: Bearer $TOKEN" | jq .summary

---

功能特性

• 可达性过滤的 SCA —— 按证据强度对每个 CVE 分类，而不仅仅是 CVSS 评分
• 运行时确认 —— 通过 coverage.py 进行基于 Docker 的覆盖率收集
• 污点追踪 —— 追踪用户输入 → 易受攻击的汇聚点（SQL、subprocess、YAML、pickle）
• LLM 引导的 DAST —— Claude/OpenAI/Ollama 生成并验证漏洞利用载荷（可选）
• CI/CD 门禁 —— policy.block_if 在确认的关键发现上使构建失败；通过 curl 触发和门禁 —— 见 docs/ci-cd-gating.md
• JWT 认证 —— 多用户、基于角色的访问（admin / analyst）
• API 令牌（API 密钥） —— 用于 curl/CI 的长期机器认证（Authorization: Bearer <API_KEY>）
• PDF 导出 —— GET /scan/{id}/export/pdf
• 无供应商锁定 —— LLM 功能默认 provider: none；支持 Ollama 用于离线使用

---

实践案例

扫描目标：multi-tier-dvpa —— 一个故意存在漏洞的 Python/Django 应用程序，11 个包中共有 72 个原始 CVE。

层级	结果
原始 CVE（Trivy）	72
分类发现（VulnReach）	90
DYNAMICALLY_REACHABLE —— 立即修复	49
STATICALLY_REACHABLE —— 本冲刺修复	23
UNCERTAIN —— 需调查	18
NOT_REACHABLE —— 抑制	0
CI 流水线门禁	BLOCKED

46% 的发现从无差别的“全部修复”队列中移出，进入优先级行动列表。在典型的生产服务中（许多传递依赖从未被调用），这一数字上升到 70–90%。

完整方法论、证据链细节和包级细分：docs/benchmark.md

---

文档

使用

• USAGE_PACKAGE.md —— pip install / Docker 服务器安装和生命周期（start/stop/reload）；扫描通过 UI 或 curl 进行，而非 CLI
• USAGE_UI.md —— UI/服务器安装、依赖、启动、使用
• docs/ci-cd-gating.md —— 通过 curl 从 CI 流水线触发和门禁扫描

运维 / 部署

• docs/deployment.md —— Docker Compose 设置、环境变量、生产注意事项
• docs/configuration.md —— 完整的 scan.yml 配置参考
• docs/api.md —— REST 端点和模式

架构 / 安全

• docs/architecture.md —— 流水线设计和执行模型
• docs/threat-model.md —— 信任边界、STRIDE、滥用案例
• docs/incubator-readiness.md —— OSS/OWASP 就绪状态
• docs/DAST.md —— DAST 概念和流程

贡献者

• ROADMAP.md —— 计划功能、已知限制、语言支持状态
• docs/development.md —— 内部机制、代理、存储、扩展点
• OWASP.md —— OWASP 项目说明
• SECURITY.md —— 漏洞披露和密钥轮换
• CONTRIBUTING.md —— 贡献流程
• CHANGELOG.md —— 发布历史

---

环境要求