pentesting-with-aws-security-agent

Original：🇺🇸 English

Translated

Run an AWS Security Agent penetration test against a live web application — registers and verifies the target domain, exercises the supplied endpoints with the managed Security Agent service, and returns verified runtime findings. Use when the user asks to pentest, run a penetration test, test their app's attack surface, find runtime vulnerabilities, register or verify a target domain, or check pentest status / findings.

1installs

Sourceaws/agent-toolkit-for-aws

Added on2026-07-05

NPX Install

npx skill4agent add aws/agent-toolkit-for-aws pentesting-with-aws-security-agent

SKILL.md Content

View Translation Comparison →

AWS Security Agent — Penetration Test

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.

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`

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.

Workflow

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

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

in

.security-agent/config.json

under

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

so future pentests can reuse it.

2. Create a pentest

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

.

3. Start the pentest job

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

4. Polling loop

```
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.

5. Findings

bash

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

If

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

"

6. Stop a pentest

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

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.

pentesting-with-aws-security-agent

NPX Install

Tags

SKILL.md Content

AWS Security Agent — Penetration Test

Resolving the values you need

Pre-pentest checks

Workflow

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

2. Create a pentest

3. Start the pentest job

4. Polling loop

5. Findings

6. Stop a pentest

Rules

Troubleshooting