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:

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:

   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.

3. Resolve account and role ARN from the table above.

4. 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)

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:

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)

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

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):

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

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

2. Status:

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

3. Only respond when status changes or on terminal state (COMPLETED, FAILED, STOPPED).

4. On COMPLETED → run the Findings workflow.

5. Findings

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.

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

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.