cpg-analysis

CPG 分析スキル

目的： AST を超える詳細なコード分析を行います。Joern を使用して完全なコードプロパティグラフ（制御フロー、データフロー、プログラム依存関係）を分析し、CodeQL を使用して関数間の汚染分析と脆弱性検出を行います。

これらはオプトインのツールです。 Docker/JVM（Joern）または CodeQL CLI が必要です。 日常的なナビゲーションには codebase-memory-mcp（Tier 1、常時利用可能）を使用してください。 Tier 1 では不十分な場合に、詳細な分析にこれらを使用してください。

┌────────────────────────────────────────────────────────────────┐
│  CODE PROPERTY GRAPH = AST + CFG + CDG + DDG + PDG             │
│  ─────────────────────────────────────────────────────────────│
│  AST  = Abstract Syntax Tree (structure)                       │
│  CFG  = Control Flow Graph (execution paths)                   │
│  CDG  = Control Dependency Graph (conditional dependencies)    │
│  DDG  = Data Dependency Graph (data flow between statements)   │
│  PDG  = Program Dependency Graph (CDG + DDG combined)          │
│                                                                │
│  Tier 2 (Joern): Full CPG with 40+ query tools                │
│  Tier 3 (CodeQL): Interprocedural taint + security queries     │
└────────────────────────────────────────────────────────────────┘

---

Tier 選択ガイド

Simple symbol lookup, dependency trace, blast radius?
  → Tier 1: codebase-memory-mcp (always on, sub-ms)

Control flow paths, data flow, dead code, complex refactoring?
  → Tier 2: Joern CPG (on-demand, seconds)

Security audit, taint analysis, vulnerability detection?
  → Tier 3: CodeQL (on-demand, seconds to minutes)

Full security review before release?
  → All three tiers in sequence

---

Tier 2：Joern CPG（CodeBadger MCP）

Joern を使用する場面

シナリオ	Joern を使う理由	Tier 1 ではできないこと
関数間のデータフローを追跡する	完全な DDG トラバーサル	Tier 1 にはデータフローがありません
制御フローのパスを理解する	分岐条件を含む CFG 分析	Tier 1 には CFG がありません
デッドコード／到達不能コードを見つける	PDG 到達可能性分析	Tier 1 が検出するのは未使用のエクスポートのみです
複雑なリファクタリングの影響を調べる	関数間の依存関係チェーン	Tier 1 は呼び出しグラフに限定されます
サードパーティライブラリの使用状況を監査する	深い呼び出しチェーンのトラバーサル	Tier 1 はインポート境界で止まります
例外の流れを理解する	CFG に throw/catch パスが含まれます	Tier 1 は例外を無視します

主要な MCP ツール（Joern/CodeBadger）

ツール	目的	クエリ例
generate_cpg	プロジェクトの CPG を構築します	初回セットアップ時、または大幅な変更後
get_cpg_status	CPG の構築状況を確認します	クエリ前に CPG の準備ができていることを確認します
run_cpgql_query	任意の CPGQL クエリを実行します	cpg.method("login").callOut.code.l
get_cpgql_syntax_help	クエリ言語のリファレンスを取得します	クエリ構文が不明な場合
get_cfg	メソッドの制御フローグラフを取得します	関数内の実行パスを理解します
list_methods	プロジェクト内のすべてのメソッドを一覧表示します	利用可能な関数の概要を把握します
get_method_source	メソッドのソースコードを取得します	特定の関数のソースを読みます
list_calls	メソッドから／メソッドへの呼び出しを一覧表示します	呼び出し元／呼び出し先を分析します
get_call_graph	完全な呼び出しグラフを可視化します	呼び出しチェーンを理解します
get_type_definition	型／クラスの定義を取得します	型階層を理解します

対応言語（Joern）

Java、Scala、C/C++、Python、JavaScript、TypeScript、PHP、Ruby、Go、 Kotlin、Swift、Lua

非対応： Rust（Rust には CodeQL を使用してください）

MCP の設定（Joern）

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

前提条件

• Docker（Joern バックエンド用）
• Python 3.10+（MCP サーバー用）
• インストール：~/.claude/install-graph-tools.sh --joern

よく使う CPGQL クエリ

// Find all methods that handle user input
cpg.method.where(_.parameter.name(".*input.*|.*request.*")).name.l

