# How to Run Penetration Testing with AWS Security Agent: Complete Setup and Workflow Guide > Learn how to run penetration testing with AWS Security Agent. This guide covers agent setup, domain registration, job creation, and finding retrieval for robust security assessments. - Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws) - Tags: how-to-guide - Published: 2026-06-26 --- **To run penetration testing with AWS Security Agent, you must first initialize an agent space with IAM roles and S3 storage, then register and verify your target domain, create a pentest job specifying your endpoints, and finally poll for completion to retrieve structured findings.** The `aws/agent-toolkit-for-aws` repository provides reusable DevSecOps skills that automate AWS Security Agent orchestration. Understanding how to run penetration testing with AWS Security Agent enables you to execute authorized, on-demand vulnerability assessments against live web applications while maintaining strict domain ownership verification and safety controls. ## Architecture Overview AWS Security Agent penetration testing relies on four core components defined in the toolkit's setup phase. The **Agent Space** acts as a logical container linking your AWS resources to the Security Agent service. An **IAM Service Role** (`SecurityAgentScanRole`) grants the service scoped permissions to store artifacts in a dedicated **S3 Bucket** (`security-agent-scans--`). Finally, the **Target Domain** represents the verified endpoint you own and wish to test, while the **Pentest Job** executes the actual 24-hour maximum attack surface scan. ## Step 1: Initialize the Security Agent Environment Before running any scans, you must execute the setup skill defined in [`plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md). This creates the persistent workspace configuration stored in [`.security-agent/config.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.security-agent/config.json). The setup process involves: 1. Creating the **Agent Space** using `aws securityagent create-agent-space` 2. Provisioning the **IAM Role** with a trust policy allowing `securityagent.amazonaws.com` 3. Creating the **S3 Bucket** with public-access blocks and 30-day lifecycle rules 4. Linking resources via `aws securityagent update-agent-space` ```bash # Create agent space (if none exists) aws securityagent create-agent-space --name security-scans # Create IAM role with trust policy aws iam create-role --role-name SecurityAgentScanRole \ --assume-role-policy-document file://trust.json # Create region-specific S3 bucket BUCKET="security-agent-scans-$(aws sts get-caller-identity --query Account --output text)-${AWS_REGION:-us-east-1}" aws s3api create-bucket --bucket "$BUCKET" \ $(if [ "$AWS_REGION" != "us-east-1" ]; then echo "--create-bucket-configuration LocationConstraint=$AWS_REGION"; fi) # Link resources to agent space aws securityagent update-agent-space --agent-space-id \ --aws-resources iamRoles=[arn:aws:iam:::role/SecurityAgentScanRole],s3Buckets=[$BUCKET] ``` ## Step 2: Register and Verify Your Target Domain You must prove domain ownership before testing. As defined in [`plugins/aws-agents-for-devsecops/skills/pentesting-with-aws-security-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/pentesting-with-aws-security-agent/SKILL.md), this requires hosting a verification token at a specific HTTP route. First, register the domain: ```bash aws securityagent create-target-domain \ --agent-space-id \ --target-domain-name example.com \ --verification-method HTTP_ROUTE ``` Host the returned verification token at `/.well-known/security-agent-verification` (or your configured route), then verify ownership: ```bash aws securityagent verify-target-domain \ --agent-space-id \ --target-domain-id ``` ## Step 3: Create and Execute the Pentest Job The toolkit enforces a **user confirmation prompt** before launching any pentest (step 40 in the workflow). After confirmation, create the pentest specifying your endpoints: ```bash aws securityagent create-pentest \ --agent-space-id \ --title pentest-$(date +%s) \ --service-role arn:aws:iam:::role/SecurityAgentScanRole \ --assets endpoints=[{uri=https://example.com/api/login},{uri=https://example.com/api/upload}] ``` Start the 24-hour maximum scan: ```bash aws securityagent start-pentest-job \ --agent-space-id \ --pentest-id ``` The toolkit records the returned `pentestJobId` in [`.security-agent/pentests.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.security-agent/pentests.json) for tracking. ## Step 4: Poll for Completion and Retrieve Findings Poll the job status every 15 minutes until `COMPLETED`: ```bash aws securityagent batch-get-pentest-jobs \ --agent-space-id \ --pentest-job-ids ``` Once finished, retrieve structured findings containing severity ratings, affected endpoints, and remediation code: ```bash aws securityagent list-findings \ --agent-space-id \ --pentest-job-id # Get full details for specific findings aws securityagent batch-get-findings \ --agent-space-id \ --finding-ids ``` The skill automatically generates a markdown report at `.security-agent/pentest-.md`. ## Key Configuration Files The toolkit maintains state in your local workspace to enable reproducible scans: - **[`.security-agent/config.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.security-agent/config.json)**: Stores the `agent_space_id`, region, and IAM role ARNs created by the setup skill - **[`.security-agent/pentests.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.security-agent/pentests.json)**: Tracks active and historical pentest job identifiers and their statuses - **[`plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md)**: Specifies the complete IAM trust policies and S3 bucket configurations - **[`plugins/aws-agents-for-devsecops/skills/pentesting-with-aws-security-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/pentesting-with-aws-security-agent/SKILL.md)**: Defines the full pentest workflow including domain verification requirements and safety guardrails ## Summary - **Initialize once**: Run the setup skill to create your Agent Space, IAM Role (`SecurityAgentScanRole`), and S3 bucket, storing configuration in [`.security-agent/config.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.security-agent/config.json) - **Verify ownership**: Register your target domain and host the verification token at the required HTTP route before scanning - **Authorize explicitly**: Confirm permissions when prompted before the toolkit launches any pentest job - **Poll and report**: Use `batch-get-pentest-jobs` to monitor progress, then retrieve findings via `list-findings` and review the auto-generated markdown report ## Frequently Asked Questions ### How long does an AWS Security Agent pentest job run? A pentest job can run for up to 24 hours, probing the endpoints you specified during creation. The toolkit automatically polls the job status and reports completion without requiring manual intervention. ### What permissions does the SecurityAgentScanRole require? The IAM role requires permissions to read from and write to the dedicated S3 bucket (`security-agent-scans--`), write logs, and assume the trust relationship with `securityagent.amazonaws.com`. The exact policy documents are defined in [`plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md). ### Why must I verify domain ownership before pentesting? Domain verification ensures you have legitimate control over the target endpoint, preventing unauthorized scanning of third-party infrastructure. You must host a verification token at a specific HTTP route (typically `/.well-known/security-agent-verification`) and call `verify-target-domain` before creating any pentest jobs. ### Where does the toolkit store pentest results? Findings are stored in two locations: the AWS Security Agent service returns structured data via `list-findings` and `batch-get-findings` API calls, while the local skill writes a human-readable markdown report to `.security-agent/pentest-.md` in your workspace.