Joern MCP

🚀 🕷️ joern-mcp

joern-mcp 是一個模型上下文協議（MCP）服務器，它藉助 Joern 的代碼屬性圖（CPG）技術，為 AI 助手賦予靜態代碼分析能力。

🚀 快速開始

前提條件

• Python 3.8 及以上版本
• Docker
• Redis
• Git

安裝步驟

1. 克隆倉庫並安裝依賴：

git clone https://github.com/Lekssays/joern-mcp.git
cd joern-mcp
pip install -r requirements.txt

2. 進行設置（構建 Joern 鏡像並啟動 Redis）：

./setup.sh

3. 配置（可選）：

cp config.example.yaml config.yaml
# 根據需要編輯 config.yaml

4. 啟動服務器：

python main.py
# 服務器將在 http://localhost:4242 可用

✨ 主要特性

• 多語言支持：支持 Java、C/C++、JavaScript、Python、Go、Kotlin、C#、Ghidra、Jimple、PHP、Ruby、Swift 等多種語言。
• Docker 隔離：每個分析會話都在安全的容器中運行。
• GitHub 集成：可直接從 GitHub URL 分析倉庫。
• 基於會話：具有持久的 CPG 會話，並能自動清理。
• Redis 支持：實現快速緩存和會話管理。
• 異步查詢：支持非阻塞的 CPG 生成和查詢執行。
• 內置安全查詢：提供預配置的常見漏洞查詢。

💻 使用示例

基礎用法

# 創建 GitHub 會話
{
  "tool": "create_cpg_session",
  "arguments": {
    "source_type": "github",
    "source_path": "https://github.com/user/repo",
    "language": "java"
  }
}

# 獲取代碼庫概述
{
  "tool": "get_codebase_summary",
  "arguments": {
    "session_id": "abc-123-def"
  }
}

# 列出代碼庫中的所有方法
{
  "tool": "list_methods",
  "arguments": {
    "session_id": "abc-123-def",
    "include_external": false,
    "limit": 50
  }
}

# 獲取特定方法的源代碼
{
  "tool": "get_method_source",
  "arguments": {
    "session_id": "abc-123-def",
    "method_name": "authenticate"
  }
}

# 查找調用特定函數的方法
{
  "tool": "get_call_graph",
  "arguments": {
    "session_id": "abc-123-def",
    "method_name": "execute_query",
    "depth": 2,
    "direction": "incoming"
  }
}

# 搜索硬編碼的秘密
{
  "tool": "find_literals",
  "arguments": {
    "session_id": "abc-123-def",
    "pattern": "(?i).*(password|secret|api_key).*",
    "limit": 20
  }
}

# 從文件中獲取代碼片段
{
  "tool": "get_code_snippet",
  "arguments": {
    "session_id": "abc-123-def",
    "filename": "src/main.c",
    "start_line": 10,
    "end_line": 25
  }
}

# 運行自定義 CPGQL 查詢
{
  "tool": "run_cpgql_query",
  "arguments": {
    "session_id": "abc-123-def",
    "query": "cpg.method.name.l"
  }
}

高級用法

預構建查詢

list_queries 工具提供 20 多種預配置的查詢，包括：

• 安全方面：SQL 注入檢測、XSS 漏洞、硬編碼秘密、命令注入、路徑遍歷。
• 內存安全方面：緩衝區溢出風險、內存洩漏、空指針解引用、未初始化變量。
• 代碼質量方面：所有方法/函數、控制結構、函數調用、字符串字面量。

📚 詳細文檔

與 GitHub Copilot 集成

服務器使用 可流式 HTTP 傳輸以實現網絡可訪問性，並支持多個併發客戶端。 在你的 VS Code settings.json 中添加以下內容：

{
  "github.copilot.advanced": {
    "mcp": {
      "servers": {
        "joern-mcp": {
          "url": "http://localhost:4242/mcp",
        }
      }
    }
  }
}

在與 Copilot 一起使用之前，請確保服務器正在運行：

python main.py

可用工具

核心工具

• create_cpg_session：從本地路徑或 GitHub URL 初始化分析會話。
• run_cpgql_query：執行同步 CPGQL 查詢並以 JSON 格式輸出結果。
• run_cpgql_query_async：執行異步查詢並跟蹤狀態。
• get_session_status：檢查會話狀態和元數據。
• list_sessions：查看活動會話並可進行過濾。
• close_session：清理會話資源。
• list_queries：獲取預構建的安全和質量查詢。

