🦡 codebadger

Java、C/C++、JavaScript、Python、Go、Kotlin、C#、Ghidra、Jimple、PHP、Ruby、Swiftをサポートする、Joernのコードプロパティグラフ（CPG）技術を用いた静的コード解析を提供するコンテナ化されたModel Context Protocol（MCP）サーバーです。

前提条件

開始する前に、以下がインストールされていることを確認してください：

• Docker および Docker Compose

• Python 3.10+ (Python 3.13を推奨)

• pip (Pythonパッケージマネージャー)

セットアップを確認するには：

docker --version
docker-compose --version
python --version

クイックスタート

1. Python依存関係のインストール

# Create a virtual environment (optional but recommended)
python -m venv venv

# Install dependencies
pip install -r requirements.txt

2. Dockerサービスの起動 (Joern)

docker compose up -d

これにより以下が起動します：

• Joern Server: 静的コード解析エンジン（CPG生成とクエリを実行）

サービスが実行中であることを確認します：

docker compose ps

3. MCPサーバーの起動

# Start the server
python main.py &

MCPサーバーは http://localhost:4242 で利用可能になります。

4. 全サービスの停止

# Stop MCP server (Ctrl+C in terminal)

# Stop Docker services
docker-compose down
# Optional: Clean up everything
bash cleanup.sh

クリーンアップスクリプト

提供されているクリーンアップスクリプトを使用して環境をリセットします：

bash cleanup.sh

これにより以下が行われます：

• Dockerコンテナの停止と削除

• 孤立したJoern/MCPプロセスの終了

• Pythonキャッシュのクリア (__pycache__, .pytest_cache)

• オプションでプレイグラウンドディレクトリ（CPGおよびキャッシュされたコードベース）のクリア

統合

GitHub Copilotとの統合

VS Code（GitHub Copilot）のMCP設定ファイルを編集します：

パス:

~/.config/Code/User/mcp.json

設定例:

{
  "inputs": [],
  "servers": {
    "codebadger": {
      "url": "http://localhost:4242/mcp",
      "type": "http"
    }
  }
}

Claude Codeとの統合

codebadger を Claude Desktop に統合するには、以下を編集します：

パス:

Claude → Settings → Developer → Edit Config → claude_desktop_config.json

以下を追加します：

{
  "mcpServers": {
    "codebadger": {
      "url": "http://localhost:4242/mcp",
      "type": "http"
    }
  }
}

利用可能なツール

コア

• generate_cpg: コードベース（ローカルパスまたはGitHub URL）のコードプロパティグラフ（CPG）を生成します。

• get_cpg_status: CPGが存在するか確認し、ステータスメタデータを取得します。

• run_cpgql_query: CPGに対して生のCPGQLクエリを実行し、構造化された結果を返します。

• get_cpgql_syntax_help: CPGQL構文のヘルパー、ヒント、一般的なエラーの修正方法を表示します。

コードブラウジング

• list_methods: 正規表現/ファイルフィルターを使用してメソッド/関数を一覧表示します。

• list_files: ソースファイルをページネーションされたツリービューで表示します。

• get_method_source: 指定したメソッドのソースコードを取得します。

• list_calls: 関数間の呼び出しサイト（呼び出し元 → 呼び出し先）を一覧表示します。

• get_call_graph: 人間が読める形式のコールグラフ（入力または出力）を構築します。

• list_parameters: メソッドのパラメータ名、型、順序を取得します。

• get_codebase_summary: 高レベルのメトリクス（ファイル数、メソッド数、呼び出し数、言語）を取得します。

• get_code_snippet: 開始行と終了行番号を指定してファイルのスニペットを返します。

セマンティック解析

• get_cfg: メソッドの制御フローグラフ（ノードとエッジ）を生成します。

• get_type_definition: 構造体/クラスの型とそのメンバーを調査します。

• get_macro_expansion: マクロ展開された可能性のある呼び出しをヒューリスティックに検出します。

汚染（Taint）および脆弱性解析

• find_taint_sources: 外部入力ポイント（ソース）の可能性が高い場所を見つけます。

• find_taint_sinks: 汚染されたデータが流れる可能性のある危険なシンクを特定します。

• find_taint_flows: ソースからシンクへのデータフローを検出します（汚染解析）。

• get_program_slice: 呼び出しに対する前方/後方プログラムスライスを構築します。

• get_variable_flow: 特定の場所における変数のデータ依存関係を追跡します。

