Back to Details

remediating-with-aws-security-agent

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Security Agent Remediation

Security Agent 漏洞修复

AWS Security Agent is a frontier agent that runs on-demand penetration tests and code reviews against a customer's applications and reports verified security risks. This skill takes you from "I have findings somewhere in AWS" to "I'm actively fixing the most important ones," while keeping the sensitive exploit detail out of source control.
The flow has four stages, and they matter in order:
  1. Discover which scans exist and how the account is configured (live, read-only).
  2. Export the findings to a local gitignored directory.
  3. Triage the findings into a prioritized, human-readable plan.
  4. Remediate by offering to fix the highest-risk issues.
AWS Security Agent是一款前沿代理工具，可针对客户应用按需运行渗透测试和代码审查，并报告已验证的安全风险。本技能可帮助您从“我的AWS账户中有检测结果”过渡到“我正在积极修复最重要的问题”，同时确保敏感漏洞细节不会进入源代码控制。
流程分为四个阶段，顺序至关重要：
  1. 发现：确认存在哪些扫描任务以及账户配置情况（实时、只读操作）。
  2. 导出：将检测结果导出至本地Git忽略目录。
  3. 梳理：将检测结果整理为优先级明确、易于阅读的修复计划。
  4. 修复：提供修复最高风险问题的选项。

Why the ordering and the guardrails matter

为何顺序和防护措施至关重要

Findings contain working attack scripts, reproduction steps, file paths, and sometimes leaked secrets or environment details. If that lands in a Git repo, a customer can accidentally commit and publish a step-by-step exploit for their own production system. So the non-negotiable rule is: findings are written only to 
.security-agent/
, and that path is gitignored before anything is written.
检测结果包含可运行的攻击脚本、复现步骤、文件路径，有时还包含泄露的密钥或环境细节。如果这些内容进入Git仓库，客户可能会意外提交并发布针对自身生产系统的分步漏洞利用方法。因此，不可违背的规则是：检测结果仅写入
.security-agent/
目录，且在写入任何内容前，该路径已被Git忽略。

Stage 1: Discover scans (live, read-only)

阶段1：发现扫描任务（实时、只读）

Find out what the account has. All commands are read-only 
list-*
operations.
AWS Security Agent organizes data as a hierarchy — work down it:
Application (account + Region)
└── Agent Space        (workspace for design review, code review, and pentests)
    ├── Penetration test → Pentest job → Findings
    └── Code review      → Code review job → Findings
Run these to orient yourself and show the user what exists:
bash
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-...>
Job 
status
is one of 
IN_PROGRESS
, 
STOPPING
, 
STOPPED
, 
FAILED
, 
COMPLETED
. Only 
COMPLETED
jobs have a stable, full set of findings.
了解账户中的扫描任务情况。所有命令均为只读的
list-*
操作。
AWS Security Agent采用层级结构组织数据——逐层向下查看：
Application (账户 + 区域)
└── Agent Space        (用于设计审查、代码审查和渗透测试的工作区)
    ├── Penetration test → Pentest job → Findings
    └── Code review      → Code review job → Findings
运行以下命令来熟悉情况并向用户展示现有内容：
bash
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
状态的任务才有完整、稳定的检测结果。

Match the codebase to a scan, then confirm

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

Agent spaces, pentests, and code reviews are named after the application they target. Before asking the user to pick from a raw list, make an informed guess about which scan corresponds to this repository — the user is working in a codebase for a reason, and the relevant findings are almost always for the app in front of them.
Infer the app identity from the workspace using cheap, high-signal sources:
  • The repository / root directory name and the Git remote URL (
    git remote -v
    ).
  • Project manifests and their 
    name
    /
    description
    (
    package.json
    , 
    pyproject.toml
    , 
    *.csproj
    , 
    go.mod
    , 
    Cargo.toml
    ).
  • README titles, product/steering docs, and any obvious product or company name.
  • Distinctive frameworks or domains that match a scan title.
Compare those signals against the agent space / scan names (case-insensitive, allow partial and fuzzy matches). Then always confirm before exporting — present your best guess and your reasoning, and let the user correct it:
"This repo looks like 
<product>
 (from 
<signal>
), which matches the <name> agent space. Use that, or pick another? [Other Agent Space names, ...]"
If nothing matches with reasonable confidence, say so plainly and show the full list rather than forcing a wrong guess. Never export from a guessed scan without the user's confirmation.
Agent Space、渗透测试和代码审查均以其目标应用命名。在让用户从原始列表中选择之前，先合理猜测哪个扫描任务对应当前代码库——用户正在某个代码库中工作，相关检测结果几乎总是针对眼前的应用。
通过低成本、高信号的来源从工作区推断应用标识：
  • 仓库/根目录名称和Git远程URL（
    git remote -v
    ）。
  • 项目清单及其
    name
    /
    description
    字段（
    package.json
    、
    pyproject.toml
    、
    *.csproj
    、
    go.mod
    、
    Cargo.toml
    ）。
  • README标题、产品/指导文档，以及任何明显的产品或公司名称。
  • 与扫描任务标题匹配的独特框架或域名。
