Agents Please コードレビューガイド：安全なセットアップガイド

Agents Please コードレビューガイドは、AI エージェントを使用してプルリクエスト、リポジトリ、または独立したコードサンプルを検査するチーム向けに設計されています。目的はレビュアーを置き換えることではありません。レビュー準備を迅速化し、セキュリティに関わる経路を明らかにし、人間のエンジニアが調査すべき質問をより明確に把握できるようにすることです。

まず、レビューの境界を狭く設定します。エージェントがアクセスできるブランチ、コミット、変更ファイル、プログラミング言語、テストコマンド、ディレクトリを特定します。スコープを制限すると結果を監査しやすくなり、無関係なレガシーコードがレビューを圧倒する可能性も減らせます。

レビューの境界

有用なレビューが答えるべきこと

優れた AI 支援レビューは、次の 5 つの質問への回答に役立つ必要があります。

• 何が変更され、どの動作に影響するのか？
• 信頼できない入力はシステムのどこから入るのか？
• その入力を受け取る関数、サービス、権限はどれか？
• 報告された各問題を裏付ける証拠は何か？
• どのテストまたはパッチがリスクを低減するのか？

一般的な懸念を列挙するだけのレポートは、ファイルパス、影響を受けるシンボル、データフローの推論、実践的な検証手順を含む、より短いレポートほど有用ではありません。

準備によって、エージェントが実行可能な分析を生成するか、推測の寄せ集めを生成するかが決まります。開始前に、平易な言葉で短いレビュー概要を書きます。機能の目的、想定される信頼境界、既知の機密操作、変更してはならない領域を含めてください。

Web サービスの場合、概要には認証、認可、ファイルアップロード、バックグラウンドジョブ、サードパーティリクエスト、データベースへの書き込み、モデルまたはプロンプトとの統合を含めることがあります。ライブラリの場合は、安全でないパーサー、シリアライズ、依存関係の変更、公開 API との互換性を重視することがあります。

レビュー概要テンプレート

実践的な指示セット

発見、推論、報告を分離する指示を使用します。

1. 変更されたコードと、その直接の呼び出し元をマッピングする。
2. 外部入力、機密データ、特権操作、ネットワークリクエストを特定する。
3. 疑わしい値を、検証、変換、保存、出力の各段階で追跡する。
4. コード上の証拠で裏付けられる問題だけを報告する。
5. 確認済みの欠陥、妥当性のある懸念、作成者への質問を区別する。
6. 明示的に許可されていない限り、変更を適用せずにテストを提案する。

この構造は、よくある失敗も防ぎます。つまり、エージェントが危険なパターンに気づいても、バリデーター、フレームワークの制御、上流の権限によってすでに悪用が防止されているかどうかを確認しないという失敗です。

AI コードレビューは、表現がどれほど恐ろしく聞こえるかではなく、悪用可能性と影響に基づいて検出結果を順位付けすると、より効果的になります。コメントの欠落と、ユーザーが制御できるサーバーサイドリクエストに同じ注意を向けるべきではありません。

信頼できない入力と、特権的または外部から見える動作を結び付ける経路から着手します。一般的な例には、データベースクエリに到達するリクエストパラメータ、パーサーに到達するアップロードコンテンツ、HTTP クライアントに到達する設定可能な URL、別のモデルへの指示に挿入されるユーザーテキストなどがあります。

検出結果の分類

リスクのトリアージマトリクス

脆弱性の疑いをレビューする際は、完全な連鎖を示すようエージェントに依頼します。

• ソース：値はどこから発生するのか？
• 変換：デコード、解析、連結、正規化のいずれかが行われているか？
• 制御：どの検証、認可、エンコード、許可リストが適用されるか？
• シンク：どの操作が値を使用するのか？
• 影響：攻撃者または誤動作するユーザーによって何が引き起こされる可能性があるか？
• 検証：主張を実証する安全なテストは何か？

たとえば、外部リクエストだからといって、自動的にサーバーサイドリクエストフォージェリの問題になるわけではありません。レビュアーは、攻撃者が宛先を操作できるか、プライベートアドレスまたはメタデータアドレスに到達できるか、リダイレクトが制御されているか、アプリケーションに許可された宛先ポリシーがあるかを確認する必要があります。

同様に、プロンプトに挿入された文字列が、必ずしもプロンプトインジェクションの成功を意味するわけではありません。レビューでは、モデルの境界、生成された出力の権限、利用可能なツール、信頼できないコンテンツがシステム指示から明確に分離されているかを特定する必要があります。

焦点を絞ったレビューでは、すべての一致が悪用可能だと決めつけることなく、頻繁に欠陥を生み出すパターンを調査します。以下のカテゴリは、Agents Please ワークフローの出発点として役立ちます。

パッチレビューの基準

提案された修正は、報告された症状を隠すだけでなく、原因に対処する必要があります。次の点を確認してください。

• 正しい信頼境界で入力を検証している。
• 正当なユーザーに対して期待される動作を維持している。
• 関連するすべてのコードパスに認可を適用している。
• 機密情報を漏えいさせずに失敗を処理している。
• 修正がなければ失敗する回帰テストを含んでいる。
• 別のエンドポイントやバックグラウンドジョブを通じて、2 つ目のバイパスを導入していない。

レビューは、エージェントがレポートを生成した時点では完了しません。チームがどの検出結果が有効かを判断し、担当者を割り当て、適切な修正を適用し、変更が安全に動作することを確認した時点で完了します。

受け入れた検出結果と未解決の質問は分けて管理します。これにより、長いレポートがリリースを妨げる少数の問題を覆い隠すことを防げます。また、将来同じコードパスに遭遇するレビュアーにとって有用な履歴にもなります。

レビュー完了表

有用な最終レポートは、簡潔でありながら具体的です。受け入れた各問題について、影響を受けるコンポーネント、リスク、証拠、推奨される修正、担当者、検証ステータスを含めます。却下した各問題については、無効と判断した制御または前提条件を記録します。これにより、後続のプルリクエストで同じ調査を繰り返す必要が減ります。

同じ誤検知が頻繁に発生する場合は、レビュー指示を改善するか、リポジトリのガイダンスを追加します。同じ実際の欠陥が繰り返し発生する場合は、手動検出を繰り返し頼るのではなく、共有ヘルパー、フレームワークの制御、lint ルール、テストフィクスチャ、またはアーキテクチャの変更に投資します。