variant-analysis

バリアント分析

すでに発見したバグの別の発生箇所を見つけます。1 つの根本原因が複数の形で現れることはよくあり、最初に見つけたモジュールに現れるとは限りません。

使用する場合

• 脆弱性が見つかり、類似する発生箇所を検索する必要がある
• セキュリティパターン向けの CodeQL／Semgrep クエリを作成または改善する
• 最初の問題を発見した後、体系的なコード監査を行う
• 1 つの根本原因が異なるコードパスでどのように現れるかを分析する

使用しない場合

• 脆弱性を初めて発見する場合 — audit-context-building またはドメイン固有の監査を使用してください
• 検索対象となる既知のパターンがない一般的なコードレビュー
• 修正の推奨事項を書く場合 — issue-writer を使用してください
• 不慣れなコードを理解する場合 — まず audit-context-building を使用してください

5 つのステップ

各ステップに進んだら、そのステップのリファレンスを読んでください。

1. 元の問題を理解する。 根本原因、つまりコードが何をするかではなく、なぜ間違っているのかを抽出し、バリアントが潜んでいる可能性のある方向を列挙します。関連する識別子、同じ間違いの別の現れ方、データ型のエッジケースなどです。 → references/root-cause.md

2. 完全一致を作成する。 既知の発生箇所だけに一致するパターンを書き、それが検出されることを確認します。何も検出されない場合、バグを誤解していることになり、そのパターンを基に構築するすべての検索が、誤ったコードを基準に調整されます。

3〜4. 1 つずつ一般化する。 完全一致からパターンファミリーへと段階的に広げ、変更を 1 つ行うたびに、すべての一致結果を実行して確認します。一致結果の半分以上がノイズになるところで止めてください。 → references/searching.md — 抽象化の段階、ツールの選択、誤検知のフィルター

5. トリアージする。 候補が実際の問題かどうかを判断し、重大度を付けて明示します。 → references/triage.md

その後、報告書にまとめます。 失敗したパターンと、再発を防ぐ CI ルールも含めてください。 → references/reporting.md

ワークフローとして実行する

このプラグインには /variant-analysis:variants が含まれています。これは、並列サブエージェントで 5 つのステップを実行します。各サブエージェントは拡張軸を 1 つずつ担当し、新たな発見がなくなるまで繰り返します。各段階では、その作業に対応する上記のリファレンスを読みます。

コードベースが大規模な場合や、根本原因に多くの現れ方がある場合は、このワークフローを使用してください。検索範囲が狭い場合や、一般化の各段階を自分で判断したい場合は、各ステップを直接進めてください。

調査が失敗する原因

1. 範囲が狭い — 元のバグが発生したモジュールだけを検索する
2. パターンが具体的すぎる — 1 つの属性だけを検索し、その周辺のパターンファミリーを見落とす
3. 脆弱性の種類が 1 つだけ — 根本原因の現れ方を 1 つだけ追いかける
4. 正常系だけをテストする — null、空、境界値のケースを一度も試さない
5. 一般化を急ぎすぎる — 複数の要素を一度に抽象化し、ノイズの原因を特定できなくなる

最初の 3 つについては root-cause.md と searching.md で、4 つ目については triage.md で説明しています。

リソース

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