将这些信号与Agent Space/扫描任务名称进行比较（不区分大小写，允许部分匹配和模糊匹配）。 然后导出前务必确认——展示您的最佳猜测及推理依据，让用户进行修正：
"此仓库看起来是**
<product>
（来自
<signal>
），与<name>** Agent Space匹配。是否使用该任务，还是选择其他？[其他Agent Space名称，...]"
如果没有合理置信度的匹配项，请直接告知用户并展示完整列表，而非强行做出错误猜测。未经用户确认，绝不能从猜测的扫描任务中导出结果。

Stage 2: Export findings to 
.security-agent/
(gitignored)

阶段2：将检测结果导出至
.security-agent/
（Git忽略目录）

Pull findings using AWS CLI commands. Write everything into 
.security-agent/
in the repo — never to chat or stdout — because findings include working attack scripts, reproduction steps, and sometimes leaked secrets.
使用AWS CLI命令拉取检测结果。将所有内容写入仓库中的
.security-agent/
目录——绝不能写入聊天窗口或标准输出——因为检测结果包含可运行的攻击脚本、复现步骤，有时还包含泄露的密钥。

1. Lock down the output directory before pulling anything

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

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

2. Resolve the latest COMPLETED job

2. 确定最新的COMPLETED状态任务

You should already have the 
agentSpaceId
and the pentest/code-review id from Stage 1. List jobs for the chosen scan:
bash
undefined
您应该已从阶段1获取了
agentSpaceId
和渗透测试/代码审查ID。列出所选扫描任务的所有任务：
bash
undefined

Pentest jobs:

渗透测试任务：

aws securityagent list-pentest-jobs-for-pentest
--agent-space-id <as-...> --pentest-id <pt-...>
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-...>

Paginate by passing `--next-token` from the previous response until absent. Filter the
job summaries to `status == "COMPLETED"`. If none are COMPLETED, stop and tell the user
"No completed jobs found. Please wait for a job to complete or check job statuses."
Otherwise, pick the COMPLETED job with the greatest `createdAt` timestamp.
aws securityagent list-code-review-jobs-for-code-review
--agent-space-id <as-...> --code-review-id <cr-...>

通过传递前一次响应中的`--next-token`进行分页，直到没有该参数为止。筛选出`status == "COMPLETED"`的任务摘要。如果没有COMPLETED状态的任务，请停止操作并告知用户“未找到已完成的任务。请等待任务完成或检查任务状态。”否则，选择`createdAt`时间戳最新的COMPLETED状态任务。

3. List finding summaries and filter by confidence

3. 列出检测结果摘要并按置信度筛选

bash
undefined
bash
undefined

Pentest findings:

渗透测试检测结果：

aws securityagent list-findings
--agent-space-id <as-...> --pentest-job-id <pj-...>
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-...>

Paginate on `--next-token` until exhausted. Confidence values from weakest to strongest:
`FALSE_POSITIVE`, `UNCONFIRMED`, `LOW`, `MEDIUM`, `HIGH`.
**Keep only `HIGH` and `MEDIUM` by default.** Widen only when the user explicitly asks.
aws securityagent list-findings
--agent-space-id <as-...> --code-review-job-id <cj-...>

使用`--next-token`分页直到所有结果都获取完毕。置信度从弱到强依次为：`FALSE_POSITIVE`、`UNCONFIRMED`、`LOW`、`MEDIUM`、`HIGH`。
**默认仅保留`HIGH`和`MEDIUM`置信度的结果**。仅当用户明确要求时才扩大筛选范围。

4. Fetch full detail in batches of 25

4. 批量获取完整详情（每次最多25条）

batch-get-findings
accepts at most 25 ids per call. Chunk the filtered finding ids into groups of 25:
bash
aws securityagent batch-get-findings \
  --agent-space-id <as-...> \
  --finding-ids <fid-1> <fid-2> ... <fid-25>
Tag each returned finding with its source (
pentest
or 
code-review
) before writing, so triage in Stage 3 can tell them apart.
batch-get-findings
每次调用最多接受25个ID。将筛选后的检测结果ID分成每组25个的批次：
bash
aws securityagent batch-get-findings \
  --agent-space-id <as-...> \
  --finding-ids <fid-1> <fid-2> ... <fid-25>
在写入之前，为每个返回的检测结果标记其来源（
pentest
或
code-review
），以便阶段3的梳理工作能够区分它们。

5. Write findings into 
.security-agent/

5. 将检测结果写入
.security-agent/
目录

