diff-scanning-with-aws-security-agent

AWS Security Agent — 差分スキャン

git の参照以降に変更されたコードのみをスキャンします。フルスキャンより高速で、差分に対象を絞って検出結果を提示します。事前にフルスキャンを実行する必要はありません。

ローカル状態

.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

---

ワークフロー

1. スキャン前の確認。 フルスキャンと同様に、設定を読み取り、エージェントスペースを検証し、値を解決して、ワークスペース ID を生成します。

2. 何を基準にスキャンするかを確認します。

   • 未コミットの変更 → BASE_REF=HEAD（デフォルト）
   • ブランチと main の比較 → BASE_REF=main
   • カスタム参照 → ユーザーが指定

3. 差分を生成します（空の場合は即座に終了）：

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

4. ワークスペースを 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 "*.pyc"
   

5. ソース 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>
   

6. ワークスペースごとの 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}]
   

7. 差分ジョブを開始します：

   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 が発生した場合は、CodeReview を再作成して再試行します。

8. codeReviewJobId を取得します。scan_type: "DIFF" と base_ref を付けて、scans.json に保存します。

9. ユーザーに伝えます：「差分スキャンを開始しました。完了まで数分かかります。2 分ごとに確認します。停止する場合は「stop polling」と入力してください。」

10. 2 分ごとにポーリングします：

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

    ステータスが変化した場合にのみ応答します。COMPLETED になったら、検出結果を取得します。

11. 検出結果： フルスキャンと同じ形式で、重大度ごとにまとめます。レポートは .security-agent/findings-{scan_id}.md に書き込みます。

---

ルール

• 差分スキャンは単独で実行でき、事前にフルスキャンを行う必要はありません
• ポーリングは 2 分ごとに行い、それより短い間隔では行いません
• ユーザーが指定しない場合は、デフォルトで BASE_REF=HEAD にします
• タイトル：diff-<git-branch>-<timestamp>（スペースなし）
• 差分が空の場合はユーザーに伝えて終了し、スキャンを開始しません