scanning-with-aws-security-agent

AWS Security Agent — Code Scans

このスキルは、リポジトリ全体のスキャンを処理します。セットアップ（エージェントスペース、ロール、バケット）は setup-security-agent スキルが処理します。.security-agent/config.json がない場合、スキャンワークフローは最初にセットアップを自動実行します。

---

アクションのマッピング

ユーザーの意図	ワークフロー
直接スキャンを依頼（「コードをスキャンして」「脆弱性を見つけて」）	Full Scan
スキャン状況を確認（「スキャンの状況は？」「進捗は？」）	Status workflow
検出結果を表示（「何が見つかった？」「結果を見せて」）	Findings workflow
スキャンを一覧表示（「最近のスキャン」「スキャン一覧を表示して」）	.security-agent/scans.json を読み取る
スキャンを停止	aws securityagent stop-code-review-job

提案を積極的に行う場合のルール

• 実行前に必ず確認してください。スキャンを自動的に開始してはいけません
• 提案は複数段落にわたる説明ではなく、1 行で伝えてください
• ユーザーが断った場合、同じセッション中に再度提案しないでください

---

ローカル状態

.security-agent/config.json を読み取り、agent_space_id と region を取得します。config.json がない場合は、「このワークスペースでの初回スキャンです。最初にセットアップを実行します。」と 1 行でユーザーに伝え、このスキルの SKILL.md に記載された手順に従って setup-security-agent ワークフローをその場で実行してから続行します。初回スキャンは「そのまま使える」必要があります。

スキャンは .security-agent/scans.json で追跡し、直近 50 件を保持します。ワークスペースごとの CodeReview ID は config.json → code_reviews[<abs_path>] に保存されるため、以降のスキャンでは同じ CodeReview が再利用されます。

必要な値の解決方法

以下の 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
<bucket>	security-agent-scans-<account>-<region>
<cr-id>	config.json → code_reviews[<abs_path>] の code_review_id
<job_id>	start-code-review-job が返す codeReviewJobId
<WORKSPACE_ID>	printf '%s' "$(pwd)" | md5sum | cut -c1-12

これらは設定から取得するのではなく導出するため、実際の状態と食い違うことはありません。

---

スキャン前の確認

1. 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. ワークスペース ID を生成します。

   WORKSPACE_ID=$(printf '%s' "$(pwd)" | md5sum | cut -c1-12)
   

---

ワークフロー：フルスキャン（約45分）

変更されたコードのみをスキャンする場合は、代わりに diff-scanning-with-aws-security-agent スキルを使用してください。脅威モデリングの仕様には、threat-modeling-with-aws-security-agent を使用してください。

1. 上記のスキャン前チェックを実行します。

2. ワークスペースを ZIP に圧縮します。 一般的なビルド／キャッシュディレクトリを除外します。.gitignore を適用します。ZIP が 2 GB を超える場合は中止します。

   cd <absolute-workspace-path>
   zip -r /tmp/source.zip . \
     -x ".git/*" \
     -x ".security-agent/*" \
     -x "node_modules/*" \
     -x "__pycache__/*" \
     -x ".venv/*" -x "venv/*" \
     -x "dist/*" -x "build/*" -x "target/*" \
     -x ".mypy_cache/*" -x ".pytest_cache/*" -x ".tox/*" \
     -x ".next/*" -x "cdk.out/*" \
     -x ".DS_Store" -x "Thumbs.db" \
     -x "*.pyc" -x "*.pyo"
   ZIP_BYTES=$(stat -f%z /tmp/source.zip 2>/dev/null || stat -c%s /tmp/source.zip)
   if [ "$ZIP_BYTES" -gt 2147483648 ]; then echo "Zip too large (>2GB)"; exit 1; fi
   

3. アップロード先には、ワークスペースごとの固定キーを使用します（以前のアップロードは上書きされます）。

   aws s3 cp /tmp/source.zip s3://<bucket>/security-scans/source/<WORKSPACE_ID>/source.zip --expected-bucket-owner <account>
   

