pentesting-with-aws-security-agent

AWS Security Agent — 渗透测试

此技能负责渗透测试的设置、执行和发现结果。初始 Security Agent 设置（Agent 空间、角色、存储桶）由 setup-security-agent 技能负责——如果缺少 .security-agent/config.json，渗透测试工作流会先自动内联运行设置流程。

渗透测试耗时较长（1-24 小时），且会主动探测实际运行的应用。开始前，务必确认用户已获授权测试目标。

---

解析所需的值

以下 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
<td-id>	create-target-domain 返回的 targetDomainId（缓存到 config.target_domains[<domain>]）
<pentest-id>	create-pentest 返回的 pentestId
<pj-id>	start-pentest-job 返回的 pentestJobId

渗透测试前检查

1. 读取 .security-agent/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. 授权检查： 如果上下文中无法明确判断，询问用户：“你是否拥有对 <target> 进行渗透测试的权限，或已获得明确授权？”未得到确认前不得继续。

---

工作流

1. 注册目标域名（每个域名仅需一次）

aws securityagent create-target-domain --agent-space-id <id> \
  --target-domain-name <domain> --verification-method HTTP_ROUTE

响应中会包含验证令牌或路由。告知用户需要在服务器上添加什么（通常是返回令牌的 .well-known/... 文件或 HTTP 路由），然后：

aws securityagent verify-target-domain --agent-space-id <id> --target-domain-id <td-id>

将已验证的 target_domain_id 保存到 .security-agent/config.json 的 target_domains: { "<domain>": "<td-id>" } 下，以便后续渗透测试复用。

2. 创建渗透测试

向用户询问：

• 标题（不能有空格——使用连字符；默认值为 pentest-<timestamp>）
• 要测试的端点（已验证域名下的一个或多个 URI）

aws securityagent create-pentest --agent-space-id <id> --title <title> \
  --service-role <role-arn> \
  --assets endpoints=[{uri=https://example.com/api/login},{uri=https://example.com/api/upload}]

记录 pentestId。

3. 启动渗透测试任务

aws securityagent start-pentest-job --agent-space-id <id> --pentest-id <pentest-id>

记录 pentestJobId。将以下内容追加到 .security-agent/pentests.json（如果文件不存在，则创建为 []——设置流程已创建该目录）：

{
  "pentest_id": "p-...",
  "pentest_job_id": "pj-...",
  "agent_space_id": "as-...",
  "title": "pentest-...",
  "endpoints": ["https://..."],
  "started_at": "2026-06-01T20:00:00Z",
  "status": "IN_PROGRESS"
}

告知用户：“渗透测试已启动（{pentest_job_id}）。根据测试范围，通常需要 1-24 小时。我会每 15 分钟检查一次——发送‘停止轮询’即可退出。”

4. 轮询循环

1. 每次检查之间执行 sleep 900（15 分钟）。不得更频繁地轮询。

2. 状态：

   aws securityagent batch-get-pentest-jobs --agent-space-id <id> --pentest-job-ids <pj-id>
   

3. 仅当 status 发生变化或进入终止状态（COMPLETED、FAILED、STOPPED）时才回复。

4. 状态为 COMPLETED 时 → 运行发现结果工作流。

5. 发现结果

aws securityagent list-findings --agent-space-id <id> --pentest-job-id <pj-id>

如果返回了 nextToken，则使用 --next-token <token> 再次调用，直到令牌为空。

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

在聊天中按严重程度分组展示（图标和格式与代码扫描相同）：

🟣 CRITICAL: {name}
   Endpoint: {endpoint}
   {description}

将包含所有返回字段的完整报告写入 .security-agent/pentest-{pentest_job_id}.md（包括 findingId、name、description、riskLevel、riskType、confidence、status、endpoint、请求/响应示例（如有）和 remediationCode（如有））。

告知用户：“详细信息已写入 .security-agent/pentest-{pentest_job_id}.md”

6. 停止渗透测试

aws securityagent stop-pentest-job --agent-space-id <id> --pentest-job-id <pj-id>

---

规则

• 开始前务必确认已获准测试目标
• 创建渗透测试前，请验证目标域名，否则 create-pentest 将失败
• 使用 config.json 中已验证的 target_domain_id，而不是重新验证
• 渗透测试标题不得包含空格，请使用连字符
• 最长每 15 分钟轮询一次 — 渗透测试需要较长时间
• 不要自动重启失败的渗透测试 — 请先向用户展示失败情况

---

故障排除

• verify-target-domain 出现 ValidationException → 验证路由当前尚未正确响应。请让用户确认路由已启用，并正在提供预期的令牌。
• target domain not verified → 再次运行 verify-target-domain（步骤 1）。
• 渗透测试在 IN_PROGRESS 状态下卡住超过 24 小时 → 可能是后端问题，或目标无法访问。请停止并检查。
• 服务角色出现 AccessDenied → 服务角色缺少渗透测试所需的网络/运行时权限。默认的 SecurityAgentScanRole 仅用于代码扫描 — 针对 AWS 资源的渗透测试可能需要更广泛的权限。请引导用户前往 AWS Security Agent 控制台配置专用的渗透测试角色。