• find_bounds_checks: バッファアクセスの近くで境界チェックを検索します。

• find_use_after_free: Use-After-Freeパターンのヒューリスティック検出を行います。

• find_double_free: 二重解放（Double-Free）の可能性を検出します。

• find_null_pointer_deref: Nullポインタ参照の可能性が高い場所を見つけます。

• find_integer_overflow: 整数オーバーフローパターンを検出します。

• find_format_string_vulns: printf系関数に非リテラルのフォーマット引数が渡されるフォーマット文字列脆弱性（CWE-134）を検出します。

• find_heap_overflow: ヒープバッファへの書き込みが割り当てサイズを超えるヒープオーバーフロー脆弱性（CWE-122）を検出します。

• find_stack_overflow: 固定サイズのローカル配列（例: char buf[64]）への書き込みが宣言された次元を超えるスタックバッファオーバーフロー脆弱性（CWE-121）を検出します。

• find_toctou: access()/stat() でファイルを確認した後に別のステップで開いたり操作したりするTime-of-Check-Time-of-Use競合状態（CWE-367）を検出します。

• find_uninitialized_reads: 値が代入される前にローカル変数が使用される未初期化変数読み取り（CWE-457）を検出します。

貢献とテスト

貢献ありがとうございます！テストの実行とコードへの貢献を始めるためのクイックガイドです。

前提条件

• Python 3.10+ (CIでは3.13を使用)

• Docker および Docker Compose (統合テスト用)

ローカル開発環境のセットアップ

1. 仮想環境を作成し、依存関係をインストールします

python -m venv venv
pip install -r requirements.txt

2. Dockerサービスを起動します（統合テスト用）

docker-compose up -d

3. ユニットテストを実行します

pytest tests/ -q

4. 統合テストを実行します（Docker Composeの実行が必要）

# Start MCP server in background
python main.py &

# Run integration tests
pytest tests/integration -q

# Stop MCP server
pkill -f "python main.py"

5. すべてのテストを実行します

pytest tests/ -q

6. テスト後のクリーンアップ

bash cleanup.sh
docker-compose down

コードへの貢献

貢献する際は以下のガイドラインに従ってください：

1. リポジトリの規約に従う

2. 動作変更にはテストを書く

3. PRを提出する前にすべてのテストがパスすることを確認する

4. PRの説明に明確な変更履歴を含める

5. 必要に応じてドキュメントを更新する

設定

MCPサーバーは環境変数または config.yaml を通じて設定できます。

環境変数

主要な設定（オプション - デフォルト値が表示されています）：

# Server
MCP_HOST=0.0.0.0
MCP_PORT=4242

# Joern
JOERN_BINARY_PATH=joern
JOERN_JAVA_OPTS="-Xmx4G -Xms2G -XX:+UseG1GC -Dfile.encoding=UTF-8"

# CPG Generation
CPG_GENERATION_TIMEOUT=600
MAX_REPO_SIZE_MB=500

# Query
QUERY_TIMEOUT=30
QUERY_CACHE_ENABLED=true
QUERY_CACHE_TTL=300

# Telemetry (OpenTelemetry)
OTEL_ENABLED=false
OTEL_SERVICE_NAME=codebadger
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc

設定ファイル

config.example.yaml から config.yaml を作成します：

cp config.example.yaml config.yaml

その後、必要に応じてカスタマイズしてください。

テレメトリ (OpenTelemetry)

CodeBadgerには、分散トレーシングのためのOpenTelemetryサポートが組み込まれています。有効にすると、すべてのMCPツール呼び出しが自動的にトレースされ、さらにCPG生成、Joernサーバー管理、クエリ実行のためのカスタムスパンが追加されます。

クイックスタート

1. テレメトリの依存関係をインストールします（requirements.txt に含まれています）：

pip install opentelemetry-sdk opentelemetry-exporter-otlp

2. 環境変数で有効にします：

export OTEL_ENABLED=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
python main.py

または config.yaml で有効にします：

telemetry:
  enabled: true
  service_name: codebadger
  otlp_endpoint: http://localhost:4317
  otlp_protocol: grpc  # or "http/protobuf"

Jaegerを使用したローカル開発

# Start Jaeger (provides UI at http://localhost:16686)
docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

# Start CodeBadger with telemetry
OTEL_ENABLED=true python main.py

トレース対象

設定リファレンス

テレメトリが無効（デフォルト）の場合、すべてのトレースはオーバーヘッドなしのノーオペレーションとなります。