4. ワークスペースごとの CodeReview を取得または作成します。 config.json → code_reviews[<abs_path>] を検索します。

   • 存在する場合は、その code_review_id を使用します。

   • 存在しない場合は、作成します。

     aws securityagent create-code-review --agent-space-id <id> --title <title> \
       --service-role <role-arn> \
       --assets sourceCode=[{s3Location=s3://<bucket>/security-scans/source/<WORKSPACE_ID>/source.zip}]
     

     codeReviewId を取得し、config.json → code_reviews[<abs_path>] に保存します。

   • タイトルのデフォルト値：pre-cr-<git-branch>（git rev-parse --abbrev-ref HEAD を使用）。空白はハイフンに置き換えます。

5. ジョブを開始します。

   aws securityagent start-code-review-job --agent-space-id <id> --code-review-id <cr-id>
   

   • レスポンスが ResourceNotFoundException の場合：CodeReview が外部から削除されています。再作成し（手順4）、再試行します。

6. codeReviewJobId を取得します。scan-<8-hex> のようなローカルの scan_id を生成します。scans.json に追記します。

   {
     "scan_id": "scan-...",
     "code_review_id": "cr-...",
     "job_id": "cj-...",
     "agent_space_id": "as-...",
     "scan_type": "FULL",
     "title": "pre-cr-main",
     "path": "/abs/path",
     "started_at": "2026-06-01T20:00:00Z",
     "status": "IN_PROGRESS"
   }
   

7. ユーザーに次のように伝えます：「フルスキャンを開始しました（scan_id: {id}）。約45分かかります。5分ごとに確認します。ポーリングを停止する場合は「stop polling」と言ってください。」

8. 以下の ポーリングループ を実行し、確認の間に sleep 300 を挟みます。

---

ポーリングループ

スキャンを開始した後：

1. sleep 300（5分）。これより短い間隔でポーリングしてはいけません。

2. ステータスを呼び出します。

   aws securityagent batch-get-code-review-jobs --agent-space-id <id> --code-review-job-ids <job_id>
   

3. status を最後に確認したステータスと比較します。ステータスが変化した場合（例：IN_PROGRESS → COMPLETED）、または終端状態（COMPLETED、FAILED、STOPPED）になった場合にのみ、ユーザーに応答します。

4. 「まだ進行中です」と何度も報告しないでください。不要な通知になります。

5. ユーザーが「stop polling」または「check later」と言った場合は、ループを停止し、「いつでも「scan status」または「show findings」と言ってください。」と伝えます。

6. COMPLETED の場合は、検出結果のワークフローを実行します。

7. FAILED の場合は、ジョブのエラー情報（statusReason があればそれも）を取得してユーザーに伝え、.security-agent/findings-{scan_id}.md に簡潔な失敗メモを書き込みます。

---

ワークフロー：ステータス確認（随時）

ユーザーが「scan status」／「how's the scan」と言った場合：

1. ユーザーが scan_id を指定した場合はそれを使用します。指定がない場合は、scans.json の最新のエントリを使用します。
2. batch-get-code-review-jobs を一度呼び出します。
3. scans.json のステータスフィールドを更新します。
4. ステータス、経過時間、現在のステップ（該当する場合）を報告します。

---

ワークフロー：検出結果

スキャン完了後（またはユーザーからの依頼時）：

1. 検出結果を取得する（ページネーション）

aws securityagent list-findings --agent-space-id <id> --code-review-job-id <job-id>

nextToken が返された場合は、すべて取得し終えるまで --next-token <token> を付けて再度呼び出します。

2. 詳細情報を追加する

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

3. フィルタリング（任意）

ユーザーが最低重大度（例：「high 以上」）を指定した場合は、そのレベルで絞り込みます。

• 重大度の順序：CRITICAL > HIGH > MEDIUM > LOW > INFORMATIONAL。

4. チャットで簡潔に要約する

重大度ごとにグループ化します。それぞれのファイルパスと行番号を含めます。

🟣 CRITICAL: {name}
   File: {filePath}:{lineStart}
   {description}

🔴 HIGH: {name}
   File: {filePath}:{lineStart}
   {description}

🟡 MEDIUM: {name}
   File: {filePath}:{lineStart}
   {description}

🟢 LOW: {name}
   File: {filePath}:{lineStart}
   {description}

5. 詳細レポートファイル

.security-agent/findings-{scan_id}.md に書き込みます。返されたすべてのフィールド（findingId、name、description、riskLevel、riskType、confidence、status、filePath／lineStart／lineEnd を含む codeLocations、および存在する場合は remediationCode）を含めます。

# Security Scan Report — {scan_id}

**Scan type**: FULL
**Title**: {title}
**Started**: {started_at}
**Total findings**: {count}

## Summary
| Severity | Count |
|----------|-------|
| CRITICAL | N |
| HIGH | N |
| MEDIUM | N |
| LOW | N |

## Findings

### 🟣 CRITICAL: {name}
- **ID**: {findingId}
- **Risk type**: {riskType}
- **Confidence**: {confidence}
- **Status**: {status}
- **Location**: `{filePath}:{lineStart}-{lineEnd}`

**Description**: {description}

**Remediation**:
{remediationCode or remediation guidance from description}

(repeat for every finding)

ユーザーに次のように伝えます：「詳細は .security-agent/findings-{scan_id}.md に書き込みました」

6. 追加対応

次の点を確認します。

• 「まず重大度 critical／high の検出結果に取り組みますか？」
• 「この中で、詳しい説明が必要なものはありますか？」
• 「これらの問題を修正しましょうか？」

修正する場合は、検出結果の説明とコードの場所を確認し、Edit ツールを使って修正を作成して適用します。

---

ワークフロー：スキャンの停止

ユーザーが「stop the scan」と言った場合：

aws securityagent stop-code-review-job --agent-space-id <id> --code-review-job-id <job_id>

scans.json のステータスを STOPPED に更新します。

ワークフロー：最近のスキャンを一覧表示する

ユーザーが「最近のスキャンを表示して」／「スキャンを一覧表示して」と依頼した場合：

.security-agent/scans.json を読み込み、簡潔な表で表示します。

scan_id	type	title	status	started
scan-abc	FULL	pre-cr-main	COMPLETED	2h ago
scan-def	FULL	pre-cr-feature-x	FAILED	1d ago

---

ルール

• スキャンを実行する前に、必ず事前スキャンチェック（設定の有無とエージェントスペースの確認）を実行します
• スキャン API はすぐに応答するため、5 分ごとにステータスをポーリングします
• ユーザーがスキャンを指定しない場合は、scans.json にある最新のスキャンを使用します
• タイトルにスペースを含めてはいけません。ハイフンを使用します。既定では Git ブランチ名を使用します
• 生の JSON をそのまま表示せず、重大度アイコンとファイルの場所を使って整形します
• start-code-review-job で ResourceNotFoundException が発生した場合は、CodeReview を再作成して 1 回だけ再試行します

---

トラブルシューティング

• 「未設定」／config.json が見つからない → 先に setup-security-agent スキルを実行します
• s3 cp で AccessDenied が発生する → バケットがエージェントスペースに登録されていないか、信頼ポリシーに誤りがあります。セットアップを再実行します。
• s3 cp で 403／ExpectedBucketOwner の不一致が発生する → 派生したバケットは別のアカウントが所有しています（バケットスクワッティング）。設計上、アップロードは拒否されます。ガードなしで再試行してはいけません。setup-security-agent を再実行します。別アカウントが所有するバケットが見つかった場合、処理は中断されます。
• エージェントスペースで ResourceNotFoundException が発生する → 削除されています。セットアップを再実行します。
• スキャンが 10 分を超えて PREFLIGHT のままになる → クライアントではなく、バックエンドの問題です。batch-get-code-review-jobs の出力を表示し、ユーザーにエスカレーションを依頼します。
• コードが大きすぎる（zip > 2 GB） → サブディレクトリを対象に実行します。