Pentesting With Aws Security Agent

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 | |-------------|----------------| | ` (agent space) | config.agentspaceid | | | config.region (default us-east-1) | | | aws sts get-caller-identity --query Account --output text (cache for the rest of the turn) | | | arn:aws:iam:::role/SecurityAgentScanRole | | | targetDomainId returned by create-target-domain (cache under config.target_domains[]) | | | pentestId returned by create-pentest | | | pentestJobId returned by start-pentest-job` |

Pre-pentest checks

1. 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.
2. Verify agent space still exists:

``bash aws securityagent batch-get-agent-spaces --agent-space-ids ``

If missing, clear agent_space_id from config.json and run setup-security-agent again.

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

---

Workflow

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

aws securityagent create-target-domain --agent-space-id  \
  --target-domain-name  --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:

aws securityagent verify-target-domain --agent-space-id  --target-domain-id 

Persist the verified target_domain_id in .security-agent/config.json under target_domains: { "": "" } so future pentests can reuse it.

2. Create a pentest

Ask the user for:

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

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

Capture pentestId.

3. Start the pentest job

aws securityagent start-pentest-job --agent-space-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):

{
  "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 ({pentestjobid}). Pentests typically run 1-24 hours depending on scope. I'll check every 15 minutes — say 'stop polling' to opt out."

4. Polling loop

1. sleep 900 (15 minutes) between checks. Do not poll faster.
2. Status:

``bash aws securityagent batch-get-pentest-jobs --agent-space-id --pentest-job-ids ``

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

5. Findings

aws securityagent list-findings --agent-space-id  --pentest-job-id 

If nextToken is returned, call again with --next-token until empty.

aws securityagent batch-get-findings --agent-space-id  --finding-ids   ...

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

aws securityagent stop-pentest-job --agent-space-id  --pentest-job-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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aws
• Source: aws/agent-toolkit-for-aws
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.