フェーズ1: 設計レビューの体験

Security Agent の 設計レビュー は、設計ドキュメント(アーキテクチャ図・API仕様書・ER図など)をアップロードすると、AIエージェントが コードが書かれる前 にセキュリティ上の問題を指摘してくれる機能です。シフトレフトを最も早いタイミング(実装前)で実践する位置付けで、組織レベルで定義したセキュリティ要件(承認済みライブラリ・ログ基準・データアクセスポリシーなど)への準拠性も自動でチェックされます。

本章では、事前準備でダウンロード・展開した zip 内の design-doc.md を Security Agent にアップロードし、AIが設計段階の問題を指摘してくれる流れを、Create a design reviewの手順に沿って体験します。

Security Agent では、AIが設計レビューを行う際に 「セキュリティ要件」 に対する準拠性を評価します。セットアップ直後の状態では、AWS が提供するベストプラクティス由来の AWS マネージドのセキュリティ要件が10個有効化されている ため、組織独自の要件を定義しなくても、それらに対するレビューがすぐに実行できます。

1. Web Applicationを起動

セットアップ完了直後はエージェントスペース一覧画面が表示されているので、ここから今回の対象である fastapi-sample-app をクリックして詳細画面を開きます。詳細画面には「ペネトレーションテスト」「設計レビュー」「コードレビュー」の3つのカードが並んでおり、フェーズ1で使うのは「設計レビュー」カードです。

「設計レビュー」カードの 「ウェブアプリケーションで開始」 をクリックします。

別タブで Security Agent 専用の Web Application が開きます。ホーム画面の「デザインレビュー」カードにある 「デザインレビューを作成」 をクリックします。

💡 ポイント
Web Application は、マネジメントコンソールとは別の UI で、実際の設計レビュー・ペネトレーションテスト実行を行う画面です。IAM-only access で初期セットアップした場合、Administrator ユーザとしてアクセスできます(画面右上に表示)。

2. デザインレビューの作成

Web Applicationが開いたら、レビュー対象の設計書をアップロードしてAIに渡します。今回の対象は事前準備でダウンロードした design-doc.md で、Tasks APIの設計に意図的な脆弱性(認証バイパス・平文パスワード保存など)を埋め込んであります。AIがこの設計書のどこを問題と判断するかを確認していきます。

「デザインレビューを作成」画面で以下を入力します。

設定項目 値 設定の基準
デザインレビュー名 Tasks API Design アプリケーション名+「Design」で、後から識別しやすい名前にする
確認するファイル 事前準備でダウンロードしたzip内の design-doc.md フェーズ1のレビュー対象。ドラッグアンドドロップまたは「ファイルを選択」で指定

design-doc.md がアップロード済みになっていることを確認し、画面右下の 「デザインレビューを開始する」 をクリックします。

💡 ポイント
公式ドキュメントによると、デザインレビューでは以下のファイル形式・サイズ制限があります。

対応形式: DOC, DOCX, JPEG, MD, PDF, PNG, TXT
ファイル数: 1レビューあたり最大5ファイル
サイズ制限: 1ファイル2MB以下、合計6MB以下

Googleドキュメントの独自形式(.gdoc)はそのままアップロードできませんが、ダウンロード時に他形式へ変換することでデザインレビューの対象にできます。Googleドキュメント画面のファイル → ダウンロードから、用途に応じて以下を選んでください。

Microsoft Word(.docx): テキスト主体の設計書(API仕様書・データモデル定義書など)に最適。見出し・表・箇条書きなどの書式もほぼ保持される
PDFドキュメント(.pdf): アーキテクチャ図などレイアウトが重要な場合に最適
書式なしテキスト(.txt): 文章主体で書式が不要な場合

変換後、画像埋め込みが多いとサイズ超過する場合があります。2MBを超えるときは、図を別のPNGとして分けてアップロードするか、画像を圧縮してから再書き出ししてください。また、Googleドライブの共有URLを直接参照する機能はないため、必ずローカルにダウンロードしてからアップロードします。機密情報(APIキー・個人情報など)が含まれていないかもアップロード前に確認してください。

レビューが開始されると、画面上部に「デザインレビュー Tasks API Design が開始されました」の通知が表示され、デザインレビュー一覧でステータスが 「進行中」 になります。

3. レビュー結果の確認

レビューを開始した時点で、AIエージェントが設計書をAWSマネージドのセキュリティ要件と照らし合わせて分析を始めます。完了を待ち、設計書のどの部分がどの要件に違反していると判定されたかを見ていきます。

数分後にレビューが完了すると、ステータスが 「完了しました」 に変わり、コントロール件数(10個)が表示されます。一覧から Tasks API Design をクリックして詳細を開きます。

詳細画面では、検出結果の概要 として以下の4ステータスでカウントが表示されます。

ステータス 意味
非準拠 設計がセキュリティ要件に違反、または適切に対応していない
データ不足 設計書の情報が不十分で判定できない
準拠 設計が要件を満たしている
該当なし この設計には適用されない要件

意図的に脆弱な設計書を渡しているため、10個すべて「非準拠」 として検出される結果になります。下部の「検出結果のレビュー」では、評価された AWS マネージドのセキュリティ要件と、それぞれの非準拠状況が一覧表示されます。

検出されたセキュリティ要件のうち、Tasks API の設計上の問題と直接対応するものは以下です。

セキュリティ要件 検出された設計上の問題
Authentication Best Practices ログインに自前のbase64トークンを採用しているため、トークン偽造が容易
Authorization Best Practices /api/v1/users/{id} /api/v1/admin/users に認証/認可がない(誰でも全ユーザ情報を取得可能)
Secret Protection Best Practices パスワードを平文でDBに保存している
Information Protection Best Practices レスポンスにパスワードをそのまま含めている
Audit Logging Best Practices 構造化ログではなく print で標準出力へ出している
Log Protection Best Practices ログにメールアドレス(PII)を出力している
Trusted Cryptography Best Practices 認証ライブラリを使わずbase64エンコードを「トークン」と呼んでいる
Privileged Access Best Practices 管理者APIに権限制御がない
Secure by Default Best Practices 認証・暗号化・PII保護のデフォルトがすべてオフ相当
Tenant Isolation Best Practices ユーザ間のデータ境界が設計上担保されていない

各要件をクリックすると、詳細パネルが開き コンプライアンスステータス・コメント(非準拠と判定した根拠)・修正ガイダンス が表示されます。

レビュー結果一覧に複数の Findings(検出事項) がリストアップされ、各 Finding の詳細パネルで非準拠の根拠と修正ガイダンスが確認できれば、設計レビューの体験は完了です。

💡 ポイント
ここでは AWS マネージドの汎用的なセキュリティベストプラクティスに対するレビューを体験しました。組織固有のセキュリティポリシー(使用してよい認証ライブラリの限定、ログ出力ルールなど)を要件として追加すると、独自ルールに対する準拠チェックも行えるようになります。詳細は本章末尾の「参考: 組織セキュリティ要件(Security requirements)の追加」に記載があります。