scanning-with-aws-security-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AWS Security Agent — Code Scans

AWS Security Agent — 代码扫描

This skill handles full repository scans. Setup (agent space, role, bucket) is handled by the setup-security-agent
skill — if

.security-agent/config.json

is missing, the scan workflow auto-runs setup inline first.

本技能处理完整仓库扫描。配置（代理空间、角色、存储桶）由**

setup-security-agent

**技能负责——如果缺少

.security-agent/config.json

，扫描工作流会先自动内联运行配置流程。

Action mapping

动作映射

User intent	Workflow
Direct scan request ("scan my code", "find vulnerabilities")	Full Scan
Scan status check ("how's the scan", "progress")	Status workflow
View findings ("what did it find", "show results")	Findings workflow
List scans ("recent scans", "show my scans")	Read `.security-agent/scans.json`
Stop a scan	`aws securityagent stop-code-review-job`

用户意图	工作流
直接扫描请求（"扫描我的代码"、"查找漏洞"）	完整扫描
扫描状态查询（"扫描进度如何"、"进展情况"）	状态工作流
查看扫描结果（"找到了什么"、"展示结果"）	结果工作流
列出扫描记录（"最近的扫描"、"展示我的扫描记录"）	读取 `.security-agent/scans.json`
停止扫描	`aws securityagent stop-code-review-job`

Rules for proactive suggestions

主动建议规则

Always ask before running — never auto-trigger scans
Single-line suggestions, not multi-paragraph pitches
If the user declines, do not bring it up again in the same session

运行前务必询问——切勿自动触发扫描
建议使用单行表述，不要用多段落说明
如果用户拒绝，在同一会话中不要再提及

Local state

本地状态

Read

.security-agent/config.json

for

agent_space_id

and

region

. If

config.json

is missing, tell the user one line — "First scan in this workspace — running setup first." — and run the setup-security-agent
workflow inline (steps from that skill's SKILL.md) before continuing. First-time scans should "just work."

Track scans in

.security-agent/scans.json

(keep last 50 entries). The per-workspace CodeReview ID is stored in

config.json → code_reviews[<abs_path>]

so subsequent scans reuse the same CodeReview.

读取

.security-agent/config.json

获取

agent_space_id

和

region

。如果缺少

config.json

，只需告知用户一句话——"此工作区首次扫描——先运行配置流程。"——然后在继续之前内联运行**

setup-security-agent

**工作流（步骤来自该技能的SKILL.md）。首次扫描应"开箱即用"。

在

.security-agent/scans.json

中跟踪扫描记录（保留最近50条条目）。每个工作区的CodeReview ID存储在

config.json → code_reviews[<abs_path>]

中，以便后续扫描复用同一个CodeReview。

Resolving the values you need

解析所需值

The CLI examples below use placeholders. Resolve them at the start of every scan:

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` (cache for the rest of the turn)
`<role-arn>`	`arn:aws:iam::<account>:role/SecurityAgentScanRole`
`<bucket>`	`security-agent-scans-<account>-<region>`
`<cr-id>`	`code_review_id` from `config.json → code_reviews[<abs_path>]`
`<job_id>`	`codeReviewJobId` returned by `start-code-review-job`
`<WORKSPACE_ID>`	`printf '%s' "$(pwd)" \| md5sum \| cut -c1-12`

These are derived rather than stored in config so they can never drift out of sync with reality.

以下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`

这些值是推导得出而非存储在配置中，因此永远不会与实际情况脱节。

Pre-scan checks

扫描前检查

Read
config.json
. If missing → run the
```
setup-security-agent
```
workflow inline first, then continue.

Verify agent space still exists:

bash

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

If response shows it doesn't exist, clear

agent_space_id

from

config.json

and run

setup-security-agent

again.

Resolve account, role ARN, and bucket name from the table above.

Generate workspace ID:

bash

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

读取
config.json
。如果缺失→先内联运行
```
setup-security-agent
```
工作流，然后继续。

验证代理空间是否仍存在：

bash

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

如果响应显示空间不存在，清除

config.json

中的

agent_space_id

并重新运行

setup-security-agent

。

解析账户、角色ARN和存储桶名称（参考上方表格）。

生成工作区ID：

bash

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

Workflow: Full Scan (~45 min)

工作流：完整扫描（约45分钟）

For scanning only changed code, use the

diff-scanning-with-aws-security-agent

skill instead. For threat modeling specs, use

threat-modeling-with-aws-security-agent

Run pre-scan checks above.

Zip the workspace. Exclude common build/cache directories. Honor

.gitignore

. Bail if zip > 2 GB.

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

Upload to the per-workspace stable key (overwrites any prior upload):

bash

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

Get or create the per-workspace CodeReview. Look up

config.json → code_reviews[<abs_path>]

If present, use that
```
code_review_id
```
.

If absent, create:

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

Capture

codeReviewId

and persist to

config.json → code_reviews[<abs_path>]

Title default:
```
pre-cr-<git-branch>
```
(use
```
git rev-parse --abbrev-ref HEAD
```
). Replace any spaces with hyphens.

Start the job:

bash

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

If the response is
ResourceNotFoundException
: the CodeReview was deleted externally. Recreate it (step 4) and retry.

Capture

codeReviewJobId

. Generate a local

scan_id

scan-<8-hex>

. Append to

scans.json

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

Tell user: "Full scan started (scan_id: {id}). Takes ~45 minutes. I'll check every 5 minutes — say 'stop polling' to opt out."
Run the Polling Loop below with
```
sleep 300
```
between checks.

如果仅需扫描变更代码，请使用

diff-scanning-with-aws-security-agent

技能。如需威胁建模规范，请使用

threat-modeling-with-aws-security-agent

。

运行上述扫描前检查。

压缩工作区。排除常见构建/缓存目录。遵循

.gitignore

规则。如果压缩包超过2 GB则终止操作。

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

上传到每个工作区的稳定存储键（覆盖之前的上传内容）：

bash

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

获取或创建每个工作区的CodeReview。查找

config.json → code_reviews[<abs_path>]

。

如果存在，使用该
```
code_review_id
```
。

如果不存在，创建：

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

捕获

codeReviewId

并保存到

config.json → code_reviews[<abs_path>]

。

默认标题：
```
pre-cr-<git-branch>
```
（使用
```
git rev-parse --abbrev-ref HEAD
```
获取分支名）。将空格替换为连字符。

启动任务：

bash

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

如果响应为
ResourceNotFoundException
：CodeReview已被外部删除。重新创建它（步骤4）并重试。

捕获

codeReviewJobId

。生成类似

scan-<8-hex>

的本地

scan_id

。追加到

scans.json

：

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

告知用户："完整扫描已启动（scan_id: {id}）。耗时约45分钟。我会每5分钟检查一次——说'停止轮询'可退出。"
运行下方的轮询循环，每次检查间隔
```
sleep 300
```
。

Polling Loop

轮询循环

After starting a scan:

```
sleep 300
```
(5 minutes). Do not poll faster than this.

Call status:

bash

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

Compare
```
status
```
to last seen status. Only respond to the user when status CHANGES (e.g.,
```
IN_PROGRESS
```
→
```
COMPLETED
```
) or on terminal state (
```
COMPLETED
```
,
```
FAILED
```
,
```
STOPPED
```
).
Do not report "still in progress" multiple times — that's noise.
If user says "stop polling" or "check later" → stop the loop and tell them: "Say 'scan status' or 'show findings' anytime."
On
```
COMPLETED
```
→ run the Findings workflow.
On
```
FAILED
```
→ fetch the job's error info (
```
statusReason
```
if present), tell the user, write a brief failure note to
```
.security-agent/findings-{scan_id}.md
```
.