// Trace data flow from parameter to return
cpg.method("processPayment").parameter.reachableBy(cpg.method("processPayment").methodReturn).l

// Find methods with high cyclomatic complexity
cpg.method.where(_.controlStructure.size > 10).name.l

// Dead code: methods with no callers
cpg.method.where(_.callIn.size == 0).filter(_.name != "main").name.l

// Exception flow: methods that can throw but callers don't catch
cpg.method.where(_.ast.isThrow.size > 0).callIn.method.filter(_.ast.isTry.size == 0).name.l

---

Tier 3：CodeQL

CodeQL を使用する場面

シナリオ	CodeQL を使う理由	他の Tier ではできないこと
リリース前のセキュリティ監査	関数間の汚染分析	Joern の汚染分析は基本的なものですが、CodeQL はより詳細です
認証／決済コードのレビュー	ソースからシンクへのデータフロー	関数間、ファイル間の汚染分析
PR のセキュリティレビュー	対象を絞った脆弱性スキャン	事前構築済みの OWASP クエリパック
コンプライアンスチェック	CWE/OWASP パターンマッチング	厳選されたセキュリティクエリスイート
Rust のセキュリティ分析	Rust を完全にサポート	Joern は Rust をサポートしていません

主要な MCP ツール（CodeQL）

ツール	目的
run_query	データベースに対して CodeQL クエリを実行します
find_definitions	シンボルの定義を特定します
find_references	シンボルへのすべての参照を検索します
get_results	BQRS（Binary Query Result Sets）を解析します

対応言語（CodeQL）

C/C++、C#、Go、Java、Kotlin、JavaScript、TypeScript、Python、Ruby、 Swift、Rust

MCP の設定（CodeQL）

{
  "mcpServers": {
    "codeql": {
      "command": "codeql-mcp",
      "args": ["--database", ".code-graph/codeql-db"]
    }
  }
}

前提条件

• CodeQL CLI（macOS では brew install codeql）
• インストール：~/.claude/install-graph-tools.sh --codeql

よく使う CodeQL パターン

// SQL injection: user input flows to SQL query
import python
from DataFlow::PathNode source, DataFlow::PathNode sink
where TaintTracking::hasFlowPath(source, sink)
  and source instanceof RemoteFlowSource
  and sink instanceof SqlExecution
select sink, source, sink, "SQL injection from $@.", source, "user input"

// Unvalidated redirect
from DataFlow::PathNode source, DataFlow::PathNode sink
where source instanceof RemoteFlowSource
  and sink instanceof RedirectSink
select sink, "Unvalidated redirect from user input"

---

組み合わせたワークフロー：詳細分析

セキュリティレビューや複雑なリファクタリングを行う際は、すべての Tier を使用してください。

1. SCOPE       → Tier 1: detect_changes / get_architecture
                 Identify files and modules in scope

2. STRUCTURE   → Tier 1: search_graph / trace_call_path
                 Map the call graph and dependencies

3. FLOW        → Tier 2: get_cfg / run_cpgql_query
                 Analyze control flow and data flow paths

4. SECURITY    → Tier 3: run_query with taint analysis
                 Check for vulnerabilities in data paths

5. REPORT      → Combine findings from all tiers
                 Prioritize: Critical > High > Medium > Low

---

避けるべきパターン

避けるべきパターン	代わりに行うこと
単純なシンボル検索に Joern/CodeQL を使用する	Tier 1 search_graph を使用します（ミリ秒未満で、数秒かかる方法より高速です）
コミットのたびに CPG をフルビルドする	CPG は必要に応じてビルドし、継続的な監視には Tier 1 を使用します
get_cpg_status を確認せずに Joern にクエリを実行する	クエリを実行する前に、CPG がビルド済みで最新であることを必ず確認します
具体的なセキュリティ上の問いがないまま CodeQL を実行する	まず仮説を立てます。CodeQL のクエリはコストがかかります
詳細な分析の前に Tier 1 で影響範囲を確認しない	まず Tier 1 で範囲を絞り、フラグが立った領域を詳しく分析します
セキュリティ以外の構造的なクエリに CodeQL を使用する	構造やフローのクエリには Joern CPGQL を、セキュリティには CodeQL を使用します