代碼瀏覽工具

• get_codebase_summary：獲取代碼庫的高級概述（文件數量、方法數量、語言）。
• list_files：列出所有源文件，並可選擇使用正則表達式進行過濾。
• list_methods：通過名稱、文件或外部狀態過濾來發現所有方法/函數。
• get_method_source：檢索特定方法的實際源代碼。
• list_calls：查找函數調用關係和依賴項。
• get_call_graph：構建調用圖（傳出被調用者或傳入調用者），並可配置深度。
• list_parameters：獲取方法的詳細參數信息。
• find_literals：搜索硬編碼的值（字符串、數字、API 密鑰等）。
• get_code_snippet：從文件中檢索指定行範圍的代碼片段。

配置

config.yaml 中的關鍵設置如下：

server:
  host: 0.0.0.0
  port: 4242
  log_level: INFO

redis:
  host: localhost
  port: 6379

sessions:
  ttl: 3600                # 會話超時時間（秒）
  max_concurrent: 50       # 最大併發會話數

cpg:
  generation_timeout: 600  # CPG 生成超時時間（秒）
  supported_languages: [java, c, cpp, javascript, python, go, kotlin, csharp, ghidra, jimple, php, ruby, swift]

環境變量可以覆蓋配置文件中的設置（例如，MCP_HOST、REDIS_HOST、SESSION_TTL）。

示例 CPGQL 查詢

查找所有方法

cpg.method.name.l

查找硬編碼的秘密

cpg.literal.code("(?i).*(password|secret|api_key).*").l

查找 SQL 注入風險

cpg.call.name(".*execute.*").where(_.argument.isLiteral.code(".*SELECT.*")).l

查找複雜方法

cpg.method.filter(_.cyclomaticComplexity > 10).l

🔧 技術細節

架構

• FastMCP 服務器：基於 FastMCP 2.12.4 框架構建，採用 可流式 HTTP 傳輸。
• HTTP 傳輸：支持多個併發客戶端的網絡可訪問 API。
• Docker 容器：每個會話使用一個隔離的 Joern 容器。
• Redis：用於會話狀態和查詢結果緩存。
• 異步處理：支持非阻塞的 CPG 生成。
• CPG 緩存：對於相同的源/語言組合，可重用 CPG。

開發

項目結構

joern-mcp/
├── src/
│   ├── services/       # 會話、Docker、Git、CPG、查詢服務
│   ├── tools/          # MCP 工具定義
│   ├── utils/          # Redis、日誌記錄、驗證器
│   └── models.py       # 數據模型
├── playground/         # 測試代碼庫和 CPG
├── main.py            # 服務器入口點
├── config.yaml        # 配置文件
└── requirements.txt   # 依賴項

運行測試

# 安裝開發依賴
pip install -r requirements.txt

# 運行測試
pytest

# 運行測試並生成覆蓋率報告
pytest --cov=src --cov-report=html

代碼質量

# 格式化代碼
black src/ tests/
isort src/ tests/

# 代碼檢查
flake8 src/ tests/
mypy src/

故障排除

設置問題

# 重新運行設置以重建和重啟服務
./setup.sh

Docker 問題

# 驗證 Docker 是否正在運行
docker ps

# 檢查 Joern 鏡像
docker images | grep joern

# 檢查 Redis 容器
docker ps | grep joern-redis

Redis 連接問題

# 測試 Redis 連接
docker exec joern-redis redis-cli ping

# 查看 Redis 日誌
docker logs joern-redis

# 重啟 Redis
docker restart joern-redis

服務器連接問題

# 測試服務器是否正在運行
curl http://localhost:4242/health

# 查看服務器日誌以查找錯誤
python main.py

調試日誌

export MCP_LOG_LEVEL=DEBUG
python main.py

📄 許可證

文檔中未提及許可證相關信息。

貢獻

1. Fork 倉庫。
2. 創建功能分支：git checkout -b feature-name。
3. 進行更改並添加測試。
4. 運行測試：pytest && black . && flake8。
5. 提交拉取請求。

致謝

• Joern - 靜態分析平臺
• FastMCP - MCP 框架
• Model Context Protocol - MCP 規範