Index of every page on this site: llms.txt
All skills
aws avatar

/pentesting-with-aws-security-agent

@12d7f78
Run it yourself

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.

  • 1 file
  • 6.4 KB
  • Updated 5 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/aws/agent-toolkit-for-aws/pentesting-with-aws-security-agent

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈116 tokens for metadata: the name and description. ≈1.5k when used: this file.

Description uses 5.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈461 characters, or 5.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

    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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 12d7f78. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 5 months ago

README badge

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