variant-analysis

variant-analysis スキルの概要

variant-analysis は、すでに 1 件の確定した問題がある状態から、関連するバグを見つけるためのセキュリティ重視のスキルです。1 つの脆弱なパターンをコードベース全体で繰り返し検索できる形に落とし込めるため、Security Audit、exploit triage、より良い CodeQL や Semgrep ルール作成に特に役立ちます。

variant-analysis は何に最適か

variant-analysis skill は、「この同じ根本原因は他にどこにあるのか？」に答える必要があるときに使います。広く探索するレビューではなく、問題発見後の監査に向いています。実際の目的は、確認済みの弱点を検索パターンに変換し、そのパターンを類似のコードパスに対して検証することです。

何が違うのか

variant-analysis ガイドは、まず根本原因、次にパターンという順序を強く重視します。最初は厳密一致を優先し、その後で少しずつ検索範囲を広げ、再現率と偽陽性のバランスを取ります。そのため、一般的な「似たコードを探す」プロンプトよりも信頼性が高く、根拠を示せる findings が必要な場面で特に有効です。

どんな場面で効果が大きいか

このスキルが最も価値を発揮するのは、コピー＆ペースト、フレームワークの誤用、不完全な修正、危険な API の繰り返し利用によってバグが群発しているときです。sink、source、欠けている防御策がすでに分かっていれば、variant-analysis は手作業の grep だけよりずっと速く variants を見つける助けになります。

variant-analysis スキルの使い方

インストールして、正しいファイルを開く

variant-analysis install では、ディレクトリの trailofbits/skills 向け skill install flow を使い、まず SKILL.md と METHODOLOGY.md を確認します。その後、resources/variant-report-template.md と、resources/codeql/ および resources/semgrep/ にある言語別ルールを見て、実際にこのスキルが findings をどう表現するかを把握してください。

根本原因を一文で伝える

うまくいく variant-analysis usage は、曖昧な目的ではなく、具体的な脆弱性の記述から始まります。良い入力例は、「信頼できない HTTP パラメータが引数分離なしに exec() に到達する」や「ユーザー制御の path が canonicalization なしに file open に到達する」といったものです。この 1 文が、そのまま検索パターンになります。

厳密一致から抽象化へ進める

まずは元のバグに対する厳密一致から始め、最初の結果が狭すぎる場合にだけ一般化します。よい流れは、危険な操作を特定し、足りない guard を確認し、同じコード形状を検索し、その後で等価な API やフレームワーク特有の書き方へ広げる、というものです。これが variant-analysis usage の中心であり、早い段階で偽陽性を減らせます。

付属リソースをテンプレートとして使う

リポジトリの resources/codeql/*.ql と resources/semgrep/*.yaml は、言語ごとに variants をどう表現するかを示す実用的な参照です。まず自分のスタックに合うファイルを読み、そのうえで sources、sinks、sanitizers を自分のプロジェクトのフレームワーク規約に合わせて調整してください。Security Audit では、レポートテンプレートも特に有用です。根本原因、位置、偽陽性の理由を必ず記録する形になっているからです。

variant-analysis スキル FAQ

variant-analysis は新しいバグをゼロから見つけるためのものか

いいえ。初動の発見には最適ではありません。variant-analysis skill は、バグパターンをすでに把握していて、その兄弟パターンを探したいことを前提にしています。ゼロから探す用途ではありません。

通常のプロンプトと比べて何が違うのか

通常のプロンプトでも一般的な確認項目は出せますが、variant-analysis は、元の問題を理解し、厳密一致を作り、その後で検索範囲を広げるという規律ある手順を与えます。再現可能な Security Audit の結果が必要なときは、この構造が一発の勘より重要です。

初心者でも使いやすいか

はい。元の脆弱性を平易な言葉で説明できるなら使えます。最初から完璧な CodeQL や Semgrep を書ける必要はありませんが、具体的な source、sink、欠けている防御策は必要です。それがないと、検索範囲が広すぎて信頼できません。

どんなときに使うべきではないか

一般的なコードレビュー、見慣れないコードベースの把握、修正文の作成には使わないでください。リポジトリの理解だけが目的、または修正案だけが欲しいなら、別の workflow のほうが良い結果になります。

variant-analysis スキルをどう改善するか

exploit path を具体的にする

品質を最も左右するのは入力の精度です。「command injection を探して」ではなく、データがどう流れるのか、どの API が危険なのか、何の safeguard が欠けているのかを正確に伝えてください。variant-analysis skill は、ルールで検証できる形で root cause を定義したときに最もよく機能します。

安全なコードの姿も伝える

期待する guardrail を書くと、偽陽性は大きく減ります。たとえば、「ユーザー入力が shell command string に届くときだけ subprocess.run() を flag する」や、「filepath.Clean() と base-directory check を通る path は除外する」といった指定です。これにより、variant-analysis guide は本当の variants と意図した挙動を分けやすくなります。

理論ではなく、結果から反復する

最初のパスの後は、resources/variant-report-template.md のテンプレートと照らし合わせ、何がノイズだったか、何を取り逃したかをもとに検索パターンを調整します。単純な一致しか出ないなら抽象化レベルを上げ、偽陽性が多すぎるなら source の集合を狭めるか sanitizer を追加します。このフィードバックループこそが、variant-analysis for Security Audit を実用的にします。

言語とフレームワークごとに調整する

言語別の CodeQL や Semgrep の例は、万能ルールではなく出発点として使ってください。最も効果的な variant-analysis の改善は、プロジェクトで実際に使われている sources、sinks、安全な wrapper を差し替えて、検索結果がコードの実態に合うようにすることです。