remediating-with-aws-security-agent

安全 Agent 整改

AWS Security Agent 是一个前沿 Agent，可按需对客户的应用进行渗透测试和代码审查，并报告经过验证的安全风险。本技能将带你从“我知道 AWS 某处有调查结果”走到“我正在修复其中最重要的问题”，同时避免将敏感的漏洞利用详情放入源代码管理。

整个流程分为四个阶段，顺序很重要：

1. 发现有哪些扫描，以及账户的配置情况（实时，只读）。
2. 导出调查结果到本地的 Git 忽略目录。
3. 分流调查结果，整理成优先级明确、易于理解的计划。
4. 整改，提出修复风险最高的问题。

为什么顺序和防护措施很重要

调查结果包含可用的攻击脚本、复现步骤、文件路径，有时还包括泄露的密钥或环境详情。如果这些内容进入 Git 仓库，客户可能会意外提交并公开针对自己生产系统的分步攻击指南。因此，必须遵守以下规则：调查结果只能写入 .security-agent/，而且在写入任何内容之前，必须先将该路径加入 Git 忽略列表。

阶段 1：发现扫描（实时，只读）

了解账户中有哪些内容。所有命令都是只读的 list-* 操作。

AWS Security Agent 按层级组织数据——逐层查看：

Application (account + Region)
└── Agent Space        (workspace for design review, code review, and pentests)
    ├── Penetration test → Pentest job → Findings
    └── Code review      → Code review job → Findings

运行以下命令，了解情况并向用户展示现有内容：

aws securityagent list-agent-spaces
aws securityagent list-pentests          --agent-space-id <as-...>
aws securityagent list-code-reviews      --agent-space-id <as-...>
aws securityagent list-pentest-jobs-for-pentest         --agent-space-id <as-...> --pentest-id <pt-...>
aws securityagent list-code-review-jobs-for-code-review --agent-space-id <as-...> --code-review-id <cr-...>

任务的 status 值为 IN_PROGRESS、STOPPING、STOPPED、FAILED 或 COMPLETED。只有 COMPLETED 任务才有稳定且完整的调查结果。

将代码库与扫描匹配，然后确认

Agent 空间、渗透测试和代码审查的名称都与其目标应用相关。在让用户从原始列表中选择之前，先根据现有信息判断哪个扫描与当前仓库对应——用户有理由在这个代码库中工作，而相关调查结果几乎总是针对眼前这个应用。

根据工作区中可靠且易于获取的信息，推断应用身份：

• 仓库／根目录名称和 Git 远程 URL（git remote -v）。
• 项目清单及其 name／description（package.json、pyproject.toml、*.csproj、go.mod、Cargo.toml）。
• README 标题、产品／方向文档，以及明显的产品或公司名称。
• 与扫描标题相符的特色框架或领域。

将这些信息与 Agent 空间／扫描名称进行比对（不区分大小写，并允许部分匹配和模糊匹配）。 然后务必在导出前确认——说明你的最佳判断及其依据，并让用户进行更正：

“这个仓库看起来对应 <product>（依据：<signal>），与 Agent 空间相符。使用该空间，还是选择其他空间？[其他 Agent 空间名称，...]”

如果没有足够可信的匹配结果，请明确说明，并显示完整列表，而不是强行给出错误判断。未经用户确认，切勿从推测的扫描中导出调查结果。

阶段 2：将调查结果导出到 .security-agent/（加入 Git 忽略列表）

使用 AWS CLI 命令获取调查结果。将所有内容写入仓库中的 .security-agent/，绝不写入聊天内容或标准输出，因为调查结果包含可用的攻击脚本、复现步骤，有时还包括泄露的密钥。

1. 在获取任何内容之前锁定输出目录

mkdir -p .security-agent
echo '*' > .security-agent/.gitignore

2. 确定最新的 COMPLETED 任务

你应该已在阶段 1 中获取 agentSpaceId 和渗透测试／代码审查 ID。 列出所选扫描的任务：

# Pentest jobs:
aws securityagent list-pentest-jobs-for-pentest \
  --agent-space-id <as-...> --pentest-id <pt-...>

# Code review jobs:
aws securityagent list-code-review-jobs-for-code-review \
  --agent-space-id <as-...> --code-review-id <cr-...>

通过在每次请求中传入上一次响应中的 --next-token 进行分页，直到该字段不存在。筛选任务摘要，保留 status == "COMPLETED" 的任务。如果没有已完成的任务，请停止并告知用户：“未找到已完成的任务。请等待任务完成，或检查任务状态。” 否则，选择 createdAt 时间戳最大的已完成任务。

3. 列出发现摘要并按置信度筛选

# Pentest findings:
aws securityagent list-findings \
  --agent-space-id <as-...> --pentest-job-id <pj-...>

# Code review findings:
aws securityagent list-findings \
  --agent-space-id <as-...> --code-review-job-id <cj-...>

持续使用 --next-token 翻页，直到没有更多结果。置信度由低到高依次为： FALSE_POSITIVE、UNCONFIRMED、LOW、MEDIUM、HIGH。 默认仅保留 HIGH 和 MEDIUM。 只有用户明确要求时才扩大范围。

4. 分批获取完整详情，每批 25 条

batch-get-findings 每次调用最多接受 25 个 ID。将筛选后的发现 ID 分成每组 25 个：

