使用说明

Joern MCP Server

Joern MCP Server 是一个将 Joern 代码分析平台与 Model Context Protocol (MCP) 集成的服务器，让大语言模型（LLM）能够直接执行代码安全分析任务。

✨ 核心功能

功能类别	描述	MCP工具
🔍 项目管理	解析代码、生成CPG、管理项目	`parse_project`, `list_projects`, `switch_project`, `delete_project`
📞 调用图分析	函数调用关系追踪、调用链分析	`get_callers`, `get_callees`, `get_call_chain`, `get_call_graph`
🌊 数据流分析	变量流向追踪、数据依赖分析	`track_dataflow`, `analyze_variable_flow`, `find_data_dependencies`
🛡️ 漏洞检测	内置6种漏洞规则、自定义污点分析	`find_vulnerabilities`, `check_taint_flow`, `list_vulnerability_rules`
⚙️ 控制流分析	CFG生成、控制结构分析	`get_control_flow_graph`, `get_dominators`, `analyze_control_structures`
📊 代码查询	函数查询、代码搜索	`list_functions`, `get_function_code`, `search_code`

🚀 快速开始

1. 安装

# 克隆项目
git clone https://github.com/yourusername/joern_mcp.git
cd joern_mcp

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# 安装依赖
pip install -e ".[dev]"

2. 安装Joern

# macOS (Homebrew)
brew install joern

# Linux/Windows
curl -L "https://github.com/joernio/joern/releases/latest/download/joern-install.sh" | bash

3. 验证安装

# 检查Joern
joern --version

# 运行单元测试
pytest tests/test_services -v

4. 启动服务器

# 启动MCP服务器
python -m joern_mcp

📖 使用示例

示例1：检测C代码漏洞

# 1. 解析项目
await parse_project("/path/to/c_project", "my-c-app")

# 2. 查找所有漏洞
result = await find_vulnerabilities(project_name="my-c-app", severity="CRITICAL")
print(f"发现 {result['total_count']} 个严重漏洞")

# 3. 追踪特定漏洞流
flows = await check_taint_flow(
    project_name="my-c-app",
    source_pattern="gets",
    sink_pattern="system"
)
for flow in flows['flows']:
    print(f"污点从 {flow['source']} 流向 {flow['sink']}")

示例2：分析函数调用关系

# 获取函数的调用者
callers = await get_callers(
    project_name="my-c-app",
    function_name="vulnerable_function",
    depth=3
)
for caller in callers['callers']:
    print(f"{caller['name']} 在 {caller['filename']} 调用了目标函数")

# 生成完整调用图
graph = await get_call_graph(
    project_name="my-c-app",
    function_name="main",
    depth=2
)
print(f"调用图包含 {graph['node_count']} 个节点, {graph['edge_count']} 条边")

示例3：追踪数据流

# 追踪用户输入到危险函数的流向
flows = await track_dataflow(
    project_name="my-c-app",
    source_method="scanf",
    sink_method="strcpy"
)

# 分析特定变量
var_flow = await analyze_variable_flow(
    project_name="my-c-app",
    variable_name="user_input",
    sink_method="system"
)

🔧 配置

创建 .env 文件配置服务器（参考 env.example）：

# Joern Server配置
JOERN_SERVER_HOST=localhost
JOERN_SERVER_PORT=8080

# 安全设置
ENABLE_CUSTOM_QUERIES=true
MAX_QUERY_TIMEOUT=300

# 日志级别
LOG_LEVEL=INFO

📚 文档

文档	描述
安装指南	详细安装步骤和系统要求
用户手册	完整使用教程和最佳实践
API参考	MCP工具完整API文档
服务API	底层服务层API文档
MCP使用指南	MCP协议集成指南
示例项目	真实漏洞检测示例

🛡️ 内置漏洞规则

规则名称	严重级别	CWE编号	描述
Command Injection	CRITICAL	CWE-78	命令注入漏洞检测
SQL Injection	CRITICAL	CWE-89	SQL注入漏洞检测
Buffer Overflow	CRITICAL	CWE-120	缓冲区溢出检测
Path Traversal	HIGH	CWE-22	路径遍历漏洞检测
Format String	HIGH	CWE-134	格式化字符串漏洞
Use After Free	CRITICAL	CWE-416	释放后使用检测

🏗️ 架构

┌─────────────────────────────────────────────────────────────┐
│                      LLM / AI Agent                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ MCP Protocol (stdio/http)
┌─────────────────────────────────────────────────────────────┐
│                    Joern MCP Server                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │   Tools     │  │  Services   │  │  Query Executor     │ │
│  │ ─ project   │  │ ─ callgraph │  │ ─ Caching           │ │
│  │ ─ callgraph │  │ ─ dataflow  │  │ ─ Concurrency       │ │
│  │ ─ dataflow  │  │ ─ taint     │  │ ─ Validation        │ │
│  │ ─ taint     │  │             │  │                     │ │
│  │ ─ cfg       │  │             │  │                     │ │
│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ HTTP + WebSocket
┌─────────────────────────────────────────────────────────────┐
│                      Joern Server                           │
│                   (Code Property Graph)                     │
└─────────────────────────────────────────────────────────────┘

🧪 测试

# 运行所有单元测试
pytest tests/ -v --ignore=tests/e2e --ignore=tests/integration

# 只运行服务测试
pytest tests/test_services -v

# 运行集成测试（需要Joern）
pytest tests/integration -v --timeout=180

# 查看测试覆盖率
pytest --cov=joern_mcp --cov-report=html

🤝 贡献

欢迎提交Issue和Pull Request！

Fork本项目
创建特性分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add amazing feature')
推送分支 (git push origin feature/amazing-feature)
提交Pull Request

📄 许可证

本项目采用 Apache 2.0 许可证。

🙏 致谢

Joern - 强大的代码分析平台
FastMCP - MCP服务器框架
Model Context Protocol - LLM工具协议

🔒 让AI成为你的代码安全专家