启动扫描后：

```
sleep 300
```
（5分钟）。不要超过此频率轮询。

调用状态查询：

bash

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

将当前
```
status
```
与上次记录的状态对比。仅当状态变化时（例如
```
IN_PROGRESS
```
→
```
COMPLETED
```
）或处于终端状态（
```
COMPLETED
```
、
```
FAILED
```
、
```
STOPPED
```
）时才向用户反馈。
不要多次报告"仍在进行中"——这属于冗余信息。
如果用户说"停止轮询"或"稍后再查"→停止循环并告知用户："随时说'扫描状态'或'展示结果'即可。"
状态为
```
COMPLETED
```
时→运行结果工作流。
状态为
```
FAILED
```
时→获取任务的错误信息（如果有
```
statusReason
```
），告知用户，并在
```
.security-agent/findings-{scan_id}.md
```
中写入简短的失败说明。

Workflow: Status check (ad-hoc)

工作流：状态查询（临时）

User says "scan status" / "how's the scan":

If user names a
```
scan_id
```
, use it. Otherwise use the most recent entry in
```
scans.json
```
.
Call
```
batch-get-code-review-jobs
```
once.
Update
```
scans.json
```
status field.
Report: status + elapsed time + current step (if any).

用户说"扫描状态" / "扫描进展如何"：

如果用户指定了
```
scan_id
```
，则使用该ID。否则使用
```
scans.json
```
中的最新条目。
调用一次
```
batch-get-code-review-jobs
```
。
更新
```
scans.json
```
中的状态字段。
反馈：状态 + 已耗时 + 当前步骤（如有）。

Workflow: Findings

工作流：结果查看

After a scan completes (or on user request):

扫描完成后（或用户请求时）：

1. Fetch findings (paginate)

1. 获取结果（分页）

bash

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

nextToken

is returned, call again with

--next-token <token>

until exhausted.

bash

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

如果返回

nextToken

，则使用

--next-token <token>

再次调用，直到获取全部结果。

2. Enrich with full details

2. 补充完整详情

bash

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

bash

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

3. Filter (optional)

3. 过滤（可选）

If the user asked for a minimum severity (e.g., "high and above"), filter to that level:

Severity order: CRITICAL > HIGH > MEDIUM > LOW > INFORMATIONAL.

如果用户要求最低严重级别（例如"高及以上"），则过滤到该级别：

严重级别顺序：CRITICAL > HIGH > MEDIUM > LOW > INFORMATIONAL。

