cpg-analysis

cpg-analysis skill の概要

cpg-analysis は、通常のリポジトリざっと見では足りない場面のための、深いコード解析 skill です。Joern CPG と CodeQL を使って、制御フロー、データフロー、プログラム依存関係、taint path、セキュリティ上の指摘を読み解くのに役立ちます。セキュリティレビューをしているとき、関数をまたいでバグを追跡したいとき、ある入力が sink にどう到達するかを証明したいときに使うべき skill です。

最適な用途: セキュリティ監査とフロー追跡

cpg-analysis は、Security Audit の作業に特に向いています。たとえば、「この入力は危険な sink に到達できるか？」や「複数ファイルをまたいで source から sink までどんな経路があるか？」といった問いに答えたいときです。表面的なコード説明ではなく、証拠に基づいた解析が求められる場面で最も力を発揮します。

何が違うのか

一般的なプロンプトと違い、cpg-analysis はグラフベースの推論を前提に設計されています。AST で構造を、CFG で実行順序を、データフローグラフで伝播を捉えます。実務上の違いは、セキュリティや正しさに関する問いで追跡性が高いことです。特に、大規模なコードベースでは、単純な grep や要約だけでは本当の経路を見落としやすいため、その差がはっきり出ます。

インストールする価値があるのはどんなときか

深い静的解析、taint tracking、脆弱性探索を繰り返し行う見込みがあるなら、cpg-analysis をインストールする価値があります。逆に、必要なのが素早いコードナビゲーションだけなら、tier-1 のメモリ系ツールで十分なことが多く、動作も軽めです。

cpg-analysis skill の使い方

cpg-analysis をインストールして実行環境を確認する

まずリポジトリの skill manager で cpg-analysis skill をインストールし、使う予定の経路に必要な runtime がそろっているか確認します。Joern ベースのワークフローには通常 Docker と JVM が必要で、CodeQL ベースのワークフローには CodeQL CLI が必要です。ローカルや作業環境でそれらを実行できない場合、プロンプトがどれだけ良くても skill の有効性は大きく制限されます。

まずは適切なファイルから読む

最初に SKILL.md を開き、その後で tier の選び方、Joern を使うべき場面、主要な MCP tools を説明している部分を読みます。そこには、クエリ生成に時間を使う前に、どの解析経路を選ぶべきかが書かれています。skill が特定の repository tree を参照しているなら、記憶で推測せず、まずその対応関係に従ってください。

曖昧な依頼を実用的なプロンプトに変える

cpg-analysis をうまく使うには、まず「この repo を解析して」ではなく、具体的な解析対象を置くことが重要です。以下を含めると効果的です。

• repository またはサブディレクトリ
• 分かっているなら言語や framework
• セキュリティ上の問い、または bug 仮説
• 気にしている source、sink、機能
• 「runtime execution はしない」「auth flow に絞る」などの制約

プロンプトの例:
Use cpg-analysis to trace whether user-controlled input from the API reaches command execution in src/ without sanitization. Focus on interprocedural paths and show the key nodes and files.

段階的なワークフローで進める

cpg-analysis の優れた使い方は、たいてい 2 段階です。まず関連する表面を広めに把握し、その後で経路を深掘りします。最初は entry point と候補 sink を見つけられる程度に広く取り、次に関係する関数やファイルへ絞り込みます。こうすることで、過信を減らし、出力を実際のデータフローに結びつけたままにできます。

cpg-analysis skill の FAQ

cpg-analysis はセキュリティ用途だけですか？

いいえ。Security は最も分かりやすい用途ですが、この skill は bug hunt、実行経路の推論、複雑なコードベースで値がどう動くかの理解にも役立ちます。単純な文字列一致ではなく、制御フローやデータフローが問われる場面で特に有用です。

毎回 Joern と CodeQL の両方が必要ですか？

必ずしもそうではありません。CPG ベースの探索なら Joern が最初の選択肢として適していることが多く、interprocedural な security query や脆弱性パターンを狙うなら CodeQL のほうが強い場面があります。デフォルトで両方を回すのではなく、問いに合う tool を選んでください。

cpg-analysis は初心者向けですか？

初心者でも使えますが、タスクが具体的であることが前提です。曖昧な依頼からは曖昧な解析しか返ってきません。ファイル名、入力 source、危険な sink を挙げられるなら、cpg-analysis skill はかなり使いやすくなります。

どんなときに cpg-analysis を使うべきではありませんか？

ドキュメント検索、基本的なリファクタリングの助言、1 ファイルのざっくり要約だけが必要なら、cpg-analysis を使う必要はありません。インストールコストのある skill なので、グラフベースの tool を使うだけの深さがあるときにこそ価値があります。

cpg-analysis skill の改善方法

解析対象をもっと絞る

最も重要な改善点は、スコープを絞ることです。「セキュリティ問題を見つけて」は広すぎますが、「routes/ 内の request params が exec または SQL query construction に到達するかを追跡して」はずっと有効です。source と sink を明確にすると、cpg-analysis の出力はより実用的になり、不要な探索も減ります。

重要な制約を共有する

Docker が使えない、コードベースが polyglot である、静的解析だけにしたい、といった制約があるなら、最初に伝えてください。制約があると、実行可能なワークフローが変わり、skill が実行できない経路を提案するのを防げます。cpg-analysis のインストール判断では、ここが有用か使えないかの分かれ目になることがよくあります。

結論ではなく証拠を求める

やり取りを重ねるときは、結論だけでなく chain を求めてください。entry point、中間関数、graph node、最終 sink までを示すように頼むと、Security Audit の cpg-analysis で重要な推論が見える形になります。最初の結果が広すぎる場合は、次に欲しい file set や query type を指定して絞り込みます。

より良い仮説で再実行する

最初の結果がノイズの多いものだったなら、一般的な再試行を頼むのではなく、仮説を改善してください。たとえば「認証周りの問題を見つけて」を、「test code と mocks を除外しつつ、router から sensitive handler への unauthenticated access を追跡して」に置き換えます。仮説が明確であるほど、cpg-analysis の出力は高信号になりやすいです。