--- name: pentesting-with-aws-security-agent description: 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. --- # 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.agent_space_id` | | `` | `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. 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 ``?" 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 \ --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: ```bash 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) ```bash aws securityagent create-pentest --agent-space-id --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 1. `sleep 900` (15 minutes) between checks. Do not poll faster. 2. Status: ```bash 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 ```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.