remediating-with-aws-security-agent

セキュリティエージェントによる修正

AWS Security Agent は、オンデマンドの侵入テストとコードレビューを顧客のアプリケーションに対して実行し、検証済みのセキュリティリスクを報告する最先端のエージェントです。このスキルを使うと、「AWS のどこかに検出結果がある」状態から、「最も重要な問題の修正に取り組んでいる」状態へ移行できます。その際、機密性の高いエクスプロイトの詳細をソース管理に含めないようにします。

このフローには 4 つの段階があり、順番が重要です。

1. 検出：どのスキャンが存在し、アカウントがどのように構成されているかを確認します（ライブ、読み取り専用）。
2. エクスポート：検出結果をローカルの gitignore 対象ディレクトリにエクスポートします。
3. トリアージ：検出結果を優先順位付けし、人が読みやすい計画にまとめます。
4. 修正：最もリスクの高い問題の修正を提案します。

順序とガードレールが重要な理由

検出結果には、実行可能な攻撃スクリプト、再現手順、ファイルパス、場合によっては漏えいしたシークレットや環境の詳細が含まれます。それらが Git リポジトリに入ると、顧客が誤ってコミットして公開し、自社の本番システムに対する段階的なエクスプロイト手順を公開してしまう可能性があります。したがって、譲れないルールは、検出結果は .security-agent/ にのみ書き込み、何かを書き込む前にそのパスを gitignore 対象にすることです。

ステージ 1：スキャンを検出する（ライブ、読み取り専用）

アカウントに何があるか確認します。コマンドはすべて読み取り専用の list-* 操作です。

AWS Security Agent はデータを階層構造で整理しています。上位から順に確認します。

Application (account + Region)
└── Agent Space        (workspace for design review, code review, and pentests)
    ├── Penetration test → Pentest job → Findings
    └── Code review      → Code review job → Findings

状況を把握し、存在するものをユーザーに示すため、次のコマンドを実行します。

aws securityagent list-agent-spaces
aws securityagent list-pentests          --agent-space-id <as-...>
aws securityagent list-code-reviews      --agent-space-id <as-...>
aws securityagent list-pentest-jobs-for-pentest         --agent-space-id <as-...> --pentest-id <pt-...>
aws securityagent list-code-review-jobs-for-code-review --agent-space-id <as-...> --code-review-id <cr-...>

ジョブの status は IN_PROGRESS、STOPPING、STOPPED、FAILED、COMPLETED のいずれかです。安定した完全な検出結果一式が得られるのは、COMPLETED ジョブのみです。

コードベースをスキャンに照合し、確認する

エージェントスペース、ペンテスト、コードレビューには、対象となるアプリケーションの名前が付けられています。未加工の一覧からユーザーに選んでもらう前に、どのスキャンがこのリポジトリに対応するか、根拠のある推測をしてください。ユーザーがこのコードベースで作業しているのには理由があり、関連する検出結果はほぼ常に目の前のアプリに関するものです。

手軽で有力な情報源を使って、ワークスペースからアプリの識別情報を推測します。

• リポジトリ名またはルートディレクトリ名、および Git のリモート URL（git remote -v）。
• プロジェクトマニフェストと、その name／description（package.json、pyproject.toml、*.csproj、go.mod、Cargo.toml）。
• README のタイトル、製品や方針に関するドキュメント、明らかな製品名や企業名。
• スキャンのタイトルと一致する特徴的なフレームワークやドメイン。

これらの情報をエージェントスペース名やスキャン名と照合します（大文字と小文字は区別せず、部分一致やあいまい一致を許容します）。 その後、エクスポートする前に必ず確認してください。最有力の候補とその根拠を示し、ユーザーが訂正できるようにします。

「このリポジトリは <product>（<signal> に基づく）に見えます。これは エージェントスペースと一致します。これを使用しますか、それとも別のものを選びますか？［他のエージェントスペース名など］」

妥当な確信をもって一致するものがない場合は、その旨を率直に伝え、誤った候補を無理に選ばせず、完全な一覧を提示します。ユーザーの確認なしに、推測したスキャンからエクスポートしてはいけません。

ステージ 2：検出結果を .security-agent/ にエクスポートする（gitignore 対象）

