How to Run Penetration Testing with AWS Security Agent: Complete Setup and Workflow Guide

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-<account>-<region>). 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. This creates the persistent workspace configuration stored in .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

# 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 <as-id> \
  --aws-resources iamRoles=[arn:aws:iam::<account>: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, this requires hosting a verification token at a specific HTTP route.

First, register the domain:

aws securityagent create-target-domain \
  --agent-space-id <as-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:

aws securityagent verify-target-domain \
  --agent-space-id <as-id> \
  --target-domain-id <td-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:

aws securityagent create-pentest \
  --agent-space-id <as-id> \
  --title pentest-$(date +%s) \
  --service-role arn:aws:iam::<account>:role/SecurityAgentScanRole \
  --assets endpoints=[{uri=https://example.com/api/login},{uri=https://example.com/api/upload}]

Start the 24-hour maximum scan:

aws securityagent start-pentest-job \
  --agent-space-id <as-id> \
  --pentest-id <pentest-id>

The toolkit records the returned pentestJobId in .security-agent/pentests.json for tracking.

Step 4: Poll for Completion and Retrieve Findings

Poll the job status every 15 minutes until COMPLETED:

aws securityagent batch-get-pentest-jobs \
  --agent-space-id <as-id> \
  --pentest-job-ids <pentestJobId>

Once finished, retrieve structured findings containing severity ratings, affected endpoints, and remediation code:

aws securityagent list-findings \
  --agent-space-id <as-id> \
  --pentest-job-id <pentestJobId>

# Get full details for specific findings

aws securityagent batch-get-findings \
  --agent-space-id <as-id> \
  --finding-ids <id1> <id2>

The skill automatically generates a markdown report at .security-agent/pentest-<pentestJobId>.md.

Key Configuration Files

The toolkit maintains state in your local workspace to enable reproducible scans:

• .security-agent/config.json: Stores the agent_space_id, region, and IAM role ARNs created by the setup skill
• .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: Specifies the complete IAM trust policies and S3 bucket configurations
• 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
• 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-<account>-<region>), 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.

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-<pentestJobId>.md in your workspace.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}