pentesting-with-aws-security-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AWS Security Agent — Penetration Test

AWS Security Agent — 渗透测试

This skill handles pentest setup, execution, and findings. Initial Security Agent setup (agent space, role, bucket) is handled by the setup-security-agent
skill — if

.security-agent/config.json

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

Pentests are slow (1-24 hours) and active — they probe a real running app. Always confirm the user is authorized to test the target before starting.

本技能负责渗透测试的设置、执行及结果处理。初始Security Agent设置（agent space、角色、存储桶）由**

setup-security-agent

**技能处理——如果

.security-agent/config.json

缺失，渗透测试工作流会先自动内联运行设置步骤。

渗透测试耗时较长（1-24小时）且为主动测试——会探测真实运行中的应用。开始前务必确认用户拥有测试目标的授权。

Resolving the values you need

获取所需参数值

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

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`
`<td-id>`	`targetDomainId` returned by `create-target-domain` (cache under `config.target_domains[<domain>]` )
`<pentest-id>`	`pentestId` returned by `create-pentest`
`<pj-id>`	`pentestJobId` returned by `start-pentest-job`

以下CLI示例使用占位符。每次渗透测试开始前需解析这些占位符：

占位符	获取方式
`<id>` （agent space）	`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`

Pre-pentest checks

渗透测试前检查

Read
.security-agent/config.json
. If missing → tell the user one line — "First pentest in this workspace — running setup first." — and run the
```
setup-security-agent
```
workflow inline before continuing.

Verify agent space still exists:

bash

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

If missing, clear

agent_space_id

from

config.json

and run

setup-security-agent

again.

Resolve account and role ARN from the table above.
Authorization check: ask the user "Do you own or have explicit permission to pentest
```
<target>
```
?" if it's not obvious from context. Do not proceed without confirmation.

读取
.security-agent/config.json
。若文件缺失→告知用户一句话：“此工作区首次进行渗透测试——先运行设置步骤。”，并在继续前内联运行
```
setup-security-agent
```
工作流。

验证agent space是否仍存在：

bash

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

若不存在，从

config.json

中清除

agent_space_id

并重新运行

setup-security-agent

。

根据上表解析账号和角色ARN。
授权检查：若上下文无法明确，询问用户“您是否拥有或获得明确授权对
```
<target>
```
进行渗透测试？”。未获得确认前不得继续。

Workflow

工作流

1. Register target domain (one-time per domain)

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

bash

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

The response includes a verification token / route. Tell the user what to put on their server (typically a

.well-known/...

file or HTTP route returning a token), then:

bash

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

Persist the verified

target_domain_id

.security-agent/config.json

under

target_domains: { "<domain>": "<td-id>" }

so future pentests can reuse it.

bash

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

响应包含验证令牌/路由。告知用户需在服务器上配置的内容（通常是

.well-known/...

文件或返回令牌的HTTP路由），然后执行：

bash

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. Create a pentest

2. 创建渗透测试任务

Ask the user for:

Title (no spaces — use hyphens; default
```
pentest-<timestamp>
```
)
Endpoints to test (one or more URIs under the verified domain)

bash

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

Capture

pentestId

向用户询问：

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

bash

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. Start the pentest job

3. 启动渗透测试任务

bash

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

Capture

pentestJobId

. Append to

.security-agent/pentests.json

(create as

[]

if it doesn't exist yet — the directory itself is already created by setup):

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

Tell user: "Pentest started ({pentest_job_id}). Pentests typically run 1-24 hours depending on scope. I'll check every 15 minutes — say 'stop polling' to opt out."

bash

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

记录

pentestJobId

。将其追加到

.security-agent/pentests.json

中（若文件不存在则创建为

[]

——该目录已由设置步骤创建）：

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. Polling loop

4. 轮询循环

```
sleep 900
```
(15 minutes) between checks. Do not poll faster.

Status:

bash

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

Only respond when
```
status
```
changes or on terminal state (
```
COMPLETED
```
,
```
FAILED
```
,
```
STOPPED
```
).
On
```
COMPLETED
```
→ run the Findings workflow.

每次检查间隔
```
sleep 900
```
（15分钟）。不得缩短轮询间隔。

查询状态：

bash

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

仅当
```
status
```
变化或进入终端状态（
```
COMPLETED
```
、
```
FAILED
```
、
```
STOPPED
```
）时回复用户。
当状态为
```
COMPLETED
```
→执行结果处理工作流。

5. Findings

5. 检测结果处理

bash

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

nextToken

is returned, call again with

--next-token <token>

until empty.

bash

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

Present in chat grouped by severity (same icons + format as code scans):

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

Write a full report to

.security-agent/pentest-{pentest_job_id}.md

with every field returned (findingId, name, description, riskLevel, riskType, confidence, status, endpoint, request/response samples if present, and remediationCode if present).

Tell user: "Full details written to

.security-agent/pentest-{pentest_job_id}.md

bash

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

若返回

nextToken

，需携带

--next-token <token>

再次调用，直至无返回值。

bash

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

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

🟣 CRITICAL: {name}
   端点: {endpoint}
   {description}

将所有返回字段（findingId、name、description、riskLevel、riskType、confidence、status、endpoint、请求/响应样本（若存在）、remediationCode（若存在））写入完整报告至

.security-agent/pentest-{pentest_job_id}.md

。

告知用户：“详细内容已写入

.security-agent/pentest-{pentest_job_id}.md

”

6. Stop a pentest

6. 停止渗透测试

bash

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

bash

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

Rules

规则

Always confirm authorization to test the target before starting
Verify the target domain before creating a pentest —
```
create-pentest
```
will fail otherwise
Reuse a verified
```
target_domain_id
```
from
```
config.json
```
instead of re-verifying
Pentest titles must not contain spaces — use hyphens
Poll every 15 minutes max — pentests are long-running
Don't auto-restart a failed pentest — show the failure to the user first

开始前务必确认测试授权
创建渗透测试任务前需验证目标域名——否则
```
create-pentest
```
会失败
复用
```
config.json
```
中已验证的
```
target_domain_id
```
，无需重新验证
渗透测试标题不得包含空格——使用连字符
最长每15分钟轮询一次——渗透测试为长时间运行任务
不得自动重启失败的渗透测试——先向用户展示失败信息

Troubleshooting

故障排除

ValidationException
on
verify-target-domain
→ the verification route isn't responding correctly yet. Ask user to confirm the route is live and serving the expected token.
target domain not verified
→ run verify-target-domain (step 1) again.
Pentest stuck in
IN_PROGRESS
for >24 hours → likely a backend issue or the target is unreachable. Stop and inspect.
AccessDenied
on the service role → the service role doesn't have the network/runtime permissions a pentest needs. The default
```
SecurityAgentScanRole
```
is for code scans only — pentests against AWS resources may need broader permissions. Direct user to the AWS Security Agent console to configure a pentest-specific role.

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