AWS CLI コマンドを使って検出結果を取得します。検出結果には実行可能な攻撃スクリプト、再現手順、場合によっては漏えいしたシークレットが含まれるため、すべてをリポジトリ内の .security-agent/ に書き込みます。チャットや標準出力には決して出力しないでください。

1. 取得前に出力ディレクトリを保護する

mkdir -p .security-agent
echo '*' > .security-agent/.gitignore

2. 最新の COMPLETED ジョブを特定する

ステージ 1 で agentSpaceId とペンテスト／コードレビュー ID をすでに取得しているはずです。選択したスキャンのジョブを一覧表示します。

# Pentest jobs:
aws securityagent list-pentest-jobs-for-pentest \
  --agent-space-id <as-...> --pentest-id <pt-...>

# Code review jobs:
aws securityagent list-code-review-jobs-for-code-review \
  --agent-space-id <as-...> --code-review-id <cr-...>

前の応答の --next-token を渡し、トークンがなくなるまでページネーションします。ジョブの概要を status == "COMPLETED" でフィルタリングします。COMPLETED のジョブがない場合は処理を中止し、ユーザーに「完了したジョブが見つかりません。ジョブが完了するまで待つか、ジョブのステータスを確認してください。」と伝えます。それ以外の場合は、createdAt タイムスタンプが最も新しい COMPLETED ジョブを選択します。

3. 検出結果の概要を一覧表示し、信頼度で絞り込む

# Pentest findings:
aws securityagent list-findings \
  --agent-space-id <as-...> --pentest-job-id <pj-...>

# Code review findings:
aws securityagent list-findings \
  --agent-space-id <as-...> --code-review-job-id <cj-...>

--next-token がなくなるまでページネーションします。信頼度の弱い順から強い順： FALSE_POSITIVE、UNCONFIRMED、LOW、MEDIUM、HIGH。 デフォルトでは HIGH と MEDIUM のみを残してください。 ユーザーから明示的に求められた場合にのみ、対象を広げます。

4. 詳細を25件ずつ取得する

batch-get-findings が1回の呼び出しで受け付けるIDは最大25件です。絞り込んだ検出結果のIDを25件ずつのグループに分けます：

aws securityagent batch-get-findings \
  --agent-space-id <as-...> \
  --finding-ids <fid-1> <fid-2> ... <fid-25>

書き出す前に、返された各検出結果にソース（pentest または code-review）のタグを付け、ステージ3のトリアージで区別できるようにします。

5. 検出結果を .security-agent/ に書き込む

検出結果をジョブIDごとにまとめます。各ジョブについて、APIから返されたすべてのフィールド（findingId、name、description、riskLevel、riskType、confidence、status、codeLocations、remediationCode、その他のフィールドを含む）を記載した完全なMarkdownレポートを .security-agent/findings_<jobId>.md に書き込みます。フィールドを省略しないでください。

エッジケース

• エージェントスペース、スキャン、または COMPLETED ジョブがない場合 — 再試行せず、停止してその旨をユーザーに伝えます。
• 認証情報に問題がある場合、またはサービスを利用できない場合 — aws sts get-caller-identity で確認し、リージョンも確認します（デフォルトは us-east-1。Security Agent はリージョンごとに提供されます）。
• 検出結果の内容をチャットに貼り付けないでください。短いタイトルと件数を除きます。詳細は gitignore 対象のファイルに記載します。

ステージ3：検出結果をトリアージし、優先順位を付けた計画を作成する

修正にかけられる時間には限りがあるため、リスクに基づいて順位を付けます。CRITICAL の未認証 RCE は、常に LOW の情報提供のみの検出結果より優先されます。.security-agent/ 内のエクスポート済み findings_*.md ファイルを読み込み、決定論的に並べ替えます。

ランキングルール

次の複合キーの昇順で並べ替えます（値が小さいほど優先度が高く、より緊急です）。

1. リスクレベル。順序は次のとおりです： CRITICAL (0) → HIGH (1) → MEDIUM (2) → LOW (3) → INFORMATIONAL (4) → UNKNOWN / 欠落 (5)。
2. リスクスコア。高い順です。riskScore は pentest の検出結果では数値文字列（例："10.0"）で、code-review の検出結果では存在しないことがよくあります。同じレベルのスコア付き検出結果より後に並ぶよう、欠落している場合は可能な最小スコアとして扱います。
3. 信頼度。順序は次のとおりです： HIGH (0) → MEDIUM (1) → LOW (2) → UNCONFIRMED (3) → FALSE_POSITIVE (4)。

