Joern MCP

🚀 🕷️ joern-mcp

このサーバーは、Joern のコードプロパティグラフ（CPG）技術を使用して、AIアシスタントに静的コード分析機能を提供するモデルコンテキストプロトコル（MCP）サーバーです。

✨ 主な機能

• 多言語対応：Java、C/C++、JavaScript、Python、Go、Kotlin、C#、Ghidra、Jimple、PHP、Ruby、Swift
• Dockerによる隔離：各分析セッションは安全なコンテナ内で実行されます
• GitHubとの統合：GitHubのURLから直接リポジトリを分析できます
• セッションベース：自動クリーンアップ付きの永続的なCPGセッション
• Redisベース：高速なキャッシュとセッション管理
• 非同期クエリ：非ブロッキングのCPG生成とクエリ実行
• 組み込みのセキュリティクエリ：一般的な脆弱性に対する事前設定済みのクエリ

🚀 クイックスタート

前提条件

• 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 で利用可能になります

📚 ドキュメント

GitHub Copilotとの統合

サーバーはネットワークアクセス性のために Streamable 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：JSON出力で同期的なCPGQLクエリを実行します
• 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：行範囲でファイルからコードスニペットを取得します

💻 使用例

基本的な使用法

# 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脆弱性
• ハードコードされたシークレット
• コマンドインジェクション
• パストラバーサル

メモリセーフティ：

• バッファオーバーフローのリスク
• メモリリーク
• ヌルポインタ参照
• 初期化されていない変数

コード品質：

• すべてのメソッド/関数
• 制御構造
• 関数呼び出し
• 文字列リテラル

設定

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フレームワーク上に構築され、Streamable HTTP トランスポートを使用しています
• HTTPトランスポート：複数の同時クライアントをサポートするネットワークアクセス可能なAPI
• Dockerコンテナ：セッションごとに1つの隔離された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. リポジトリをフォークする
2. 機能ブランチを作成する：git checkout -b feature-name
3. 変更を加え、テストを追加する
4. テストを実行する：pytest && black . && flake8
5. プルリクエストを送信する

🙏 謝辞

• Joern - 静的分析プラットフォーム
• FastMCP - MCPフレームワーク
• Model Context Protocol - MCP仕様