pentesting-with-aws-security-agent

Name: pentesting-with-aws-security-agent
Author: aws

258installs190forks

How to install pentesting-with-aws-security-agent?

aws/agent-toolkit-for-aws/pentesting-with-aws-security-agent

$npx -y skills add aws/agent-toolkit-for-aws --skill pentesting-with-aws-security-agent

Installs into the current project.

Summary

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 penetrat

Files · 1

View on GitHub

SKILL.md

1	# AWS Security Agent — Penetration Test
2
3	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.
4
5	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.
6
7	---
8
9	## Resolving the values you need
10
11	The CLI examples below use placeholders. Resolve them at the start of every pentest:
12
13	\| Placeholder \| How to resolve \|
14	\|-------------\|----------------\|
15	\| `<id>` (agent space) \| `config.agent_space_id` \|
16	\| `<region>` \| `config.region` (default `us-east-1`) \|
17	\| `<account>` \| `aws sts get-caller-identity --query Account --output text` (cache for the rest of the turn) \|
18	\| `<role-arn>` \| `arn:aws:iam::<account>:role/SecurityAgentScanRole` \|
19	\| `<td-id>` \| `targetDomainId` returned by `create-target-domain` (cache under `config.target_domains[<domain>]`) \|
20	\| `<pentest-id>` \| `pentestId` returned by `create-pentest` \|
21	\| `<pj-id>` \| `pentestJobId` returned by `start-pentest-job` \|
22
23	## Pre-pentest checks
24
25	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.
26	2. Verify agent space still exists:
27
28	```bash
29	aws securityagent batch-get-agent-spaces --agent-space-ids <id>
30	```
31
32	If missing, clear `agent_space_id` from `config.json` and run `setup-security-agent` again.
33	3. Resolve account and role ARN from the table above.
34	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.
35
36	---
37
38	## Workflow
39
40	### 1. Register target domain (one-time per domain)
41
42	```bash
43	aws securityagent create-target-domain --agent-space-id <id> \
44	--target-domain-name <domain> --verification-method HTTP_ROUTE
45	```
46
47	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:
48
49	```bash
50	aws securityagent verify-target-domain --agent-space-id <id> --target-domain-id <td-id>
51	```
52
53	Persist the verified `target_domain_id` in `.security-agent/config.json` under `target_domains: { "<domain>": "<td-id>" }` so future pentests can reuse it.
54
55	### 2. Create a pentest
56
57	Ask the user for:
58
59	- Title (no spaces — use hyphens; default `pentest-<timestamp>`)
60	- Endpoints to test (one or more URIs under the verified domain)
61
62	```bash
63	aws securityagent create-pentest --agent-space-id <id> --title <title> \
64	--service-role <role-arn> \
65	--assets endpoints=[{uri=https://example.com/api/login},{uri=https://example.com/api/upload}]
66	```
67
68	Capture `pentestId`.
69
70	### 3. Start the pentest job
71
72	```bash
73	aws securityagent start-pentest-job --agent-space-id <id> --pentest-id <pentest-id>
74	```
75
76	Capture `pentestJobId`. Append to `.security-agent/pentests.json` (create as `[]` if it doesn't exist yet — the directory itself is already created by setup):
77
78	```json
79	{
80	"pentest_id": "p-...",
81	"pentest_job_id": "pj-...",
82	"agent_space_id": "as-...",
83	"title": "pentest-...",
84	"endpoints": ["https://..."],
85	"started_at": "2026-06-01T20:00:00Z",
86	"status": "IN_PROGRESS"
87	}
88	```
89
90	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."
91
92	### 4. Polling loop
93
94	1. `sleep 900` (15 minutes) between checks. Do not poll faster.
95	2. Status:
96
97	```bash
98	aws securityagent batch-get-pentest-jobs --agent-space-id <id> --pentest-job-ids <pj-id>
99	```
100
101	3. Only respond when `status` changes or on terminal state (`COMPLETED`, `FAILED`, `STOPPED`).
102	4. On `COMPLETED` → run the Findings workflow.
103
104	### 5. Findings
105
106	```bash
107	aws securityagent list-findings --agent-space-id <id> --pentest-job-id <pj-id>
108	```
109
110	If `nextToken` is returned, call again with `--next-token <token>` until empty.
111
112	```bash
113	aws securityagent batch-get-findings --agent-space-id <id> --finding-ids <id1> <id2> ...
114	```
115
116	Present in chat grouped by severity (same icons + format as code scans):
117
118	```
119	🟣 CRITICAL: {name}
120	Endpoint: {endpoint}
121	{description}
122	```
123
124	Write a full report to `.security-agent/pentest-{pentest_job_id}.md` with every field returned (findingId, name, desc

People who liked this also viewed

6 picks

Type

pentesting-with-aws-security-agent

258installs190forks

View on GitHub

How to install pentesting-with-aws-security-agent?

aws/agent-toolkit-for-aws/pentesting-with-aws-security-agent

$npx -y skills add aws/agent-toolkit-for-aws --skill pentesting-with-aws-security-agent

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# AWS Security Agent — Penetration Test
2
3	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.
4
5	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.
6
7	---
8
9	## Resolving the values you need
10
11	The CLI examples below use placeholders. Resolve them at the start of every pentest:
12
13	\| Placeholder \| How to resolve \|
14	\|-------------\|----------------\|
15	\| `<id>` (agent space) \| `config.agent_space_id` \|
16	\| `<region>` \| `config.region` (default `us-east-1`) \|
17	\| `<account>` \| `aws sts get-caller-identity --query Account --output text` (cache for the rest of the turn) \|
18	\| `<role-arn>` \| `arn:aws:iam::<account>:role/SecurityAgentScanRole` \|
19	\| `<td-id>` \| `targetDomainId` returned by `create-target-domain` (cache under `config.target_domains[<domain>]`) \|
20	\| `<pentest-id>` \| `pentestId` returned by `create-pentest` \|
21	\| `<pj-id>` \| `pentestJobId` returned by `start-pentest-job` \|
22
23	## Pre-pentest checks
24
25	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.
26	2. Verify agent space still exists:
27
28	```bash
29	aws securityagent batch-get-agent-spaces --agent-space-ids <id>
30	```
31
32	If missing, clear `agent_space_id` from `config.json` and run `setup-security-agent` again.
33	3. Resolve account and role ARN from the table above.
34	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.
35
36	---
37
38	## Workflow
39
40	### 1. Register target domain (one-time per domain)
41
42	```bash
43	aws securityagent create-target-domain --agent-space-id <id> \
44	--target-domain-name <domain> --verification-method HTTP_ROUTE
45	```
46
47	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:
48
49	```bash
50	aws securityagent verify-target-domain --agent-space-id <id> --target-domain-id <td-id>
51	```
52
53	Persist the verified `target_domain_id` in `.security-agent/config.json` under `target_domains: { "<domain>": "<td-id>" }` so future pentests can reuse it.
54
55	### 2. Create a pentest
56
57	Ask the user for:
58
59	- Title (no spaces — use hyphens; default `pentest-<timestamp>`)
60	- Endpoints to test (one or more URIs under the verified domain)
61
62	```bash
63	aws securityagent create-pentest --agent-space-id <id> --title <title> \
64	--service-role <role-arn> \
65	--assets endpoints=[{uri=https://example.com/api/login},{uri=https://example.com/api/upload}]
66	```
67
68	Capture `pentestId`.
69
70	### 3. Start the pentest job
71
72	```bash
73	aws securityagent start-pentest-job --agent-space-id <id> --pentest-id <pentest-id>
74	```
75
76	Capture `pentestJobId`. Append to `.security-agent/pentests.json` (create as `[]` if it doesn't exist yet — the directory itself is already created by setup):
77
78	```json
79	{
80	"pentest_id": "p-...",
81	"pentest_job_id": "pj-...",
82	"agent_space_id": "as-...",
83	"title": "pentest-...",
84	"endpoints": ["https://..."],
85	"started_at": "2026-06-01T20:00:00Z",
86	"status": "IN_PROGRESS"
87	}
88	```
89
90	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."
91
92	### 4. Polling loop
93
94	1. `sleep 900` (15 minutes) between checks. Do not poll faster.
95	2. Status:
96
97	```bash
98	aws securityagent batch-get-pentest-jobs --agent-space-id <id> --pentest-job-ids <pj-id>
99	```
100
101	3. Only respond when `status` changes or on terminal state (`COMPLETED`, `FAILED`, `STOPPED`).
102	4. On `COMPLETED` → run the Findings workflow.
103
104	### 5. Findings
105
106	```bash
107	aws securityagent list-findings --agent-space-id <id> --pentest-job-id <pj-id>
108	```
109
110	If `nextToken` is returned, call again with `--next-token <token>` until empty.
111
112	```bash
113	aws securityagent batch-get-findings --agent-space-id <id> --finding-ids <id1> <id2> ...
114	```
115
116	Present in chat grouped by severity (same icons + format as code scans):
117
118	```
119	🟣 CRITICAL: {name}
120	Endpoint: {endpoint}
121	{description}
122	```
123
124	Write a full report to `.security-agent/pentest-{pentest_job_id}.md` with every field returned (findingId, name, desc

People who liked this also viewed

6 picks

Type