Group findings by job id. For each job, write a full markdown report to 
.security-agent/findings_<jobId>.md
with ALL fields returned by the API (findingId, name, description, riskLevel, riskType, confidence, status, codeLocations, remediationCode, and any other fields). Do not leave off any fields.
按任务ID对检测结果进行分组。对于每个任务，将完整的Markdown报告写入
.security-agent/findings_<jobId>.md
，包含API返回的所有字段（findingId、name、description、riskLevel、riskType、confidence、status、codeLocations、remediationCode以及其他任何字段）。请勿遗漏任何字段。

Edge cases

边缘情况

  • No agent space, scan, or COMPLETED job — stop and surface that to the user rather than retrying.
  • Credentials or service unavailable — confirm with 
    aws sts get-caller-identity
    and check the Region (default 
    us-east-1
    ; Security Agent is regional).
  • Don't paste finding contents into chat beyond short titles and counts. The detail belongs in the gitignored files.
  • 无Agent Space、扫描任务或COMPLETED状态任务——停止操作并告知用户，而非重试。
  • 凭证或服务不可用——使用
    aws sts get-caller-identity
    确认凭证，并检查区域（默认
    us-east-1
    ；Security Agent是区域性服务）。
  • 请勿在聊天窗口中粘贴检测结果内容，除了简短标题和数量。详细内容应保存在Git忽略的文件中。

Stage 3: Triage into a prioritized plan

阶段3：梳理为优先级明确的修复计划

Rank by risk, because remediation time is finite and a CRITICAL unauthenticated RCE outranks a LOW informational finding every time. Read the exported 
findings_*.md
files from 
.security-agent/
and sort them deterministically.
按风险等级排序，因为修复时间有限，未认证的CRITICAL级远程代码执行漏洞的优先级始终高于LOW级信息性检测结果。读取
.security-agent/
目录中导出的
findings_*.md
文件，并进行确定性排序。

Ranking rules

排序规则

Sort ascending by this composite key (lower wins, i.e. more urgent first):
  1. Risk level, in this order: 
    CRITICAL
    (0) → 
    HIGH
    (1) → 
    MEDIUM
    (2) → 
    LOW
    (3) → 
    INFORMATIONAL
    (4) → 
    UNKNOWN
    / missing (5).
  2. Risk score, highest first. 
    riskScore
    is a numeric string on pentest findings (e.g. 
    "10.0"
    ), often absent on code-review findings — treat missing as the lowest possible score so it sorts after scored findings of the same level.
  3. Confidence, in this order: 
    HIGH
    (0) → 
    MEDIUM
    (1) → 
    LOW
    (2) → 
    UNCONFIRMED
    (3) → 
    FALSE_POSITIVE
    (4).
Also compute a severity-count summary across all findings (e.g. 
2 CRITICAL · 5 HIGH · 3 MEDIUM
) for the header of the report.
按以下复合键升序排序（数值越小，优先级越高，即越紧急）：
  1. 风险等级，顺序如下： 
    CRITICAL
    (0) → 
    HIGH
    (1) → 
    MEDIUM
    (2) → 
    LOW
    (3) → 
    INFORMATIONAL
    (4) → 
    UNKNOWN
    / 缺失 (5)。
  2. 风险分数，分数越高优先级越高。
    riskScore
    是渗透测试检测结果中的数字字符串（例如
    "10.0"
    ），代码审查检测结果中通常不存在——将缺失的风险分数视为最低可能分数，使其在相同风险等级的有分数检测结果之后排序。
  3. 置信度，顺序如下： 
    HIGH
    (0) → 
    MEDIUM
    (1) → 
    LOW
    (2) → 
    UNCONFIRMED
    (3) → 
    FALSE_POSITIVE
    (4)。
同时计算所有检测结果的严重程度计数摘要（例如
2 CRITICAL · 5 HIGH · 3 MEDIUM
），作为报告的标题部分。

Pulling the code location

提取代码位置

For each finding, derive a single short 
location
string:
  • If 
    filePath
    is set, use it as-is.
  • Otherwise, take 
    codeLocations[0]
    . Strip the scanner's sandbox prefix from 
    filePath
    (everything up to and including that marker) so the path is repo-relative; if that marker isn't present, fall back to the basename. Append 
    :<lineStart>
    when present.
  • If neither is available (typical for some pentest findings), leave it blank and describe the affected endpoint or attack chain in the impact line instead.
为每个检测结果生成一个简短的
location
字符串：
  • 如果设置了
    filePath
    ，直接使用该路径。
  • 否则，取
    codeLocations[0]
    。从
    filePath
    中去除扫描器沙箱前缀（直到并包括该标记的所有内容），使路径变为仓库相对路径；如果该标记不存在，则回退到文件名。当存在
    lineStart
    时，追加
    :<lineStart>
    。
  • 如果两者都不可用（某些渗透测试检测结果通常如此），则留空，并在影响行中描述受影响的端点或攻击链。

