diff-scanning-with-aws-security-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AWS Security Agent — Diff Scan

AWS Security Agent — 差异扫描

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.

仅扫描自git ref以来变更的代码。比全量扫描更快——将检测结果聚焦于差异部分。无需预先进行全量扫描。

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

读取

.security-agent/config.json

中的

agent_space_id

和

region

。如果缺失，请先内联运行

setup-security-agent

工作流。

在

.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`

占位符	获取方式
`<id>` （agent空间）	`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`

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):

bash

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):

bash

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:

bash

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

Get or create per-workspace CodeReview (same logic as full scan — lookup

config.json → code_reviews[<abs_path>]

, create if absent):

bash

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:

bash

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

: 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:

bash

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
```
.

扫描前检查。与全量扫描相同——读取配置、验证agent空间、解析值、生成工作区ID。
询问扫描基准：
- 未提交的变更 →
```
BASE_REF=HEAD
```
  （默认值）
- 分支与主分支对比 →
```
BASE_REF=main
```
- 自定义基准 → 由用户提供

生成差异（无变更则快速失败）：

bash

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

压缩工作区（与全量扫描排除相同路径，限制2GB）：

bash

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"

上传源码压缩包和差异补丁：

bash

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

获取或创建工作区专属CodeReview（与全量扫描逻辑相同——查找

config.json → code_reviews[<abs_path>]

，不存在则创建）：

bash

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

启动差异扫描任务：

bash

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并重试。

记录

codeReviewJobId

。将其与

scan_type: "DIFF"

和

base_ref

一起保存到

scans.json

中。

告知用户：“差异扫描已启动。需耗时数分钟。我会每2分钟检查一次——输入‘停止轮询’即可退出。”
轮询：每2分钟执行一次：
bash
```
aws securityagent batch-get-code-review-jobs --agent-space-id <id> --code-review-job-ids <job_id>
```
仅在状态变更时反馈。扫描完成（COMPLETED）后→获取检测结果。
检测结果：与全量扫描展示方式相同——按严重程度分组，报告写入
```
.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

差异扫描可独立运行——无需预先进行全量扫描
每2分钟轮询一次，不可更频繁
如果用户未指定，默认
```
BASE_REF=HEAD
```
标题格式：
```
diff-<git-branch>-<timestamp>
```
（无空格）
如果无差异，告知用户并终止流程——不启动扫描