# SynapseQL

**Repository Path**: hacja/synapse-ql

## Basic Information

- **Project Name**: SynapseQL
- **Description**: 用于sarif解析的mcp工具
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-20
- **Last Updated**: 2026-05-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SynapseQL MCP：神经符号协同漏洞挖掘中枢

![Version](https://img.shields.io/badge/version-0.3.0--beta-blue)
![Python](https://img.shields.io/badge/Python-3.11+-green)
![Status](https://img.shields.io/badge/status-beta-green)

## 1. 定位：AI IDE 的"安全专家大脑插件"

SynapseQL 不是一个自动化的扫描器，也不是一个 PoC 生成器。它是一个**确定性的"安全专家插件"**，旨在让 AI IDE（Trae/Cursor/Windsurf）能够**将 CodeQL 的分析结果利用到极致**。

**核心逻辑**：IDE 提供执行环境（手脚）和逻辑推理（大脑），SynapseQL 提供**CodeQL 级别的硬核数据支撑（证据）**和**资产状态管理（记忆）**。

*   **极简主义**：你不再需要写文件树、搜索栏、终端模拟器。这些统统交给 IDE。
*   **极致分析**：专注于 SARIF 路径剪枝、符号对齐评分、权限与端点映射，为 AI 提供最精准的"弹药"。
*   **状态治理**：通过 MCP 实现漏洞状态的实时流转与持久化，让每一次审计都有迹可循。
*   **零幻觉**：通过极简接口，将 CodeQL 的 SARIF 结果转化为 AI 可直接引用的「代码定位链」「权限对齐状态」「端点置信度评分」，从根本上消除大模型在安全分析中的不确定性。
---

## 2. 项目结构

```
synapse-ql/
├── backend/
│   ├── synapseql/                 # 核心模块
│   │   ├── core/                  # 核心功能
│   │   │   ├── analysis/          # 分析模块（符号约束、端点检测、权限标记）
│   │   │   ├── db/                # 数据库模型与连接
│   │   │   ├── utils/             # 工具函数（路径、安全、IO调度）
│   │   │   ├── sarif_parser.py    # SARIF 解析器
│   │   │   └── severity.py        # 严重级别定义
│   │   ├── mcp/                   # MCP 协议实现
│   │   │   ├── tools/             # MCP 工具实现
│   │   │   ├── schemas.py         # 数据模型
│   │   │   └── server.py          # MCP 服务器入口
│   │   └── services/              # 服务层
│   │       ├── path_summary.py    # 路径摘要服务
│   │       └── vulnerability_service.py  # 漏洞管理服务
│   ├── tests/                     # 测试套件
│   │   ├── conftest.py            # 测试配置与 fixtures
│   │   ├── test_sarif_parser.py   # SARIF 解析测试
│   │   ├── test_symbols.py        # 符号约束测试
│   │   ├── test_endpoints.py      # 端点检测测试
│   │   ├── test_path_summary.py   # 路径摘要测试
│   │   └── test_mcp_tools.py      # MCP 工具测试
│   ├── pytest.ini                 # pytest 配置
│   └── requirements.txt           # Python 依赖
└── README.md
```

---

## 3. 系统架构 (MCP 模式)

通过 MCP 协议，SynapseQL 作为一个本地服务，直接向 AI IDE 暴露"专家工具"。

```mermaid
flowchart TD
    subgraph IDE_Host["AI IDE (Trae/Cursor/Windsurf)"]
        Chat[AI Agent 聊天/编排]
        MCP_Client[MCP Client]
    end

    subgraph SynapseQL_MCP["SynapseQL MCP Server (FastAPI)"]
        Tools[MCP Tools / Resources]
        Engine[SynapseQL Core Engine]
        DB[(SQLite - 漏洞与证据库)]
    end

    subgraph External["工具与环境"]
        CQL[CodeQL CLI]
    end

    MCP_Client <-- MCP Protocol --> Tools
    Tools --> Engine
    Engine --> CQL
    Engine --> DB
```

---

## 4. 核心功能设计 (AI-First 增强)

### 4.1 智能预筛与证据定位 (CSV Linkify & Payload)
*   **Linkify (一键定位)**：`filter_by_csv` 返回的结果中包含 `file:///` 格式的绝对路径链接（带行号），AI 可直接引用为"代码定位链接"，无需二次搜索。
*   **Payload Templates (攻击载荷)**：针对 Top 风险项（如 SSRF、路径遍历），自动生成复现载荷模板（非执行），辅助 AI 快速验证。
*   **Fingerprint Linkage**：自动将 CSV 行与 SARIF 中的指纹关联，确保后续深度分析的准确性。

### 4.2 深度路径分析 (Context Enrichment)
*   **Auth Alignment (权限对齐)**：`get_path_summary` 自动解析 `SecurityConfig` (Spring Security) 或注解 (`@PreAuthorize`)，判断端点是否允许**匿名访问**。
*   **Sink Risk Labeling (危险点标注)**：自动识别 SARIF 路径中的 Sink 点，并标注危险等级（如 `OkHttp` vs `File IO`）。
*   **Path Pruning (智能剪枝)**：基于数据流分析，生成剪枝后的关键路径摘要 (Source -> Steps -> Sink)，去除冗余节点。

### 4.3 符号约束与端点映射 (Symbol Constraints)
*   **Endpoint Resolution (端点解析)**：`solve_symbol_constraints` 支持通过 URL 端点（如 `GET /api/user`）反向查找对应的代码方法签名与位置。
*   **Endpoint Symbol Format (端点符号格式)**：支持 `GET /api/user`（精确方法+路径）、`POST /api/login`、`/api/health`（任意方法）三种格式。
*   **Tree-sitter AST (精准解析)**：优先使用 Tree-sitter 进行多语言（Java/Python/Go/JS/TS/C/C++/C#）的精准 AST 解析，提取作用域与参数签名。
*   **Alignment Score (置信度评分)**：基于符号存在性、签名匹配度、作用域一致性给出 0-5 的置信度评分，拒绝幻觉。
*   **Multi-Framework Support (多框架支持)**：内置支持 Spring MVC、JAX-RS、NestJS、Express、Koa、Gin、Echo、FastAPI、Flask、Django、ASP.NET 等 15+ 框架的端点解析。

---

## 5. 关键接口定义 (MCP Tools)

### 5.1 filter_by_csv - CSV 快速预筛

**[首选入口]** 解析 CodeQL 导出的 CSV 文件，进行轻量预筛。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `csv_path` | string | ✅ | CSV 文件绝对路径 |
| `sarif_path` | string | ❌ | SARIF 文件路径（用于指纹联动） |
| `source_root` | string | ❌ | 源码根目录（用于 linkify） |
| `include_rules` | list | ❌ | 规则白名单 |
| `exclude_rules` | list | ❌ | 规则黑名单 |
| `min_severity` | string | ❌ | 最低严重级别（ERROR/WARNING/NOTE） |
| `limit_rows` | int | ❌ | 返回行数上限 |
| `linkify` | bool | ❌ | 生成 `file:///` 可点击链接（默认 false） |

**返回示例：**
```json
{
  "summary": {
    "rows": 10,
    "by_rule": {"java/path-injection": 5, "java/sql-injection": 5},
    "by_severity": {"ERROR": 8, "WARNING": 2}
  },
  "rows": [
    {
      "file": "src/main/java/Controller.java",
      "line": 42,
      "rule_id": "java/path-injection",
      "severity": "ERROR",
      "message": "Uncontrolled data used in path expression",
      "link": "file:///path/to/Controller.java#L42",
      "fingerprint": "abc123..."
    }
  ]
}
```

---

### 5.2 get_path_summary - 深度路径分析

**[深度分析]** 获取剪枝后的路径摘要，包含权限对齐、危险点标注、风险评估。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `result_id` | int | ✅ | 结果 ID（用于缓存关联） |
| `sarif_path` | string | ✅ | SARIF 文件绝对路径 |
| `task_id` | int | ❌ | 任务 ID（用于数据库回填） |
| `source_root` | string | ❌ | 源码根目录 |

**返回示例：**
```json
{
  "result_id": 123,
  "summary": {
    "paths": [{
      "rule_id": "java/path-injection",
      "severity": "ERROR",
      "cwe_ids": ["CWE-22"],
      "fingerprint": "abc123...",
      "source": {"file": "Controller.java", "line": 10, "role": "SOURCE"},
      "sink": {"file": "FileUtils.java", "line": 50, "role": "SINK"},
      "steps": [...],
      "sink_risk": {"type": "FILE_WRITE", "confidence": 0.95}
    }],
    "alignment": {"score_avg": 4.5, "files_resolved": 3},
    "auth_status": "anonymous",
    "evidence": {
      "auth_hits": [...],
      "sink_hits": [...],
      "assessment": {"level": "high", "reasons": ["匿名访问", "文件写入"]}
    }
  }
}
```

---

### 5.3 solve_symbol_constraints - 符号约束验证

**[符号验证]** 验证符号/端点真实性，返回 AST 级对齐评分。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `source_paths` | list | ✅ | 源路径列表（支持 glob 通配符） |
| `symbols` | list | ✅ | 符号列表（支持端点格式） |

**端点符号格式：**
- `GET /api/user` - 精确匹配方法和路径
- `POST /api/login` - 精确匹配 POST 方法
- `/api/health` - 匹配任意 HTTP 方法

**返回示例：**
```json
{
  "summary": {
    "symbols_checked": 2,
    "files_scanned": 5,
    "missing_symbols": []
  },
  "files": [{
    "path": "/path/to/UserController.java",
    "language": "java",
    "symbols": {
      "GET /api/user": {
        "exists": true,
        "categories": ["endpoint"],
        "assessment": "must",
        "alignment_score": 5,
        "endpoint_info": {"method": "GET", "path": "/api/user", "framework": "spring-mvc"}
      },
      "UserController": {
        "exists": true,
        "categories": ["definition"],
        "alignment_score": 4,
        "def_spans": [{"start": 10, "end": 50}]
      }
    }
  }]
}
```

---

### 5.4 mark_vulnerability - 漏洞状态治理

**[状态治理]** 标记漏洞状态并记录审计证据。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | int | ✅ | 漏洞 ID |
| `status` | string | ✅ | 状态：OPEN/CONFIRMED/FALSE_POSITIVE/RESOLVED |
| `reason` | string | ❌ | 变更理由 |

**返回示例：**
```json
{
  "id": 1,
  "status": "CONFIRMED",
  "previous_status": "OPEN",
  "evidence_id": 42,
  "success": true
}
```

---

### 5.5 refresh_path_summary_cache - 缓存管理

**[缓存管理]** 管理路径摘要缓存，支持清理过期缓存或重新计算。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `result_id` | int | ❌ | 结果 ID |
| `task_id` | int | ❌ | 任务 ID |
| `project_id` | int | ❌ | 项目 ID |
| `mode` | string | ❌ | 模式：clear（默认）/ recompute |
| `force` | bool | ❌ | 强制刷新（默认 false） |
| `limit` | int | ❌ | 处理数量上限 |

---

## 6. 开发价值总结

1.  **AI 友好型接口**：所有工具的输出都经过精心设计（Linkify、Payloads、Auth Status），最符合 AI 的"起手式"需求。
2.  **确定性证据**：通过 CodeQL + AST 双重校验，消除 AI 的幻觉，提供 100% 可信的代码证据。
3.  **资产全生命周期**：从发现 (CSV) -> 分析 (SARIF) -> 验证 (AST) -> 治理 (DB)，全流程状态化管理。

---

## 7. 使用指南（MCP）

### 7.1 环境准备

#### 7.1.1 安装依赖
```bash
cd backend
pip install -r requirements.txt
```

#### 7.1.2 配置 MCP Server

**Windows 示例：**
```json
{
  "Synapseql": {
    "command": "D:\\Projects\\synapse-ql\\backend\\.venv\\Scripts\\python.exe",
    "args": ["-m", "synapseql.mcp.server"],
    "env": {
      "PYTHONPATH": "D:\\Projects\\synapse-ql\\backend",
      "DATABASE_URL": "sqlite:///D:/Projects/synapse-ql/backend/data/synapseql.db"
    }
  }
}
```

**Linux/macOS 示例：**
```json
{
  "Synapseql": {
    "command": "/home/user/synapse-ql/backend/.venv/bin/python",
    "args": ["-m", "synapseql.mcp.server"],
    "env": {
      "PYTHONPATH": "/home/user/synapse-ql/backend",
      "DATABASE_URL": "sqlite:////home/user/synapse-ql/backend/data/synapseql.db"
    }
  }
}
```

---

### 7.2 完整工作流程

#### 步骤 1：准备 CodeQL 环境

```bash
# 安装 CodeQL CLI
# 访问：https://github.com/github/codeql-cli-binaries/releases

# 下载查询包
codeql pack download codeql/java-queries
codeql pack download codeql/python-queries
```

#### 步骤 2：创建数据库并运行查询

```bash
# 创建数据库
codeql database create ./codeql-db \
  --source-root=/path/to/project \
  --language=java \
  --command="mvn clean compile"

# 运行查询
codeql database analyze ./codeql-db \
  codeql/java-queries:Security/*.ql \
  --format=sarifv2 \
  --output ./out/results.sarif \
  --csv ./out/results.csv
```

#### 步骤 3：使用 SynapseQL MCP 工具分析

**快速预筛：**
```python
result = await mcp_client.call_tool("filter_by_csv", {
    "csv_path": "/path/to/results.csv",
    "sarif_path": "/path/to/results.sarif",
    "linkify": True,
    "min_severity": "ERROR"
})
```

**深度分析：**
```python
result = await mcp_client.call_tool("get_path_summary", {
    "sarif_path": "/path/to/results.sarif",
    "result_id": 123,
    "source_root": "/path/to/project"
})
```

**符号验证：**
```python
result = await mcp_client.call_tool("solve_symbol_constraints", {
    "source_paths": ["/path/to/project/**/*.java"],
    "symbols": ["GET /api/user", "UserController"]
})
```

---

## 8. 测试

项目包含完整的单元测试套件：

```bash
cd backend
python -m pytest tests/ -v --tb=short
```

测试覆盖：
- SARIF 解析器
- 符号约束求解
- 端点检测
- 路径摘要服务
- MCP 工具

---

## 9. 性能开关（环境变量）

- `SYN_PATH_SUMMARY_SLICE_LIMIT`：路径条目上限（默认 5）
- `SYN_PATH_SUMMARY_STEP_LIMIT`：单路径步骤上限（默认 8）
- `SYN_PATH_MAX_CANDIDATES`：候选文件数量上限（默认 64）

---

## 10. 支持的端点框架

`solve_symbol_constraints` 内置支持以下框架的端点解析：

### 10.1 Java 框架
| 框架 | 端点语法示例 | 匹配规则 |
|------|-------------|----------|
| **Spring MVC** | `@GetMapping("/api/user")` | 支持 `@GetMapping`/`@PostMapping`/`@PutMapping`/`@DeleteMapping`/`@PatchMapping`/`@RequestMapping` |
| **JAX-RS** | `@GET @Path("/api/user")` | 支持 `@GET`/`@POST`/`@PUT`/`@DELETE`/`@PATCH` + `@Path` 组合 |

### 10.2 JavaScript/TypeScript 框架
| 框架 | 端点语法示例 | 匹配规则 |
|------|-------------|----------|
| **NestJS** | `@Get('user')` / `@Post({ path: '/login' })` | 支持装饰器语法 |
| **Express** | `app.get('/api/user', ...)` | 支持 `app`/`router` 实例方法 |
| **Koa** | `router.get('/api/user', ...)` | 支持 `router` 实例方法 |

### 10.3 Python 框架
| 框架 | 端点语法示例 | 匹配规则 |
|------|-------------|----------|
| **FastAPI** | `@app.get("/api/user")` | 支持 `@app`/`@router` 装饰器 |
| **Flask** | `@app.route('/api/user', methods=['GET'])` | 支持 `methods` 参数 |
| **Django** | `path('api/user', ...)` | 支持 `path`/`re_path` 函数 |

### 10.4 Go 框架
| 框架 | 端点语法示例 | 匹配规则 |
|------|-------------|----------|
| **Gin** | `r.GET("/api/user", ...)` | 支持 `r`/`router` 实例方法 |
| **Echo** | `e.GET("/api/user", ...)` | 支持 `e`/`echo` 实例方法 |

### 10.5 C# 框架
| 框架 | 端点语法示例 | 匹配规则 |
|------|-------------|----------|
| **ASP.NET** | `[HttpGet("api/user")]` | 支持 `[HttpGet]`/`[HttpPost]` 等特性 |

---

## 11. 设计准则（零幻觉/零误导）

- **严格确定性**：仅以 CodeQL/SARIF 与 AST 确证为依据。
- **Fail-closed**：解析失败或证据不足时返回 unknown，宁缺勿滥。
- **禁止启发式与概率性**：不做端点/权限的正则回退与概率排行。
- **输出纪律**：只在证据充分时给出 must，否则为 not_found 或 unknown。

---

## 12. 许可证

MIT License