pentesting-with-aws-security-agent

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

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

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

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}

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws