Code Reason

コーディングエージェント向けプログラム解析。

grepして推測する代わりに、code-reasonでエージェントにプログラム解析機能を提供しましょう。

code-reasonは、データフローの到達可能性、コールグラフのたどり方、証拠チェーンの構築など、実際のプログラム解析プリミティブをコーディングエージェントに提供するMCP サーバーです。推測ではなく、確かな根拠に基づいてコードの動作を検証できます。

code-reasonを使う理由

コーディングエージェントはコードを読むのが得意ですが、プログラム全体に関する質問には苦戦します。

• ユーザーが制御する入力は実際にこのSQL呼び出しに到達するのか、それともサニタイズによってフローが遮断されるのか？
• コードベース全体で、この関数を実際に呼び出しているのは誰か？
• ソースからシンクまでの完全な証拠チェーンは何か？

コード解析ツールがなければ、エージェントはこうした質問に手作業でgrepしながら追跡して回答します。コードは読めても、データフローを実際に追跡したり、制御フローグラフをたどったり、ユーザー入力がシンクに到達することを検証したりはできません。ツールなしでどのように汚染を追跡するのか、最新のコーディングエージェントに尋ねれば、「ファイルを読んで文字列の一致を追います」といった答えが返ってくるでしょう。

単純なケースならそれでうまくいきます。しかし、エイリアスされた変数、関数間のフロー、サニタイズのチェック、フレームワークが注入する入力など、複雑なケースでは問題が表面化します。エージェントは依然として回答を出しますが、多くの場合、自信満々でありながら、たった1つのチェーンを確認するために6個以上のファイルを読み、推測にコンテキストを費やし、grepしようと思いつかなかったフローを気づかないまま見落としています。セキュリティ上重要な作業では、自信に満ちた誤答は無回答より危険です。そして、それこそがgrepベースの追跡を大規模に行ったときに生じる問題です。

code-reasonはこのギャップを埋めます。エージェントは何に注目するかを決め、code-reasonは一度解析すれば低コストでクエリできるコードプロパティグラフに基づいて、実際に正しいことを答えます。その結果、より決定的でトークン効率が高く、動作の速いエージェントと、実際に信頼できるエージェント型セキュリティワークフローを実現できます。

従来のSASTツールが人間によるトリアージを前提とした検出結果レポートを作成するのに対し、code-reasonはエージェントが独自の調査を進めるための解析プリミティブを公開します。

多言語のデータフロー、制御フロー、汚染解析にはFraunhofer AISECのCode Property Graphを使用し、エージェントから呼び出せるツールとして機能を公開するためにKotlin MCP SDKを使用しています。

得られるもの

実際のJavaおよびPythonのコードベースで行ったドッグフーディングセッションの結果：

• 複数ステップのセキュリティレビューで、エージェントのトークン消費を30〜40％削減。 手作業で確認するには通常5〜10回のgrepが必要となるコールグラフクエリが、主な削減要因です。
• ファイル全体のダンプではなく、簡潔で構造化された回答。 コールグラフクエリは到達可能なメソッドをJSONで返します。一方、grepして読み進める方法では、1つのチェーンを確認するためにエージェントが6個以上のファイルを読む必要があります。
• サービスごとに解析は1回、クエリは無制限。 reason_analyze_projectでCPGを一度構築すれば、他のすべてのreason_*ツールから低コストでクエリできます。
• 実際の証拠チェーン。 reason_trace_taint_pathは、「SQLiかもしれない」といった推測ではなく、中間ステップとコードコンテキストを含む、ソースからシンクまでの完全な経路を返します。

仕組み

code-reason は、コーディングエージェントとコードプロパティグラフの間に位置します。エージェントが処理を進め、code-reason が回答します。

   Coding agent (Claude Code, Cursor, ...)
              │  MCP over stdio
              ▼
       code-reason server
              │
              ▼
   Fraunhofer CPG (Java + Python frontends)
              │
              ▼
        Target codebase

一般的なループは、次の 3 つのフェーズで実行されます。

1. 分析。 エージェントが reason_analyze_project を呼び出します。CPG は対象のコードベースを解析し、抽象構文、制御フロー、データフロー、評価順序をすべて 1 つのクエリ可能な構造にまとめたマルチグラフを構築します。

2. クエリ。 エージェントが 1 つ以上の reason_* ツールを呼び出します。それぞれが、汚染の伝播、呼び出しグラフのたどり方、データフローの到達可能性、証拠チェーンの構築といった、特定のグラフ操作に変換されます。

3. 推論。 各ツールは、構造化された結果（位置、パス、信頼度、証拠）を返します。エージェントはそれらの結果を自身の文脈に応じた推論と組み合わせ、次に何を尋ねるかを判断します。

エージェントは 意図 と大局的な推論を担い、code-reason は実際のグラフに基づく 正確な回答 を提供します。grep と推測に頼ることも、過剰に大きなコンテキストを出力することもありません。

ツール

code-reason は、目的別にグループ化された 9 つの MCP ツールを公開します。

グループ	ツール	目的
セットアップ	reason_analyze_project	プロジェクトを解析し、コードプロパティグラフを構築する
ナビゲーション	reason_find_entry_points	HTTP ハンドラー、CLI エントリーポイント、フレームワークのフックを特定する
ナビゲーション	reason_find_callers	「この関数を呼び出しているのは誰か？」
ナビゲーション	reason_find_callees	「この関数は何を呼び出しているか？」
データフロー	reason_query_dataflow	データフローグラフ上の順方向／逆方向の到達可能性を調べる
データフロー	reason_trace_taint_path	任意の 2 点間の、ソースからシンクまでの完全な証拠チェーン
カタログスキャン（便利機能）	reason_scan_injections	カタログ駆動の汚染解析（SQLi／XSS／コマンドインジェクション）
カタログスキャン（便利機能）	reason_list_supported_checks	組み込みの脆弱性チェックを一覧表示する
カタログスキャン（便利機能）	reason_get_finding_detail	スキャン結果の説明と修正方法

最大の価値は、ナビゲーションとデータフローのプリミティブです。エージェントはこれらを組み合わせ、プログラム全体に関する質問に独自に回答します。カタログスキャンツールは、初回の迅速なトリアージに便利なベースラインです。実際のコードベースで違いを生むのは、プリミティブを使ったエージェント自身の推論です。

前提条件

• JDK 21

ビルドでは Maven Central と Sonatype Central Snapshots から CPG のアーティファクトを取得します。後者は、CPG 11.x が Central で安定版としてリリースされるまでの main-SNAPSHOT 用です。兄弟リポジトリのチェックアウトは必要ありません。

ビルド

./gradlew installDist

ランチャーは build/install/code-reason/bin/code-reason に生成されます。

テストの実行

./gradlew test

統合テストでは、小規模な Java および Python のフィクスチャを使って、パイプライン全体を実行します。

Claude Code のセットアップ

プロジェクト単位の .mcp.json、またはグローバル設定の ~/.claude/.mcp.json に code-reason を追加します。

{
  "mcpServers": {
    "code-reason": {
      "command": "/absolute/path/to/build/install/code-reason/bin/code-reason",
      "args": ["--stdio"]
    }
  }
}

Claude Code を再起動すると、ツール一覧に reason_* ツールが表示されます。

ワークフローの例

プリミティブを組み合わせて証拠を集める、エージェント主導の一般的なセッションは次のとおりです。

1. エージェントが reason_analyze_project を呼び出して、CPG を構築します。
2. エージェントが reason_find_entry_points を呼び出し、外部入力がコードベースに入る箇所を列挙します。
3. 疑わしいエントリーポイントについて、エージェントは reason_find_callees と reason_query_dataflow を使って、下流への到達範囲を把握します。
4. データが機微な呼び出しに到達したら、エージェントは reason_trace_taint_path を呼び出し、ソースからシンクまでの完全な証拠チェーンを取得します。
5. エージェントは構造化された結果から悪用可能性を推論し、次に何を調査するかを判断します。

初回の迅速なトリアージでは、エージェントは reason_scan_injections を呼び出して組み込みカタログから候補となるフローを抽出し、その後 reason_trace_taint_path で各候補を検証することもできます。

対応言語

• Java
• Python

対応する cpg-language-* 依存関係を build.gradle.kts に追加すると、CPG の追加フロントエンド（C/C++、Go、TypeScript、JVM、LLVM、Ruby）を有効にできます。

ステータス

code-reason は v0.1.0 で、初期段階の研究グレードです。CI はプッシュとプルリクエストのたびに実行されます。現在、ビルドは CPG main-SNAPSHOT に固定されています。Fraunhofer が Maven Central に安定版の 11.x を公開したら、そちらに切り替える予定です。

ライセンス

Apache 2.0 です。詳細は LICENSE をご覧ください。

謝辞

Fraunhofer AISEC の Code Property Graph を基盤として構築されています。