🛡️ Fuzzy-Semantic-Audit-MCP

基于 Model Context Protocol (MCP) 与 CodeGraph 索引构建的高精度逻辑漏洞模糊语义审计工具。通过 CWE 漏洞目录引导、AI 自动检索词转换、CodeGraph 调用图提取、大模型静态污点分析与静态验证（Taint Analysis）和误报哈希（SimHash）缓存，为多语言代码库提供全自动逻辑 0-day 漏洞的发现与验证。

🌟 核心特性

• 多语言适配与预检裁剪：支持 C/C++、Python、Go、Java、JS/TS 项目的智能语种检测，结合代码预扫描技术对非激活技术栈对应的 CWE 进行剪枝，大幅降低审计噪声。

• AI 驱动的意图检索词翻译：自动将复杂的 CWE 定义与缓解措施转换为具体的代码级语义检索 Intents 以及大模型定制审计 Prompt。

• CodeGraph 精准符号提取：利用 CodeGraph 引擎对目标关键字执行模糊查询，通过 ContextSlicer 自动补充关联类型定义，且回溯入口调用链，完成攻击面确认。

• 误报 SimHash 距离缓存：基于代码标准化、SimHash 64位指纹与汉明距离（Hamming Distance <= 3）算法自动缓存被判定为 False Positive（误报）的函数。当代码修改引发重新校验时，自动拦截误报。

• 静态污点与可达性校验：采用静态污点分析（Taint Analysis）与调用链分析对候选点（Candidate）的调用链可达性（Path Reachability）、数据清洗状态（Sanitization Check）与漏洞触发机制（Trigger Mechanism）进行 LLM 逻辑证明，不依赖实机沙箱环境，保障极低的误报率。

• 崩溃自愈与断点续扫：支持通过 resume_audit 自动查询当前扫描进度，并从首个未完成的 pending 任务处热恢复执行。

• 自动编译安全性报告：全量漏洞按 CVSS 分值降序排列，自动过滤低于 CVSS 5.0 分的低危风险，提供交互式 Markdown 报告（含漏洞源码、类型依赖、以及包含调用链、污点流和触发原理三大结构化分析的 Triage 推导过程）。

Related MCP server: frogeye-mcp

🛠️ 安装与部署

一键初始化环境（自动创建虚拟环境、安装依赖、并在 Antigravity 中自动注册 MCP 服务）：

# 1. 进入项目根目录
cd ~/fuzzy-semantic-audit-mcp

# 2. 运行一键初始化脚本
./fuzzy-audit init

集成至 Antigravity CLI (agy)

初始化完成后，MCP 自动化注册完成。您可以通过 agy 交互式命令进行验证和调用：

• 查看已加载的技能：/skills

• 查看暴露的 Tools：/mcp

🤖 配置 AI 模型 API Key（必须）

⚠️ 未配置 API Key 时，工具会静默降级为 Mock 模式，仅凭函数名关键词匹配判定漏洞，不执行真实的代码分析。

本工具依赖大模型进行静态污点追踪与漏洞验证，需至少配置以下任一提供商的 API Key：

# 推荐：DeepSeek（与 CodeWhale 共用 Key）
export DEEPSEEK_API_KEY="sk-your-deepseek-key"
# 可选：自定义 Base URL
export DEEPSEEK_BASE_URL="https://api.deepseek.com"

# 备选：Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-your-key"

# 备选：Google Gemini
export GEMINI_API_KEY="your-gemini-key"

支持三种提供商，按优先级自动选择：DeepSeek → Anthropic → Gemini。配置后重新运行审计即可启用真实 AI 分析。

🚀 审计流水线说明

graph TD
    A[initialize_audit] -->|语种与技术栈预检| B[generate_queries]
    B -->|CWE转语义检索词| C[explore_code]
    C -->|CodeGraph探索与切片| D[verify_batch]
    D -->|SimHash缓存过滤 + 静态污点校验| E[generate_report]

步骤 1：初始化审计计划 (initialize_audit)

预扫描项目代码资产，检测出目标技术栈对应的 CWE 审计任务集并初始化 SQLite 计划数据库。

agy mcp call fuzzy-semantic-audit initialize_audit --project_path "/path/to/project" [--lang "python"]

步骤 2：生成语义检索词 (generate_queries)

调用 LLM 将 CWE 的描述转化为可在 CodeGraph 索引中检索的 3~5 个意图关键字。

agy mcp call fuzzy-semantic-audit generate_queries --plan_id "plan-xxx"

步骤 3：符号定位与代码切片 (explore_code)

模糊查询 CodeGraph 定位关联的源码候选函数，并利用 slice 提取类型上下文以及过滤 Mock/测试文件。

agy mcp call fuzzy-semantic-audit explore_code --plan_id "plan-xxx"

步骤 4：高并发静态污点流向校验 (verify_batch)

对定位出的候选漏洞点执行高并发校验。不依赖沙箱，使用纯静态污点链模型，分析数据流向和输入清洗状态。当不提供具体的候选点 ID 时，默认对数据库中全部 pending 的候选项执行全量校验：

agy mcp call fuzzy-semantic-audit verify_batch --plan_id "plan-xxx" [--max_concurrent 4]

步骤 5：导出安全性报告 (generate_report)

将验证确认的逻辑漏洞以 CVSS 评分从高到低排序，导出规范的审计报告文件。报告将自动过滤 CVSS 分数低于 5.0 的低风险候选项。

agy mcp call fuzzy-semantic-audit generate_report --plan_id "plan-xxx" --output_path "/path/to/project/report.md"

🔗 CI/CD 集成

我们提供了全自动无头（Headless）扫描脚本，可轻松集成至 GitHub Actions 或 GitLab CI/CD 中，支持对合并请求（PR）的增量变更扫描和安全质量门禁拦截。

关于具体的配置与使用方法，请参见：

• CI/CD 集成指南

🧪 单元测试

项目集成了全方位的测试用例覆盖，在提交修改前请务必运行测试以确保执行链的可靠：

# 运行单元测试与端到端集成用例
.venv/bin/python3 -m unittest discover tests/