また、レポートのヘッダー用に、すべての検出結果にわたる重大度ごとの件数を集計します（例：2 CRITICAL · 5 HIGH · 3 MEDIUM）。

コードの場所を特定する

各検出結果について、短い location 文字列を1つ導き出します。

• filePath が設定されている場合は、その値をそのまま使用します。
• それ以外の場合は、codeLocations[0] を使用します。filePath からスキャナーのサンドボックスのプレフィックス（そのマーカーまでのすべての部分とマーカー自体）を取り除き、リポジトリ相対パスにします。マーカーが見つからない場合は、ベース名を使用します。lineStart がある場合は :<lineStart> を追加します。
• どちらも利用できない場合（pentest の検出結果の一部に多く見られます）は空欄にし、代わりに影響を受けるエンドポイントまたは攻撃チェーンを影響の行で説明します。

概要の形式

ユーザー向けに簡潔な概要を作成します。

## Security Agent triage — <agent space name>

<N> findings exported (<P pentest, C code review>) · confidence: <levels> · severity: <counts>

### Priority order
1. [CRITICAL · score 10.0 · HIGH confidence] <finding name>
   - Type: <riskType> · Source: <pentest|code-review>
   - Where: <file:line or endpoint, if present>
   - Impact: <one-line plain-language summary>
2. [HIGH · ...] ...

### Recommended remediation order
<short rationale: which to fix first and why — e.g. "1 and 3 are both
unauthenticated RCE on internet-facing endpoints; fix those before the
stored-XSS issues.">

検出結果が約10件を超える場合は、上位N件の詳細を示し、残りは末尾に重大度ごとの件数としてまとめます。

チャットに含めない情報

完全な description、reasoning、attackScript は gitignore 対象のファイルに残します。これらには、実行可能なエクスプロイトの詳細が含まれています。チャットの概要では、影響の説明を平易な言葉で各1行に収めます。Code-review の検出結果には通常 filePath／場所と suggestedFix が含まれているため、リポジトリの変更に直接結びつくこれらの情報を示します。Pentest の検出結果にはエンドポイントや攻撃チェーンが記載されています。可能な場合は、該当するコードと関連付けます。相互に裏付け合う検出結果（pentest と code review が同じ根本原因を指摘するもの）がないか確認してください。これらは、何を最初に修正すべきかを判断するうえで強い手がかりになります。

ステージ 4: 修復の提案

トリアージを提示した後、修正の開始を提案してください。黙ってコードの編集を始めないでください。

ユーザーに次のように尋ねてください:「上位の検出事項の修正を始めましょうか?#1()から始めることをおすすめします。」ユーザーが同意した場合は、優先度の高い順に上から作業を進めます:

1. gitignore されたエクスポートファイルから検出事項の詳細(場所、説明、推奨される修正)を読み取ります。
2. 影響を受けるファイルを開き、エディター経由で修正を適用します。
3. 修正ごとに 1 行で報告します:「{name} を {filePath}:{lineStart} で修正しました。」

ユーザーが複数の検出事項に対応したい場合は、各変更がレビュー可能な状態を保てるよう、一度に 1 件ずつ(または関連する検出事項の 1 つのまとまりずつ)修正し、ステージ 3 の優先順位に従って進めてください。

注意事項とエッジケース

• 完了したジョブがない: スキャンが IN_PROGRESS である可能性があります。部分的なジョブをエクスポートするのではなく、その旨をユーザーに伝え、後で再確認することを提案してください。
• 再実行: 実行するたびに、そのジョブ ID のファイルが上書きされます。このディレクトリは削除しても問題ありません。エクスポートされたコピーのみが含まれており、ソースオブトゥルースのデータは含まれていません。
• 複数のアカウント/リージョン: 検出事項はリージョン単位でスコープされます。ユーザーが結果を期待したのに何も得られなかった場合は、Security Agent が構成されているリージョンと一致しているかを確認してください。
• データの取り扱い: エクスポートされた検出事項は機密情報として扱ってください。これらはユーザー自身のシステムに対して検証されたエクスプロイトのコピーです。