Summary format

摘要格式

Write a compact summary for the user:
undefined
为用户编写简洁的摘要：
undefined

Security Agent triage — <agent space name>

Security Agent 风险梳理 — <agent space name>

<N> findings exported (<P pentest, C code review>) · confidence: <levels> · severity: <counts>
共导出<N>条检测结果（<P>条渗透测试，<C>条代码审查）· 置信度：<levels> · 严重程度：<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 · ...] ...
  1. [CRITICAL · 分数10.0 · HIGH置信度] <检测结果名称>
    • 类型：<riskType> · 来源：<pentest|code-review>
    • 位置：<文件:行号 或 端点（如果存在）>
    • 影响：<单行通俗易懂的摘要>
  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.">

If more than ~10 findings, show the top N in detail and summarize the rest as a count
by severity at the bottom.
<简短理由：先修复哪些问题及原因——例如“1和3都是面向互联网端点的未认证远程代码执行漏洞；应在存储型XSS问题之前修复这些漏洞。”>

如果检测结果超过约10条，则详细展示前N条，其余部分按严重程度计数汇总在底部。

What to keep out of chat

聊天窗口中应避免的内容

The full 
description
, 
reasoning
, and 
attackScript
stay in the gitignored files — they contain working exploit detail. In the chat summary keep impact lines to one line each, in plain language. Code-review findings usually carry a 
filePath
/location and a 
suggestedFix
; call those out since they map directly to repo changes. Pentest findings describe endpoints and attack chains; map them to the responsible code where you can. Look for findings that corroborate each other (a pentest and a code review flagging the same root cause) — those are strong signals for what to fix first.
完整的
description
、
reasoning
和
attackScript
应保留在Git忽略的文件中——它们包含可运行的漏洞利用细节。在聊天摘要中，每条影响描述应限制为单行，使用通俗易懂的语言。代码审查检测结果通常包含
filePath
/位置和
suggestedFix
；应突出显示这些内容，因为它们直接对应仓库中的变更。渗透测试检测结果描述端点和攻击链；尽可能将它们映射到负责的代码。寻找相互印证的检测结果（渗透测试和代码审查都标记了相同的根本原因）——这些是优先修复的强烈信号。

Stage 4: Offer to remediate

阶段4：提供修复选项

After presenting the triage, offer to start fixing — don't silently begin editing code.
Ask the user something like: "Want me to start fixing the top finding(s)? I'd recommend starting with #1 (<name>)." If they agree, work top-down by priority:
  1. Read the finding detail from the gitignored export file (location, description, suggested fix).
  2. Open the affected file and apply the fix via the editor.
  3. Report one line per fix: "Fixed {name} in 
    {filePath}:{lineStart}
    ."
If the user wants to handle several findings, fix one at a time (or one cluster of related findings) so each change stays reviewable, and proceed in the priority order from Stage 3.
展示梳理结果后，提供开始修复的选项——不要静默开始编辑代码。
向用户询问类似内容：“是否要我开始修复排名靠前的检测结果？我建议从第1条（<名称>）开始。”如果用户同意，则按阶段3的优先级从上到下处理：
  1. 从Git忽略的导出文件中读取检测结果详情（位置、描述、建议修复方案）。
  2. 打开受影响的文件并通过编辑器应用修复。
  3. 每条修复报告一行：“已修复{name}于
    {filePath}:{lineStart}
    。”
如果用户想要处理多个检测结果，请一次修复一个（或一组相关的检测结果），以便每次变更都易于审查，并按照阶段3的优先级顺序进行。

Notes and edge cases

注意事项和边缘情况

  • No completed jobs: a scan may still be 
    IN_PROGRESS
    . Tell the user; offer to re-check later rather than exporting a partial job.
  • Re-running: each run overwrites the files for that job id. The directory is safe to delete; it only holds exported copies, not source-of-truth data.
  • Multiple accounts/Regions: findings are Region-scoped. If the user expected results and got none, confirm the region matches where Security Agent is configured.
  • Data handling: treat exported findings as sensitive. They are copies of verified exploits against the user's own systems.
  • 无已完成任务：扫描任务可能仍处于
    IN_PROGRESS
    状态。告知用户；稍后再重新检查，而非导出不完整的任务结果。
  • 重新运行：每次运行都会覆盖对应任务ID的文件。该目录可以安全删除；它仅保存导出的副本，而非真实数据源。
  • 多账户/区域：检测结果是区域范围的。如果用户预期有结果但未获取到，请确认区域与Security Agent配置的区域一致。
  • 数据处理：将导出的检测结果视为敏感数据。它们是针对用户自身系统的已验证漏洞利用副本。