# Quickstart: Run a penetration test
<a name="quickstart"></a>

This quickstart walks you through running your first penetration test (pentest) with AWS Security Agent. AWS Security Agent tests your deployed application and identifies security vulnerabilities with detailed findings.

**Note**  
You need access to AWS Management console to setup a new penetration test

## Step 1: Set up AWS Security Agent in the AWS console
<a name="_step_1_set_up_aws_security_agent_in_the_aws_console"></a>

1. Navigate to [AWS Security Agent](https://console.aws.amazon.com/securityagent/) in the AWS Management Console.

1. Select **Set up AWS Security Agent** 

1. Create an agent space. An agent space can be used by multiple users and should be specific for every application you want to test. Enter a name and description for your first agent space. This name appears to users in the web application. The name of the agent space should be based on the application you want to penetration test.

1. Select **IAM-only access** under *User access configuration* 
   + This quickstart does not cover enabling single sign-on (SSO) with IAM Identity Center. This allows users to directly access the AWS Security Agent web application, from the AWS Console.
   + If you want to enable users without AWS Management Console Access to perform tasks such as starting a penetration test or design review, you should enable the IAM Identity Center integration.

1. Click **Set up AWS Security Agent** 

**Note**  
When you choose Set up, AWS Security Agent will create your Agent Space, and establish a web application where your users can carry out design reviews and penetration tests.

## Step 2: Enable and configure penetration testing
<a name="_step_2_enable_and_configure_penetration_testing"></a>

**Note**  
In the AWS console, you define the scope of what can be tested. Users then run specific penetration tests within that scope from the AWS Security Agent web application.

1. From the left sidebar, select **Agent Spaces** and then select the Agent Space you created in Step 1.

1. From the header, select **Enable penetration test** to enable this capability.

1.  **Step 1 — Configure domain**: Enter the target domain you want to test and select a verification method (**DNS\$1TXT** or **HTTP\$1ROUTE**). The domain should be live and host the application you want to penetration test. Choose **Next** to proceed.

1.  **Step 2 — Verify domains**: Verify ownership of each domain in the **Target domains** table:
   + For Route 53 domains in the same AWS account: select the domain and choose **One-click verification**. AWS Security Agent creates the DNS record and completes verification automatically.
   + For other DNS providers: copy the verification token, add the TXT record with your DNS registrar, then select the domain and choose **Verify**.
   + AWS Security Agent can only run penetration tests against verified domains.

1.  **Step 3 — Configure additional capabilities (optional)**: Configure optional resources such as VPCs, CloudWatch logs, and credentials. The **Service access** section is pre-configured — AWS Security Agent automatically creates a service role with the required permissions unless you want to use an existing IAM role.

## Step 3: Connect to GitHub (optional)
<a name="_step_3_connect_to_github_optional"></a>

**Note**  
This step is optional, however we recommend connecting to your GitHub account to give AWS Security Agent access to the source code for your application. This helps the Security Agent understand your application context and improve penetration testing coverage.

1. Once you have completed the pentest setup, you will see a banner with an option to connect GitHub for penetration testing, click **Add** in the right side of the banner.

1. Click **Create new registration** 

1. Select **GitHub** and then **Next** 

1. Click **Install and authorize**. You’ll be redirected to GitHub to complete the installation.

   1. Select the *GitHub User* or *GitHub Organization* that owns the repository you want to test.

   1. Select either **All repositories** or **Only select repositories**. AWS suggests installing AWS Security Agent on all repositories, and then creating a unique agent space for each repository you want to test.

   1. Select **Install & Authorize** and complete GitHub authentication.

1. Define the **Registration Name** and confirm the **account type** matches where you installed the GitHub application.

1. Click **Next** 

1. Select the repositories you want to be associated for penetration testing. This allows the web application users to associate these repositories to a penetration test, when they create a new pentest.

1. Click **Next** 

1. If you want to enable automatic code remediation, enable **Pentest remediation enabled** on the repositories you want to allow AWS Security Agent to create pull requests with ready-to-implement code fix for pentest findings.

1. Click **Connect** 

## Step 4: Run a penetration test
<a name="_step_4_run_a_penetration_test"></a>

**Note**  
You can create and run a penetration test only in the AWS Security Agent web application.

1. Select the **Web app** tab and then **Admin access** to launch the AWS Security Agent Web Application with administrator privileges. This will only work if you had setup your agent using **IAM-only access** under *User access configuration*. Alternatively, you will need to add users and create a login.

1. In the left sidebar, click **Penetration Test**, then select **Create your first penetration test**.

1. Define the penetration test details:

   1. Select the domain you want to test or specify one or more paths. You can only test verified domains.

   1. If your application needs to access URLs that are outside of your target domain, add them to the **Accessible URLs** field.
**Note**  
Add accessible domains for third-party services (such as Okta, Auth0, Stripe) that are outside your target domain. This is required so AWS Security Agent can access these URLs for login and navigation during testing. AWS Security Agent does NOT penetration test these domains—they are used solely for access purposes.

   1. Select the IAM role and log group AWS Security Agent should use to store logs. If you do not select a log group, AWS Security agent will create a log group at the start of the pentest run.

   1. Select **Enable automatic code remediation** to allow AWS Security Agent to automatically create a pull request with ready-to-implement code fix for all the pentest findings.

   1. Click **Next**.

1. (Optional) If your application requires a login, then input the credentials directly into the web application. Define how AWS Security Agent should authenticate to your application. Provide authentication instructions into **Agent Space login prompt**, then click **Next**.

1. (Optional) Provide additional resources to help test your application. You can upload files such as design documents, threat model, API specifications or other documents that are helpful to understand the application context.

1. Click **Create and execute**. You’ll be redirected to the penetration test detail screen.
   + To save the configuration for future use without running it immediately, click **Create penetration test** instead.

## Step 5: Review penetration test findings
<a name="_step_5_review_penetration_test_findings"></a>

1. The penetration test can take up to several hours to complete.

1. Once complete, review the details of the pentest on the Pentest overview, logs and findings screens.