---

本项目基于 OWASP Noir 扩展，新增 漏洞假设制导的端点合成（VHES, Vulnerability-Hypothesis-Guided Endpoint Synthesis） 能力。

Noir 原本擅长从源码恢复路由模板（如 GET /userdata/{file}）。但安全审计的真实起点往往是一条自然语言的漏洞假设——「某数据/配置目录未受 Web API 访问控制充分保护」——审计者需要的是能直接发送的具体请求，如 GET /userdata/ComfyUI-Manager%2Fconfig.ini。

从模板到具体可利用请求之间存在一道语义鸿沟：它要求联接三类分散且异构的信息——路由模板的解码语义、服务目录下真实存在的文件、审计者的自然语言意图。VHES 用确定性静态分析提供可信接地事实，用 LLM 承担跨源语义联接与具体化，再用确定性校验与合并把 LLM 输出约束回严格 schema。

核心能力

• 自然语言驱动。以一条漏洞假设为意图输入，合成出磁盘上真实存在、编码正确的可发送请求。
• neuro-symbolic 职责划分。静态分析接地（路由模板、路由源码、真实数据文件），LLM 语义联接，符号校验约束输出、拒绝幻觉与越界。
• %2F 保真。合成阶段置于优化器之后，避免具体路径段被归一化回 {param}，保证路径穿越可利用性。
• per-user 服务根感知。自动处理 user/<user-id>/ 这类 per-user/tenant 服务根，避免产出多一层前缀的不可达路径。
• 大仓可用。--ai-vuln-only 让昂贵的 LLM 调用只发生在合成这一步，跳过全仓 LLM 分析——3.3 万文件仓库约 45 秒完成。
• 多 provider 动态可配。OpenAI 兼容（含新增的 DeepSeek）、Ollama/LM Studio、ACP（claude/codex/gemini）；model/key 全部动态配置，源码不写死。

新增用法

在原有 Noir 用法之上，新增以下标志：

示例

# 把漏洞假设写入文件，避免中文长文本在命令行被 shell 误解析
echo "ComfyUI-Manager 的数据与配置目录在旧版本中未受 ComfyUI 的 Web API 访问控制充分保护。" > /tmp/vd.txt

# 完整目录扫描 + 漏洞制导合成
./bin/noir -b <source_dir> \
  --vuln-desc-file /tmp/vd.txt \
  --ai-provider deepseek --ai-model deepseek-v4-pro --ai-key <YOUR_KEY> \
  --ai-vuln-only

# 期望输出中包含： GET /userdata/ComfyUI-Manager%2Fconfig.ini

--ai-key 也可通过配置文件或 NOIR_AI_KEY 环境变量提供，无需写在命令行。

工作原理

源码 ──▶ [确定性分析器] ──▶ 端点(模板级) ──▶ [优化器] ──┐
                                                        │
自然语言假设 h ─────────────────────────────────────────┤
                                                        ▼
                        ┌──────────── VulnGuided 合成器 ───────────┐
                        │  ① 上下文收集：模板 T · 路由源码 S · 数据文件 F │
                        │  ② Prompt 构造（接地 + 编码规则 + schema）      │
                        │  ③ LLM 单次调用 → JSON                        │
                        │  ④ 校验 & 合并（约束回收，%2F 保真）           │
                        └───────────────────────────────────────────────┘
                                                        ▼
                                            端点(模板级 + 具体级)

LLM 只在「最需要世界知识与语义推理」的一步介入：输入被静态事实接地，输出被符号规则约束。这既规避了纯静态的表达力不足，也抑制了纯 LLM 的幻觉与不可控。

核心实现见 src/analyzer/analyzers/llm_analyzers/vuln_guided.cr。

构建

依赖 Crystal 与 shards（同 OWASP Noir）：

shards install
shards build
# 产物在 ./bin/noir

ACP（--ai-provider acp:claude 等）依赖的 Node 包需 Node.js ≥ 20；旧版本会静默失败。

关于 Noir

VHES 构建在 OWASP Noir 之上——一款读取源码、枚举应用暴露端点（路径、方法、参数、头、cookie 及其源文件）的 SAST 工具，覆盖 50+ 框架，可输出 JSON / YAML / OpenAPI / SARIF / cURL / Postman 等格式并对接 ZAP / Burp / Caido 等 DAST 工具。

• 上游项目：https://github.com/owasp-noir/noir
• 文档：https://owasp-noir.github.io/noir/
• OWASP 项目页：https://owasp.org/www-project-noir/

原始 README 保留于上游仓库。本 fork 的所有新增能力遵循上游许可协议。

致谢与许可

• 基础工具 OWASP Noir 及其贡献者。
• 本 fork 沿用上游许可（见 LICENSE）。

授权与伦理

VHES 合成的穿越端点仅用于授权的安全审计与防御性测试，应仅对自有或已获授权的系统使用。