pentesting-with-aws-security-agent

AWS Security Agent — ペネトレーションテスト

このスキルでは、ペネトレーションテストの設定、実行、検出結果の確認を行います。初回の Security Agent 設定（エージェントスペース、ロール、バケット）は setup-security-agent スキルで行います。.security-agent/config.json が見つからない場合、ペネトレーションテストのワークフローでは、最初にインラインで自動的にセットアップを実行します。

ペネトレーションテストは時間がかかり（1～24 時間）、実際に稼働しているアプリを調査するアクティブなテストです。開始前に、ユーザーがテスト対象をテストする権限を持っていることを必ず確認してください。

---

必要な値の解決

以下の CLI の例ではプレースホルダーを使用しています。ペネトレーションテストのたびに、開始時に値を解決してください。

プレースホルダー	解決方法
<id>（エージェントスペース）	config.agent_space_id
<region>	config.region（デフォルトは us-east-1）
<account>	aws sts get-caller-identity --query Account --output text（このターンの残りの間はキャッシュしてください）
<role-arn>	arn:aws:iam::<account>:role/SecurityAgentScanRole
<td-id>	create-target-domain が返す targetDomainId（config.target_domains[<domain>] にキャッシュしてください）
<pentest-id>	create-pentest が返す pentestId
<pj-id>	start-pentest-job が返す pentestJobId

ペネトレーションテスト前の確認

1. .security-agent/config.json を読み取ります。 見つからない場合は、ユーザーに「このワークスペースで初めてのペネトレーションテストです。先にセットアップを実行します。」と一言伝え、続行する前に setup-security-agent ワークフローをインラインで実行します。

2. エージェントスペースがまだ存在することを確認します。

   aws securityagent batch-get-agent-spaces --agent-space-ids <id>
   

   存在しない場合は、config.json から agent_space_id を削除し、setup-security-agent を再度実行します。

3. 上の表からアカウントとロール ARN を解決します。

4. 権限の確認： 文脈から明らかでない場合は、ユーザーに「<target> を所有している、またはペネトレーションテストを行う明示的な許可を得ていますか？」と尋ねます。確認が取れるまでは続行しないでください。

---

ワークフロー

1. ターゲットドメインを登録する（ドメインごとに一度）

aws securityagent create-target-domain --agent-space-id <id> \
  --target-domain-name <domain> --verification-method HTTP_ROUTE

応答には、検証トークンまたはルートが含まれます。サーバーに設定する内容（通常はトークンを返す .well-known/... ファイルまたは HTTP ルート）をユーザーに伝えてから、次を実行します。

aws securityagent verify-target-domain --agent-space-id <id> --target-domain-id <td-id>

検証済みの target_domain_id を .security-agent/config.json の target_domains: { "<domain>": "<td-id>" } に保存し、今後のペネトレーションテストで再利用できるようにします。

2. ペネトレーションテストを作成する

ユーザーに次の情報を尋ねます。

• タイトル（スペースは使わず、ハイフンを使用します。デフォルトは pentest-<timestamp>）
• テストするエンドポイント（検証済みドメイン内の URI を 1 つ以上）

aws securityagent create-pentest --agent-space-id <id> --title <title> \
  --service-role <role-arn> \
  --assets endpoints=[{uri=https://example.com/api/login},{uri=https://example.com/api/upload}]

pentestId を取得します。

3. ペネトレーションテストのジョブを開始する

aws securityagent start-pentest-job --agent-space-id <id> --pentest-id <pentest-id>

pentestJobId を取得します。.security-agent/pentests.json に追記します（まだ存在しない場合は [] として作成します。ディレクトリ自体はセットアップによってすでに作成されています）。

{
  "pentest_id": "p-...",
  "pentest_job_id": "pj-...",
  "agent_space_id": "as-...",
  "title": "pentest-...",
  "endpoints": ["https://..."],
  "started_at": "2026-06-01T20:00:00Z",
  "status": "IN_PROGRESS"
}

ユーザーに次のように伝えます。「ペネトレーションテストを開始しました（{pentest_job_id}）。テスト範囲によって異なりますが、通常は 1～24 時間かかります。15 分ごとに確認します。確認を停止する場合は『stop polling』と言ってください。」

4. ポーリングループ

1. 確認の間隔として sleep 900（15 分）を実行します。それより短い間隔でポーリングしないでください。

2. 状態を確認します。

   aws securityagent batch-get-pentest-jobs --agent-space-id <id> --pentest-job-ids <pj-id>
   

3. status が変化したとき、または終端状態（COMPLETED、FAILED、STOPPED）になったときにのみ応答します。

4. COMPLETED になったら、検出結果のワークフローを実行します。

5. 検出結果

aws securityagent list-findings --agent-space-id <id> --pentest-job-id <pj-id>

nextToken が返された場合は、空になるまで --next-token <token> を指定して再度呼び出します。

aws securityagent batch-get-findings --agent-space-id <id> --finding-ids <id1> <id2> ...

重大度ごとにグループ化して、チャットに表示します（コードスキャンと同じアイコンおよび形式を使用します）。

🟣 CRITICAL: {name}
   Endpoint: {endpoint}
   {description}

返されたすべてのフィールド（findingId、name、description、riskLevel、riskType、confidence、status、endpoint、存在する場合はリクエスト／レスポンスのサンプルと remediationCode）を含む完全なレポートを .security-agent/pentest-{pentest_job_id}.md に書き込みます。

ユーザーに「詳細な情報を .security-agent/pentest-{pentest_job_id}.md に書き込みました」と伝えます。

6. ペネトレーションテストを停止する

aws securityagent stop-pentest-job --agent-space-id <id> --pentest-job-id <pj-id>

---

ルール

• 開始する前に、必ず対象をテストする許可を確認してください
• ペンテストを作成する前に、対象ドメインを検証してください。検証しないと create-pentest は失敗します
• 再検証する代わりに、config.json にある検証済みの target_domain_id を再利用してください
• ペンテストのタイトルにスペースを含めないでください。ハイフンを使用してください
• ポーリングは最大15分間隔で行ってください。ペンテストは長時間実行されます
• 失敗したペンテストを自動で再起動しないでください。まず失敗内容をユーザーに提示してください

---

トラブルシューティング

• verify-target-domain で ValidationException が発生する → 検証ルートがまだ正しく応答していません。ルートが稼働しており、想定されるトークンを提供していることをユーザーに確認してください。
• target domain not verified → verify-target-domain（手順1）を再実行してください。
• ペンテストが24時間以上 IN_PROGRESS のままになっている → バックエンドの問題か、対象に到達できない可能性があります。停止して調査してください。
• サービスロールで AccessDenied が発生する → サービスロールに、ペンテストに必要なネットワーク／ランタイムの権限がありません。デフォルトの SecurityAgentScanRole はコードスキャン専用です。AWS リソースに対するペンテストには、より広範な権限が必要な場合があります。ペンテスト専用のロールを設定するよう、ユーザーに AWS Security Agent コンソールを案内してください。