scanning-with-aws-security-agent

AWS Security Agent — 代码扫描

此技能用于扫描整个代码仓库。设置（Agent 空间、角色、存储桶）由 setup-security-agent 技能负责——如果缺少 .security-agent/config.json，扫描工作流会先自动内联运行设置流程。

---

操作映射

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

主动建议规则

• 运行前务必先征求同意——绝不自动触发扫描
• 建议控制在单行，不要写成多段推销文案
• 如果用户拒绝，在同一会话中不要再提起

---

本地状态

读取 .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。

解析所需值

下面的 CLI 示例使用占位符。每次扫描开始时都要解析这些占位符：

占位符	解析方式
<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>
<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. 确认 Agent 空间仍然存在：

   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. 压缩工作区。 排除常见的构建／缓存目录。遵循 .gitignore。如果压缩包大于 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_id，例如 scan-<8-hex>。追加到 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 分钟检查一次——回复‘停止轮询’即可退出。”

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. 如果用户说“停止轮询”或“稍后再检查” → 停止循环，并告知他们：“随时回复‘扫描状态’或‘显示发现项’。”

6. 如果状态为 COMPLETED → 执行发现项工作流。

7. 如果状态为 FAILED → 获取任务的错误信息（如果存在 statusReason，则获取该字段），告知用户，并将简要失败说明写入 .security-agent/findings-{scan_id}.md。

---

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

用户说“扫描状态”／“扫描进展如何”时：

1. 如果用户指定了 scan_id，则使用该 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. 筛选（可选）

如果用户要求最低严重级别（例如“高及以上”），则筛选到该级别：

• 严重级别顺序：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. 后续跟进

询问：

• “您想先处理严重／高危发现项吗？”
• “需要我详细解释其中任何一项吗？”
• “要我修复这些问题吗？”

修复时：阅读发现项的描述和代码位置，然后综合判断并通过 Edit 工具应用修复。

---

工作流：停止扫描

用户说“停止扫描”时：

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

---

规则

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

---

故障排查

• “未配置”／缺少 config.json → 先运行 setup-security-agent 技能
• 执行 s3 cp 时出现 AccessDenied → 存储桶未在 Agent 空间注册，或信任策略有误。重新运行设置。
• 执行 s3 cp 时出现 403／ExpectedBucketOwner 不匹配 → 派生的存储桶归其他账户所有（存储桶抢注）。上传会按设计被拒绝 — 未启用防护时不要重试。重新运行 setup-security-agent，该命令会在存储桶归其他账户所有时中止。
• Agent 空间出现 ResourceNotFoundException → Agent 空间已被删除。重新运行设置。
• 扫描在 PREFLIGHT 阶段卡住超过 10 分钟 → 这是后端问题，不是客户端问题。显示 batch-get-code-review-jobs 的输出，并告知用户升级处理。
• 代码过大（zip > 2 GB） → 改为在子目录上运行。