SKILLOfficialdevelopment

diff-scanning-with-aws-security-agent

プラグイン: aws-agents-for-devsecops
ソース: GitHub で見る ↗

説明

AWS セキュリティエージェント（クラウド上のセキュリティ監視ツール）を使って、指定した git の参照地点以降に変更されたコード部分だけを素早くスキャンします。次のような場合に使用： - ユーザーが変更内容のスキャンを依頼したとき - 差分スキャン（変更部分のみを確認）を実行するよう指示されたとき - 変更コードのセキュリティ上の問題を確認したいとき - コミット前（コードを確定する前）のセキュリティチェック - プルリクエスト前（コード統合申請前）のセキュリティチェック - その他のコミット前・プッシュ前（サーバーへの送信前）のセキュリティ確認

原文を表示

Run a fast AWS Security Agent diff scan on only the changed code since a git ref. Use when the user asks to scan changes, run a diff scan, check what changed for security issues, scan before committing, scan before PR, or any pre-commit/pre-push security check.

ユースケース

変更内容のセキュリティスキャンを依頼されたとき
差分スキャン（変更部分のみ）を実行するとき
変更コードのセキュリティ問題を確認するとき
コミット前のセキュリティチェック
プルリクエスト前のセキュリティチェック

本文（日本語訳）

AWS Security Agent — 差分スキャン

変更されたコードのみをスキャンします。フルスキャンより高速で、差分箇所に絞った検出結果が得られます。事前のフルスキャンは不要です。

ローカル状態

.security-agent/config.json から agent_space_id と region を読み込みます。ファイルがない場合は、先に setup-security-agent ワークフローをインラインで実行してください。

スキャンの履歴は .security-agent/scans.json に記録します。

必要な値を特定する方法

プレースホルダ	特定方法
`<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>`
`<WORKSPACE_ID>`	`printf '%s' "$(pwd)" \| md5sum \| cut -c1-12`

ワークフロー

スキャン前の確認

フルスキャンと同じ方法で実行します。設定を読み込み、エージェント領域を確認し、値を特定し、ワークスペースIDを生成します。
スキャン対象を確認
- コミット前の変更 → BASE_REF=HEAD （初期値）
- ブランチとメインブランチの差分 → BASE_REF=main
- カスタム参照先 → ユーザーが指定

差分を生成（変更がない場合は即座に停止）

cd <absolute-workspace-path>
if [ "$BASE_REF" = "HEAD" ]; then
  git diff HEAD > /tmp/diff.patch
else
  git diff "$BASE_REF..HEAD" > /tmp/diff.patch
fi
[ -s /tmp/diff.patch ] || { echo "No changes vs $BASE_REF"; exit 1; }

ワークスペースを圧縮（フルスキャンと同じ除外設定、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 "*.pyc"

ソースZIPと差分ファイルをアップロード

SCAN_ID="diff-$(date +%s)-$(openssl rand -hex 3)"
aws s3 cp /tmp/source.zip s3://<bucket>/security-scans/source/<WORKSPACE_ID>/source.zip --expected-bucket-owner <account>
aws s3 cp /tmp/diff.patch s3://<bucket>/security-scans/diffs/${SCAN_ID}/diff.patch --expected-bucket-owner <account>

ワークスペースごとのコードレビュー（CodeReview）を取得または作成

フルスキャンと同じ方法で実行します。config.json → code_reviews[<abs_path>] を確認し、ない場合は新規作成します。
```
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}]
```

差分スキャンジョブを開始

aws securityagent start-code-review-job --agent-space-id <id> --code-review-id <cr-id> \
  --diff-source s3Uri=s3://<bucket>/security-scans/diffs/${SCAN_ID}/diff.patch

ResourceNotFoundException が発生した場合は、コードレビューを再作成して再試行します。

codeReviewJobId をキャプチャし、scans.json に scan_type: "DIFF" と base_ref とともに記録します。
ユーザーに通知「差分スキャンを開始しました。数分かかります。2分ごとに確認します。『stop polling』と指定すると確認を中止します。」
2分ごとにポーリング（状態確認）
```
aws securityagent batch-get-code-review-jobs --agent-space-id <id> --code-review-job-ids <job_id>
```
ステータスに変更があった場合のみ応答します。完了（COMPLETED）になったら検出結果を取得します。
検出結果

フルスキャンと同じ形式で表示します。重大度別にまとめ、結果を .security-agent/findings-{scan_id}.md に記録します。

ルール

差分スキャンはスタンドアロン（事前のフルスキャン不要）
ポーリングは2分ごと（それ以上頻繁にしない）
ユーザーが指定しない場合は BASE_REF=HEAD を初期値とする
タイトル形式：diff-<git-branch>-<timestamp> （スペースなし）
差分が空の場合はユーザーに通知して停止（スキャンを開始しない）

原文（English）を表示

AWS Security Agent — Diff Scan

Scan only the code that changed since a git ref. Faster than a full scan — focuses findings on the diff. No prior full scan needed.

Local state

Read .security-agent/config.json for agent_space_id and region. If missing, run the setup-security-agent workflow inline first.

Track scans in .security-agent/scans.json.

Resolving the values you need

Placeholder	How to resolve
`<id>` (agent space)	`config.agent_space_id`
`<region>`	`config.region` (default `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>`
`<WORKSPACE_ID>`	`printf '%s' "$(pwd)" \| md5sum \| cut -c1-12`

Workflow

Pre-scan checks. Same as full scan — read config, verify agent space, resolve values, generate workspace ID.
Ask what to scan against:
- Uncommitted changes → BASE_REF=HEAD (default)
- Branch vs main → BASE_REF=main
- Custom ref → user provides

Generate diff (fail fast if empty):

cd <absolute-workspace-path>
if [ "$BASE_REF" = "HEAD" ]; then
  git diff HEAD > /tmp/diff.patch
else
  git diff "$BASE_REF..HEAD" > /tmp/diff.patch
fi
[ -s /tmp/diff.patch ] || { echo "No changes vs $BASE_REF"; exit 1; }

Zip the workspace (same exclusions as full scan, 2 GB limit):

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 "*.pyc"

Upload both source zip and diff patch:

SCAN_ID="diff-$(date +%s)-$(openssl rand -hex 3)"
aws s3 cp /tmp/source.zip s3://<bucket>/security-scans/source/<WORKSPACE_ID>/source.zip --expected-bucket-owner <account>
aws s3 cp /tmp/diff.patch s3://<bucket>/security-scans/diffs/${SCAN_ID}/diff.patch --expected-bucket-owner <account>

Get or create per-workspace CodeReview (same logic as full scan — lookup config.json → code_reviews[<abs_path>], create if absent):

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}]

Start the diff job:

aws securityagent start-code-review-job --agent-space-id <id> --code-review-id <cr-id> \
  --diff-source s3Uri=s3://<bucket>/security-scans/diffs/${SCAN_ID}/diff.patch

If ResourceNotFoundException: recreate CodeReview and retry.

Capture codeReviewJobId. Persist to scans.json with scan_type: "DIFF" and base_ref.
Tell user: "Diff scan started. Takes a few minutes. I'll check every 2 minutes — say 'stop polling' to opt out."

Poll every 2 minutes:

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

Only respond when status changes. On COMPLETED → fetch findings.

Findings: same presentation as full scan — grouped by severity, report written to .security-agent/findings-{scan_id}.md.

Rules

Diff scans are standalone — no prior full scan needed
Poll every 2 minutes, not faster
Default to BASE_REF=HEAD if user doesn't specify
Title: diff-<git-branch>-<timestamp> (no spaces)
If diff is empty, tell user and stop — don't start a scan

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。