ホワイトボックス診断
本ページでは Takumi のホワイトボックス診断の内部アーキテクチャを説明します。利用方法についてはホワイトボックス診断（都度）をご参照ください。
概要
Takumi のホワイトボックス診断では、LLM を活用したエージェントが、静的コード解析により脆弱性を発見します。
診断を開始する際、診断対象のコードが含まれたリポジトリはサンドボック ス環境内にクローンされます。複数の LLM エージェントがワークフローとして連携し、サンドボックス内で実行されるツール群を通じてコードを読み取りながら脆弱性を探索します。
各エージェントの役割と、やり取りされるデータは以下の通りです。
- Feature Enumeration: エージェントがファイル操作・検索ツールを使ってコードの構造を分析し、後続する脆弱性の発見を体系的に行うための機能のリストを出力する
- Hypothesis Generation: エージェントが各機能のコードを読み、脆弱性の仮説（脆弱性であると考えられるコードが存在する箇所とその根拠）を出力する
- Hypothesis Validation: エージェントがコードのデータフローを詳細に追跡し、アプリケーション固有の検証基準を参照しながら、仮説の真偽を判定する
- 最後に、検証済みの脆弱性をもとにレポートが生成される
なお、サンドボックス環境は 診断単位 で分離されます。すなわち、ある診断で使用される環境は、他の診断と共有されることはありません。これにより、異なる診断対象間のデータ分離が保証されます。
エージェントが使用するツール群
各エージェントはサンドボックス内で実行可能なツール群を利用して、 対象コードを自律的に探索します。ツール群は大きく以下の3つの用途に分類されます。
- ファイル閲覧・探索: ファイルの内容を読み取る、ディレクトリ構造を一覧する、パターンに一致するファイルを検索するなど、コードベースの構造を把握する
- コード検索: 正規表現による全文検索により、特定の関数呼び出しやパターンをコードベース全体から効率的に発見する
- Git: コミット履歴や差分を参照し、コードの変更経緯や最近の修正箇所を把握する
これらを組み合わせることで、エージェントは人間のセキュリティエンジニアと同様に、コードベースの構造把握、関連ファイルの特定、データフローの追跡といった作業を自律的に行います。
脆弱性探索の仕組み
ホワイトボックス診断では、分割統治（divide-and-conquer） のアプローチにより、コードベースの機能を網羅的に解析します。
LLM には一度に処理できるトークン量（コンテキストウィンドウ）に上限があるため、大規模なコードベースをそのまま渡して解析させることはできません。そこで、コードベースをまず 機能（feature） という意味のある単位に分割し、機能ごとに独立して脆弱性の仮説生成と検証を行います。これにより、各エージェントは常に限定された範囲のコードに集中でき、コンテキストウィンドウの制約の中で詳細な解析が可能になります。
機能列挙
最初に、対象コードベースを機能単位に分割します。この工程は、さらに3つのフェーズから構成されます。
除外パターンの発見
セキュリティ診断の観点で重要でないファイルを特定し、スコープから除外します。たとえば、以下のようなファイルは除外対象となります。
- テストファイル (
*_test.go,*_spec.rbなど)、ロックファイル、メディアファイル、ドキュメント、サードパーティコード (node_modules/,vendor/など) は一律で除外される - さらに、エージェントが発見したプロジェクト固有の除外パターンが除外される（例: 大量の自動生成コードを含むディレクトリ、データのみを含むディレクトリなど）
- その他、ユーザーが明示的に対象外として指定したファイルも診断対象から除外される
機能の特定
エージェントがファイル操作ツールを使ってコードの構造を分析し、API エンドポイント、認証処理、ミドルウェア、Webhook ハンドラなど、セキュリティ上重要な機能を識別します。各機能には名前、概要、関連ファイルの一覧が含まれます。
ファイルが機能に割り当てられるたびにスコープフィルタリングに反映されるため、エージェントは次の探索で、まだ検査していないファイルのみを確認できます。
優先順位付け
特定された機能数が多い場合は、エージェントが実施する脅威モデリングに基づいて優先順位付けを行います。エージェントがコードベースを探索し、攻撃者にとって価値の高い領域を評価した上で、機能の種類（例: 認証、決済、ファイルアップロード）ごとに優先度を割り当て、診断のリソースを優先度の高い領域に集中させます。
脆弱性仮説のブレインストーミング
列挙された各機能に対して、エージェントがセキュリティの専門知識を活用して脆弱性の仮説を生成します。エージェントはファイル操作ツールや Git ツールを使い、対象コードを実際に読みながら仮説を構築します。認証・認可のバイパス、SQL インジェクション、XSS、SSRF、パストラバーサル、Race Condition など、影響度の高い脆弱性 に重点が置かれます。一方で、セキュリティ関連 HTTP ヘッダーの欠如、リクエストレート制限の欠如、ロギングの不足など、攻撃者が直接悪用することが困難なカテゴリやコード以外の層で対処されることが一般的なカテゴリに含まれる事項は報告対象から除外されます。
仮説検証
出力された仮説を1件ずつ検証します。本プロセスでは、エージェントがファイル操作ツールや Git ツールを用いてコードを再度詳細に解析し、以下の観点から脆弱性の成否を判定します。
- データフロー分析: 外部入力の発生地点を特定し、脆弱なコードに到達するまでの経路全体を追跡する。各レイヤーでのサニタイズや検証の有無を確認する
- セキュリティモデルとの照合: アプリケーションの想定される利用者、機能仕様、既存のセキュリティ対策を考慮する。例えば、管理者のみが利用する機能での XSS は、一般ユーザーが利用する機能での XSS とはリスクが異なる
- アプリケーション固有の検証基準: 診断対象アプリケーションの脅威モデルや権限モデルに基づいて、報告された事象がアプリケーション本来の仕様から逸脱しているかどうかを判断する
- 攻撃シナリオの具体化: 抽象的な脆弱性ではなく、具体的な攻撃シナリオ（トリガーとなる入力例、脆弱なコード箇所）が成立するかを判定する
検証に成功した仮説のみが最終的なレポートに記載される脆弱性として採用されます。
非 LLM 系ツールとの比較
ここでは、Takumi によるエージェントベースのアプローチと、 従来型の静的コード解析ツール（SAST）を比較します。
従来型の SAST とは、ソースコードに対してあらかじめ定義されたルール（パターン）を照合することで脆弱性を検出するツールです。代表的なものに Semgrep や CodeQL があります。
設定コスト
従来型の SAST を導入する際には、以下のような設定作業が必要です。
- 対象言語・フレームワークに適したルールセットの選定
- プロジェクト固有のコーディングパターンに合わせたルールのカスタマイズ
- 誤検知（False Positive）を抑制するためのルール調整・除外設定
例えば、自社フレームワーク独自のサニタイズ関数を使っている場合、SAST はそれをサニタイズとして認識できず、誤検知が発生します。これを解消するにはルールのカスタマイズが必要になります。
一方、Takumi では、コードベースを指定するだけで診断を開始できます。エージェントがコードの構造やフレームワークの慣習を自律的に理解するため、ルールの記述や調整は不要です。
ビジネスロジックに関する脆弱性の発見
従来型の SAST は、「ユーザー入力がサニタイズされずに SQL クエリに渡されている」のような、コードの構文的なパターンとして表現できる脆弱性の検出を得意とします。
一方で、以下のような コードの意味や文脈を理解しなければ検出できない脆弱性 は発見が困難です。
- 認可の欠如: ある API エンドポイントが「管理者のみが操作できるはずのリソース」を扱っているにもかかわらず、認可チェックを実装していない。これを検出するには、「このリソースは管理者のみが操作できるべきである」というビジネスルールの理解が必要であり、構文パターンだけでは判定できない
- 制限のバイパス: EC サイトの注文確定処理で、注文確定の関数が決済完了を前提条件としてチェックしておらず、API を直接呼び出すと支払いなしで発送処理が開始されてしまう。これは個々のコード行ではなく、ワークフロー全体の前提条件の管理に問題がある
Takumi では、エージェントがコードの意味を理解したうえで解析するため、このようなビジネスロジックに関する脆弱性を発見できます。
実行コスト
従来型の SAST はパターンマッチングによる処理であり、通常のコンピューティング環境で高速に実行できます。大規模なコードベースでも数分から数十分で完了するのが一般的です。
Takumi はエージェントがコードを逐次読み解きながら解析するため、従来型の SAST と比較して実行時間・消費クレジットともに高くなります。特に、診断対象のコードベースが大きいほど、検査対象となる機能や生成される仮説の数が増加するため、実行時間・消費クレジットもそれに応じて増加します。
再現性
従来型の SAST は決定論的に動作します。同一のコードとルールに対して、何度実行しても常に同一の結果が得られます。
Takumi は LLM を用いているため、その確率的な性質上、同一コードに対する診断結果が実行ごとに若干異なることがあります。ある実行で発見された脆弱性が別の実行では発見されない、またはその逆が起こる可能性があります。