🦡 codebadger

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

ニュース

codebadger およびその関連論文である Bridging Code Property Graphs and Language Models for Program Analysis が、Software Vulnerability Management Workshop @ ICSE 2026 に採択されました。🎉

Related MCP server: Smart Code Reviewer

引用

@article{lekssays2026bridging,
  title={Bridging Code Property Graphs and Language Models for Program Analysis},
  author={Lekssays, Ahmed},
  journal={arXiv preprint arXiv:2603.24837},
  year={2026}
}

codebadger を使用して脆弱性を発見しましたか？

codebadger が実際の脆弱性の発見に役立った場合は、ぜひお知らせください。TROPHIES.md に追加するプルリクエストを作成してください。CVE ID、プロジェクト名、1行の説明、日付を含めてください。

前提条件

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

• 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) を検出します。

カスタムツール

コアコードベースを変更せずに独自の検出器を追加できます：

1. src/tools/queries/your_query.scala に Scala クエリテンプレートを作成します。

2. src/tools/custom_tools.py に Python ツール関数を登録します。

3. サーバーを再起動すると、すべての MCP クライアントでツールが自動的に表示されます。

ステップバイステップガイド、CPGQL リファレンス、設計上の決定事項については CUSTOM_TOOLS_GUIDE.md を参照してください。

貢献とテスト

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

前提条件

• 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

トレースされる内容

設定リファレンス

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