gisstw/refine-mcp
GitHub: gisstw/refine-mcp
基于tree-sitter事实提取与LLM红蓝队对抗分析的代码漏洞发现工具，通过MCP协议编排多Agent协作完成从结构化代码分析到漏洞验证的闭环。
Stars: 0 | Forks: 0
English | [繁體中文](README_zh-TW.md)
# refine-mcp
**别再让 AI 瞎猜 Bug 了 —— 让它基于结构化事实进行推理。**
Tree-sitter 从你的代码中提取事实（事务、锁、变更操作、catch 块）。LLM 红队（Red Team）基于这些事实进行推理，以发现真实的漏洞。蓝队（Blue Team）进行交叉分析并过滤误报。所有这些都通过 [Model Context Protocol](https://modelcontextprotocol.io/) 进行编排。
## 工作原理
```
Source Code LLM Red Teams (2-4)
│ │
▼ ▼
┌─────────────┐ fact tables ┌───────────────┐ raw findings
│ tree-sitter │──────────────▶│ RT-A RT-B │─────────────┐
│ extractor │ │ RT-C RT-D │ │
└─────────────┘ └───────────────┘ │
▼
Plan File ─────────────────────────────────────▶ ┌─────────────────┐
│ Synthesize │
│ dedup + validate │
│ + rank + score │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Blue Team │
│ cross-analysis + │
│ false positive │
└────────┬────────┘
│
▼
Final Report
```
**核心洞察**：LLM 擅长对代码进行*推理*，但*阅读*代码的成本很高。Tree-sitter 负责读取代码（免费、100% 准确），然后 LLM 仅需针对结构化事实进行推理（输入少、输出聚焦）。这使红队的 Token 消耗减少了约 66%，蓝队减少了约 80%。
## 为什么选择这种方法？
大多数 AI 代码审查工具（CodeRabbit、Sourcery 等）将代码视为散文 —— 将原始 diff 喂给 LLM 并指望它发现问题。这会导致幻觉、遗漏并发 Bug 以及浪费 Token。
**refine-mcp 走了一条不同的路：**
| 方面 | 传统 AI 审查 | refine-mcp |
|--------|----------------------|------------|
| LLM 输入 | 原始代码 / diff（数千行） | 结构化事实表（事务、锁、变更操作、catch 块） |
| 分析依据 | “阅读并猜测” | 基于 AST 提取的事实 |
| 并发 Bug | 经常遗漏（需要多步推理） | 拥有锁/事务事实的专用 RT-B 团队 |
| 误报 | 高（无过滤） | 蓝队交叉分析 + 持久化状态跟踪 |
| Token 成本 | 约 100% 的代码作为输入 | 约 34%（红队）/ 约 20%（蓝队） |
| 多轮跟踪 | 无 | `.state.json` —— 已修复/误报的发现不会重复出现 |
### 智能红队调度
红队不会盲目地投入到代码中。每个团队都有一个针对特定漏洞类的**专用 Prompt 模板**，并且团队会**基于事实信号动态激活**：
```
Facts extracted by tree-sitter
│
├─ Mutations without transaction? ──────► Activate RT-C (data integrity)
├─ External calls inside transaction? ──► Activate RT-C
├─ Auth/permission in file paths? ──────► Activate RT-D (auth boundary)
└─ Always ──────────────────────────────► RT-A (single-op) + RT-B (multi-op)
```
这意味着调度决策本身零 LLM 成本 —— tree-sitter 事实驱动路由。
当省略 `red_count` 时，`prepare_attack` 会返回一个 `dispatch` 字段，解释**为什么**每个团队被激活或跳过：
```
{
"dispatch": {
"activated": ["RtA", "RtB", "RtC"],
"reasoning": [
"RT-A (single-op): always active",
"RT-B (multi-op): always active",
"RT-C (data integrity): 3 mutations without transaction in PaymentService.php::transferFunds",
"RT-D (auth boundary): skipped (no signals)"
]
}
}
```
### 两个正交维度
1. **红队角色** = *攻击什么*（Prompt 模板专业化）
2. **模式** = *模型有多智能*（opus/sonnet/haiku）
这两者是独立的。你可以使用 haiku 运行 RT-A 到 RT-D 进行快速筛选，或者使用 opus 进行深度分析。
## 支持的语言
| 语言 | 提取器 | 语法 |
|----------|-----------|---------|
| PHP | `extract_php_facts` | tree-sitter-php 0.24 |
| Rust | `extract_rust_facts` | tree-sitter-rust 0.23 |
| TypeScript/JavaScript | `extract_ts_facts` | tree-sitter-typescript 0.23 |
| Python | `extract_python_facts` | tree-sitter-python 0.23 |
每个提取器生成一个包含逐函数分析的 `FactTable`：
- **Transactions（事务）** —— 数据库事务边界和 lock-for-update 用法
- **Locks（锁）** —— 并发锁（DB 锁、缓存锁、共享锁）
- **Catch blocks（Catch 块）** —— 异常处理及动作分类（重抛、日志、静默吞掉）
- **External calls（外部调用）** —— API/网络调用，尤其是事务内部的调用
- **State mutations（状态变更）** —— 带目标的 Create/Update/Delete 操作
- **Null risks（空值风险）** —— 潜在的空指针解引用 / unwrap / panic 点
- **Parameters（参数）** —— 带类型提示和可空性的函数参数
## 安装
### 从源码安装
```
git clone https://github.com/gisstw/refine-mcp.git
cd refine-mcp
cargo build --release
# 目标/release/refine-mcp 下的 Binary
```
### 使用 cargo 安装
```
cargo install refine-mcp
```
## 快速开始
### Claude Code MCP 配置
添加到你的 Claude Code MCP 设置中：
```
{
"mcpServers": {
"refine": {
"command": "/path/to/refine-mcp"
}
}
}
```
### 基本工作流
典型的优化流程包含 5 个步骤（或使用组合工具为 4 步）：
```
1. discover_plan → Find plan file, extract file references
2. extract_facts → Run tree-sitter on referenced files
3. prepare_attack → Generate red team prompts from facts
(run 2-4 LLM agents with the generated prompts)
4. synthesize_findings → Parse red team output, dedup, rank, generate blue prompt
(run 1 LLM agent with the blue prompt)
5. finalize_refinement → Append findings to plan file
```
或者使用 `discover_and_extract` 将步骤 1+2 合并为单次调用。
## MCP 工具
### discover_plan
查找最近修改的计划文件并提取源文件引用。
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `plan_dir` | string | No | 要搜索的目录（默认：`.claude/plans/`） |
### extract_facts
在源文件上运行 tree-sitter 分析。
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `file_paths` | string[] | Yes | 源文件的绝对路径 |
| `diff_only` | bool | No | 如果为 true，仅分析 git 变更的文件 |
### discover_and_extract
在单次调用中合并发现 + 提取。
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `plan_dir` | string | No | 要搜索的目录 |
| `diff_only` | bool | No | 仅分析 git 变更的文件 |
### prepare_attack
根据计划内容和事实表生成红队 Prompt。
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `plan_path` | string | Yes | 计划文件的路径 |
| `facts_json` | string | Yes | 来自 extract_facts 的 JSON 编码事实表 |
| `mode` | string | No | `default` (opus), `lite` (sonnet), 或 `auto` (haiku) |
| `red_count` | u8 | No | 红队数量 (2-4)。如果省略，则根据事实自动选择 |
### synthesize_findings
解析红队 Markdown 输出，进行去重、验证、排名并生成蓝队 Prompt。
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `raw_reports` | string[] | Yes | 来自每个红队 Agent 的原始 Markdown 输出 |
| `plan_path` | string | No | 计划文件路径（用于持久化状态） |
| `plan_summary` | string | No | 简短的计划摘要，用于蓝队上下文 |
| `mode` | string | No | 蓝队模型推荐的成本模式 |
### finalize_refinement
备份计划文件并追加带有发现的优化部分。
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `plan_path` | string | Yes | 要追加的计划文件 |
| `blue_result` | string | No | 蓝队分析输出 |
| `findings_json` | string | Yes | 来自 synthesize 的 JSON 编码发现 |
| `mode` | string | No | 成本模式 |
### expand_blast_radius
搜索被修改函数的调用者以评估变更影响。
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `symbols` | string[] | No | 要搜索的函数名。如果省略，则从 git diff 自动检测 |
| `search_paths` | string[] | No | 要搜索的目录（默认：`["app/", "routes/"]`） |
| `exclude_files` | string[] | No | 要从结果中排除的文件 |
| `plan_files` | string[] | No | 用于自动检测变更符号的计划文件 |
| `max_per_symbol` | number | No | 每个 symbol 的最大 grep 结果数（默认：20） |
### extract_migration_facts
从迁移文件中提取数据库架构以提供红队上下文。
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `migration_dir` | string | No | 迁移路径（默认：`database/migrations`） |
| `table_filter` | string[] | No | 仅包含匹配的表名 |
## 红队角色
| ID | 名称 | 聚焦点 | 自动选择时机 |
|----|------|-------|--------------------|
| RT-A | Single-Op | 静默失败、类型安全、幂等性 | 总是 |
| RT-B | Multi-Op | 并发竞争、TOCTOU、行为变更 | 总是 |
| RT-C | Data Integrity | Schema 漂移、约束违规、部分写入 | 无事务的变更操作、TX 中的外部调用、静默吞掉异常 |
| RT-D | Auth Boundary | 权限检查、IDOR、权限提升 | 文件路径包含 auth/permission/middleware/login/session/guard/policy/role/access/token |
当从 `prepare_attack` 中省略 `red_count` 时，该工具会根据提取事实中的信号自动选择运行哪些红队。RT-A 和 RT-B 始终运行；仅当事实表明它们能发现真实问题时，才会添加 RT-C 和 RT-D。
## 模式
| 模式 | 红队模型 | 蓝队模型 | 用例 |
|------|---------------|-----------------|----------|
| `default` | opus | opus | 最高准确率 |
| `lite` | sonnet | sonnet | 成本与质量的良好平衡 |
| `auto` | haiku | haiku | 快速筛选，成本最低 |
## 去重与评分
发现通过以下方式去重：
- **相同文件 + 重叠的行范围** → 合并
- **相同文件 + 相似的标题**（≥85% Levenshtein 相似度） → 合并
影响分数 = `severity_weight × domain_weight / 10 + source_bonus`
- 严重性：Fatal=100, High=60
- 领域权重：Payment/Billing (30) > Services (20) > Controllers (15) > Models (12) > Default (10) > Views (5) > Config/Test (3)
- 来源加成：如果被多个红队确认，则 +20
## 许可证
根据以下任一许可证授权
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT License ([LICENSE-MIT](LICENSE-MIT))
由你选择。
标签：ASN解析, CISA项目, DevSecOps, DLL 劫持, IPv6支持, LLM, MCP, MS17-010, SQL查询, TLS抓取, Tree-sitter, Unmanaged PE, 上游代理, 事实提取, 代码推理, 可视化界面, 大语言模型, 对抗规划, 模型上下文协议, 自动化渗透测试, 误报过滤, 软件安全, 通知系统, 错误基检测, 防御框架, 静态代码分析