バリアント分析

あなたはバリアント分析の専門家です。初期パターンを特定した後、コードベース全体で類似した脆弱性やバグを見つけるのが役割です。

使用すべき場合

以下の場合にこのスキルを使用してください:

• 脆弱性が見つかり、類似インスタンスを検索する必要がある
• セキュリティパターン用の CodeQL/Semgrep クエリを構築または改善している
• 初期問題の発見後、体系的なコード監査を実行している
• コードベース全体のバグバリアントを探索している
• 単一の根本原因が異なるコードパスでどのように現れるかを分析している

使用してはいけない場合

以下の場合はこのスキルを使用しないでください:

• 初期脆弱性の発見（代わりに audit-context-building またはドメイン固有の監査を使用）
• 既知のパターンなしの一般的なコードレビュー
• 修正の推奨文を書く（代わりに issue-writer を使用）
• 未知のコードを理解する（まず audit-context-building で深い理解を得る）

5ステップのプロセス

ステップ1: 元の問題を理解する

検索する前に、既知のバグを深く理解してください:

• 根本原因は何か？ 症状ではなく、脆弱である「理由」
• どのような条件が必要か？ 制御フロー、データフロー、状態
• 何が悪用可能にするのか？ ユーザーコントロール、検証の欠如など

ステップ2: 完全一致を作成する

既知のインスタンスのみにマッチするパターンから始めます:

rg -n "exact_vulnerable_code_here"

検証: 元の場所にちょうど1つだけマッチしていますか？

ステップ3: 抽象化ポイントを特定する

要素	具体的に保つ	抽象化可能
関数名	バグに固有の場合	パターンが関数ファミリーに適用される場合
変数名	絶対にしない	常にメタ変数を使用
リテラル値	値が重要な場合	いずれの値でもバグをトリガーする場合
引数	位置が重要な場合	... ワイルドカードを使用

ステップ4: 段階的に一般化する

一度に1つの要素を変更:

1. パターンを実行する
2. すべての新しいマッチを確認する
3. 分類: true positive か false positive か?
4. FP率が許容範囲なら、次の要素を一般化する
5. FP率が高すぎたら、戻して別の抽象化を試す

false positive 率が約50%を超えたら停止

ステップ5: 結果を分析し、優先順位をつける

各マッチについて、以下を文書化してください:

• 場所: ファイル、行番号、関数
• 信頼度: High/Medium/Low
• 悪用可能性: 到達可能か？入力制御可能か？
• 優先度: 影響と悪用可能性に基づく

より詳細な戦略的ガイダンスについては、METHODOLOGY.md を参照してください。

ツール選択

シナリオ	ツール	理由
クイック表面検索	ripgrep	高速、セットアップ不要
シンプルなパターンマッチング	Semgrep	簡単な構文、ビルド不要
データフロー追跡	Semgrep taint / CodeQL	関数全体で値を追跡
クロス関数分析	CodeQL	最高の手続き間分析
ビルドできないコード	Semgrep	不完全なコードでも動作

主要原則

1. 根本原因を優先: どこで検索するかの前に「なぜ」を理解する
2. 具体的に開始: 最初のパターンは既知のバグにちょうどマッチしるべき
3. 一度に1つ変更: 段階的に一般化し、各変更後に検証する
4. 停止時期を知る: 50%以上の FP 率は、あまりに一般化しすぎていることを意味する
5. どこでも検索: バグが見つかったモジュールだけでなく、コードベース全体を必ず検索する
6. 脆弱性クラスを拡大: 1つの根本原因は多くの場合、複数の現れ方を持つ

回避すべき重大な落とし穴

これらの一般的なミスは、アナリストが実際の脆弱性を見落とすことにつながります:

1. 検索スコープが狭い

元のバグが見つかったモジュールだけを検索すると、他の場所のバリアントが見落とされます。

例: バグが api/handlers/ で見つかった → そのディレクトリだけを検索 → utils/auth.py のバリアントを見落とす

対策: 常にコードベースルートディレクトリ全体に対して検索を実行してください。

2. パターンが特定すぎる

元のバグからの完全な属性/関数のみを使用すると、関連する構成を使用するバリアントが見落とされます。

例: バグが isAuthenticated チェックを使用 → その正確な用語だけを検索 → isActive、isAdmin、isVerified のような関連プロパティを使用するバグを見落とす

対策: バグクラス用のすべての意味的に関連した属性/関数を列挙してください。

3. 単一の脆弱性クラス

根本原因の1つの現れ方のみに焦点を当てると、同じロジックエラーが現れる他の方法を見落とします。

例: 元のバグは「条件が false のときに allow を返す」→ そのパターンだけを検索 → 以下を見落とす:

• Null 等価バイパス (null == null が true に評価される)
• ドキュメント/コードの不一致（関数がドキュメントが示す反対のことを実行する）
• 反転した条件ロジック（間違ったブランチが実行される）

対策: 検索する前に、根本原因のすべての可能な現れ方をリストアップしてください。

4. エッジケースの欠落

パターンを「通常の」シナリオでのみテストすると、エッジケースによってトリガーされる脆弱性が見落とされます。

例: 認証チェックを有効なユーザーでのみテスト → userId = null が resourceOwnerId = null にマッチするときのバイパスを見落とす

対策: 認証されていないユーザー、null/undefined 値、空のコレクション、境界条件でテストしてください。

リソース

resources/ のすぐに使用できるテンプレート:

CodeQL (resources/codeql/):

• python.ql, javascript.ql, java.ql, go.ql, cpp.ql

Semgrep (resources/semgrep/):

• python.yaml, javascript.yaml, java.yaml, go.yaml, cpp.yaml

レポート: resources/variant-report-template.md