4. Concise summary in chat

4. 聊天中的简洁摘要

Group by severity. File path + line for each:

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

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

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

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

按严重级别分组。每个结果显示文件路径 + 行号：

🟣 CRITICAL: {name}
   文件: {filePath}:{lineStart}
   {description}

🔴 HIGH: {name}
   文件: {filePath}:{lineStart}
   {description}

🟡 MEDIUM: {name}
   文件: {filePath}:{lineStart}
   {description}

🟢 LOW: {name}
   文件: {filePath}:{lineStart}
   {description}

5. Detailed report file

5. 详细报告文件

Write to

.security-agent/findings-{scan_id}.md

. Include EVERY field returned (findingId, name, description, riskLevel, riskType, confidence, status, codeLocations with filePath/lineStart/lineEnd, and remediationCode if present).

markdown

undefined

写入

.security-agent/findings-{scan_id}.md

。包含返回的所有字段（findingId、name、description、riskLevel、riskType、confidence、status、带filePath/lineStart/lineEnd的codeLocations，以及如果存在的remediationCode）。

markdown

undefined

Security Scan Report — {scan_id}

安全扫描报告 — {scan_id}

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

扫描类型: FULL 标题: {title} 启动时间: {started_at} 总结果数: {count}

Summary

摘要

Severity	Count
CRITICAL	N
HIGH	N
MEDIUM	N
LOW	N

严重级别	数量
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)


Tell user: "Full details written to `.security-agent/findings-{scan_id}.md`"

ID: {findingId}
风险类型: {riskType}
置信度: {confidence}
状态: {status}
位置:
```
{filePath}:{lineStart}-{lineEnd}
```

描述: {description}

修复方案: {remediationCode或描述中的修复指引}

（每个结果重复上述格式）


告知用户："完整详情已写入`.security-agent/findings-{scan_id}.md`"

6. Follow-ups

6. 后续操作询问

Ask:

"Would you like to focus on the critical/high findings first?"
"Should I explain any of these in more detail?"
"Want me to fix these issues?"

For fixes: read the finding's description and code location, then synthesize and apply the fix via the Edit tool.

询问：

"是否要优先处理严重/高风险的扫描结果？"
"需要我详细解释其中任何一项吗？"
"需要我修复这些问题吗？"

修复操作：读取扫描结果的描述和代码位置，然后通过编辑工具合成并应用修复方案。

Workflow: Stop a scan

工作流：停止扫描

User says "stop the scan":

bash

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

Update

scans.json

status to

STOPPED

用户说"停止扫描"：

bash

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

更新

scans.json

中的状态为

STOPPED

。

Workflow: List recent scans

工作流：列出最近扫描记录

User asks "show my recent scans" / "list scans":

Read

.security-agent/scans.json

. Show in a compact table:

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

用户询问"展示我最近的扫描记录" / "列出扫描记录"：

读取

.security-agent/scans.json

。以紧凑表格形式展示：

scan_id	类型	标题	状态	启动时间
scan-abc	FULL	pre-cr-main	COMPLETED	2小时前
scan-def	FULL	pre-cr-feature-x	FAILED	1天前

Rules

规则

Always run pre-scan checks (config exists + agent space verified) before any scan
Scan APIs return immediately — poll status every 5 minutes
Use the most recent scan in
```
scans.json
```
if the user doesn't name one
Title must not contain spaces — use hyphens. Default to git branch name.
Don't dump raw JSON — format with severity icons + file locations

ResourceNotFoundException

from

start-code-review-job

, recreate the CodeReview and retry once

任何扫描前务必运行扫描前检查（配置存在 + 代理空间已验证）
扫描API会立即返回结果——每5分钟轮询一次状态
如果用户未指定扫描ID，使用
```
scans.json
```
中的最新扫描记录
标题不得包含空格——使用连字符。默认使用Git分支名。
不要输出原始JSON——使用严重级别图标 + 文件位置进行格式化
如果
```
start-code-review-job
```
返回
```
ResourceNotFoundException
```
，重新创建CodeReview并重试一次

Troubleshooting

故障排除

"Not configured" /
config.json
missing → run
```
setup-security-agent
```
skill first
AccessDenied
on
s3 cp
→ bucket not registered on agent space, or trust policy wrong. Re-run setup.
ResourceNotFoundException
on agent space → it was deleted. Re-run setup.
Scan stuck in PREFLIGHT for >10 min → backend issue, not client. Show
```
batch-get-code-review-jobs
```
output and tell user to escalate.
Code too large (zip > 2 GB) → run on a subdirectory instead.

"未配置" / 缺失
config.json
→ 先运行
```
setup-security-agent
```
技能
s3 cp
时出现
AccessDenied
→ 存储桶未在代理空间注册，或信任策略错误。重新运行配置流程。
代理空间出现
ResourceNotFoundException
→ 空间已被删除。重新运行配置流程。
扫描在PREFLIGHT状态停留超过10分钟 → 后端问题，非客户端问题。展示
```
batch-get-code-review-jobs
```
的输出并告知用户升级处理。
代码过大（压缩包>2 GB） → 改为在子目录运行扫描。