OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add aws/agent-toolkit-for-aws --skill pentesting-with-aws-security-agent
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.
npx skills add aws/agent-toolkit-for-aws --skill pentesting-with-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.
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 |
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:
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.
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:
Persist the verified target_domain_id in .security-agent/config.json under target_domains: { "<domain>": "<td-id>" } so future pentests can reuse it.
Ask the user for:
pentest-<timestamp>)Capture pentestId.
Capture pentestJobId. Append to .security-agent/pentests.json (create as [] if it doesn't exist yet — the directory itself is already created by setup):
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."
sleep 900 (15 minutes) between checks. Do not poll faster.
Status:
Only respond when status changes or on terminal state (COMPLETED, FAILED, STOPPED).
On COMPLETED → run the Findings workflow.
If nextToken is returned, call again with --next-token <token> until empty.
Present in chat grouped by severity (same icons + format as code scans):
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"
create-pentest will fail otherwisetarget_domain_id from config.json instead of re-verifyingValidationException 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.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.