aws securityagent batch-get-findings \
  --agent-space-id <as-...> \
  --finding-ids <fid-1> <fid-2> ... <fid-25>

写入前，为每条返回的发现标注其来源（pentest 或 code-review），以便第 3 阶段的分类能区分它们。

5. 将发现写入 .security-agent/

按任务 ID 对发现分组。为每个任务，将完整的 Markdown 报告写入 .security-agent/findings_<jobId>.md，并包含 API 返回的所有字段（findingId、 name、description、riskLevel、riskType、confidence、status、codeLocations、remediationCode 及其他任何字段）。不得遗漏任何字段。

边缘情况

• 没有 Agent 空间、扫描或 COMPLETED 任务——停止操作并告知用户，不要重试。
• 凭据无效或服务不可用——使用 aws sts get-caller-identity 确认，并检查 Region（默认为 us-east-1；Security Agent 按区域部署）。
• 不要在聊天中粘贴发现内容，仅可提供简短标题和数量。详情应保存在已加入 gitignore 的文件中。

第 3 阶段：分类并制定优先级计划

按风险排序，因为修复时间有限，CRITICAL 级别的未认证 RCE 每次都应优先于 LOW 级别的信息性发现。读取 .security-agent/ 中导出的 findings_*.md 文件，并按确定性规则排序。

排序规则

按以下复合键升序排序（值越低越优先，即越紧急）：

1. 风险级别，顺序如下： CRITICAL（0）→ HIGH（1）→ MEDIUM（2）→ LOW（3）→ INFORMATIONAL（4）→ UNKNOWN / 缺失（5）。
2. 风险评分，从高到低。pentest 发现中的 riskScore 是数字字符串 （例如 "10.0"），code-review 发现中通常没有此字段——将缺失值视为最低可能评分，使其排在同一风险级别中有评分的发现之后。
3. 置信度，顺序如下： HIGH（0）→ MEDIUM（1）→ LOW（2）→ UNCONFIRMED（3）→ FALSE_POSITIVE（4）。

此外，统计所有发现的严重性数量摘要（例如 2 CRITICAL · 5 HIGH · 3 MEDIUM），用于报告标题。

提取代码位置

为每条发现生成一个简短的 location 字符串：

• 如果设置了 filePath，则原样使用。
• 否则，取 codeLocations[0]。从 filePath 中移除扫描器的沙箱前缀（即直到并包括该标记的所有内容），使路径相对于仓库；如果找不到该标记，则回退到基本文件名。若存在 lineStart，则追加 :<lineStart>。
• 如果两者都不可用（某些 pentest 发现通常如此），则留空，并在影响说明中描述受影响的端点或攻击链。

摘要格式

为用户撰写简洁摘要：

## Security Agent triage — <agent space name>

<N> findings exported (<P pentest, C code review>) · confidence: <levels> · severity: <counts>

### Priority order
1. [CRITICAL · score 10.0 · HIGH confidence] <finding name>
   - Type: <riskType> · Source: <pentest|code-review>
   - Where: <file:line or endpoint, if present>
   - Impact: <one-line plain-language summary>
2. [HIGH · ...] ...

### Recommended remediation order
<short rationale: which to fix first and why — e.g. "1 and 3 are both
unauthenticated RCE on internet-facing endpoints; fix those before the
stored-XSS issues.">

如果发现超过约 10 条，则详细展示优先级最高的 N 条，并在底部按严重性汇总其余发现的数量。

聊天中应避免的内容

完整的 description、reasoning 和 attackScript 保留在已加入 gitignore 的文件中——其中包含可用于实际利用的细节。聊天摘要中的影响说明每条限一行，并使用通俗语言。Code-review 发现通常带有 filePath/位置和 suggestedFix；请指出这些信息，因为它们可直接对应到仓库修改。Pentest 发现描述端点和攻击链；尽可能将其关联到对应代码。留意相互印证的发现（pentest 和 code-review 指向同一根本原因）——这是优先修复的重要依据。

Stage 4: 提供修复方案

呈现分诊结果后，主动提出开始修复，不要悄悄开始编辑代码。

询问用户类似这样的问题：“要我开始修复优先级最高的问题吗？我建议从 #1（）开始。”如果用户同意，按优先级从高到低处理：

1. 从被 git 忽略的导出文件中读取问题详情（位置、描述、建议的修复方案）。
2. 打开受影响的文件，并通过编辑器应用修复。
3. 每项修复报告一行：“已在 {filePath}:{lineStart} 修复 {name}。”

如果用户想处理多个问题，请逐个修复（或一次修复一组相关问题），以便每项变更都易于审查，并按照 Stage 3 中的优先级顺序进行。

备注和边缘情况

• 没有已完成的任务：扫描任务可能仍处于 IN_PROGRESS 状态。告知用户，并提议稍后重新检查，而不是导出未完成的任务。
• 重新运行：每次运行都会覆盖该任务 ID 对应的文件。可以安全删除此目录；其中仅包含导出的副本，不包含事实来源数据。
• 多个账户/区域：问题按区域划分。如果用户原本预期会有结果但没有，请确认该区域与 Security Agent 的配置区域一致。
• 数据处理：将导出的问题视为敏感信息。这些是针对用户自身系统验证过的漏洞利用副本。