# Troubleshooting
<a name="troubleshooting"></a>

Find solutions to commonly seen errors when using AWS Security Agent.

## Access Denied: Incorrect GitHub account type selected or incorrect organization name specified
<a name="_access_denied_incorrect_github_account_type_selected_or_incorrect_organization_name_specified"></a>
+ You installed the AWS Security Agent application into your desired GitHub organization but incorrectly set the `GitHub Account Type` to `User` instead of `Organization` 
+ You installed the AWS Security Agent application into your desired GitHub organization and correctly set the `GitHub Account Type` to `Organization` but left the `Organization Name` field blank or entered an incorrect organization name that does not match the organization you installed the application into

 **Solution:** 

1. Go to GitHub and uninstall the app from the organization. For more information, see [Step 1: Uninstall the AWS Security Agent GitHub App from GitHub](remove-github.md#remove-github-step-1).

1. Go back to the integrations page and restart the integration process by clicking on `Add Integrations`, install and authorize the app into your desired GitHub organization once again.

1. Select `Organization` from the dropdown of `GitHub account type` 

1. Make sure the `Organization Name` you input is the EXACT same as the one you installed the application into.

1. Choose **Connect** to create your GitHub organization integration.

## Access Denied: Insufficient permissions to install GitHub App into organization
<a name="_access_denied_insufficient_permissions_to_install_github_app_into_organization"></a>

When you attempt to install the AWS Security Agent application into your desired GitHub organization, you will see two different messages on the button in the installation page.
+ An organization `Member` will see `Authorize & Request` 
+ An organization `Owner` will see `Install & Authorize` 

You can verify whether you are a `Member` or an `Owner` of the GitHub organization by following the below steps.

1. Go to [github.com](https://github.com) 

1. Choose your profile on the website

1. Navigate to `Organizations` on the dropdown menu and choose it

1. Find the organization you wish to install AWS Security Agent into from the list of organizations, it will specify whether you are a `Member` or an `Owner` next to the organization name.

To verify the installation, AWS Security Agent lists the apps installed on the organization. It uses the GitHub account that authorized the app. GitHub allows only organization owners to list installed apps. Registration fails for a member even after an owner approves the member’s installation request.

Possible solutions:
+ Have an organization owner complete the whole integration process: install the app, authorize it, and register it in the AWS Console
+ Have an owner update your role in the GitHub organization from a `Member` to an `Owner` and restart the integration process again

## Agent cannot connect to endpoint during a penetration test
<a name="_agent_cannot_connect_to_endpoint_during_a_penetration_test"></a>

If the penetration test agent is unable to make calls to the configured target URL or fails to successfully navigate the target endpoint:
+ If your endpoint makes calls to domains outside the configured target URL, verify the additional domains are added as **Accessible URLs** in your penetration test configuration
+ If your application serves traffic on a non-standard port, include the port in the target URL (for example, `https://example.com:8443`)
+ If you have a WAF configured, check that you WAF is not blocking penetration test traffic. You can allowlist penetration test traffic by `User-Agent` header, which will be set to `securityagent` by default

## Endpoint validation failed during a penetration test
<a name="_endpoint_validation_failed_during_a_penetration_test"></a>

A penetration test failing during endpoint validation indicates that your endpoint is not accessible from the penetration testing environment. The steps for debugging this issue will depend on if you have configured a VPC for your penetration test:
+ For a non-VPC penetration test:
  + Ensure the target endpoint has a public DNS record that resolves to a publicly accessible IP address
  + Verify that your target endpoint can be reached without special networking requirements. Some common blockers are a specific VPN required to reach the endpoint or a WAF that blocks public internet traffic
  + Attempt to reach the target endpoint using `curl` or a browser and verify you receive a valid response
+ For a VPC penetration test:
  + Ensure the selected VPC/subnet has proper routing to the target endpoint (e.g., via VPN tunnel or VPC peering), DNS resolution is correctly configured for the private domain (e.g., Route 53 Resolver or custom DNS), and security group rules allow outbound traffic to the target
  + To debug further, launch an EC2 instance in your account with the same VPC, subnet, and security group as your penetration test. Connect to the EC2 instance and verify that networking requests to your target endpoint succeed

## Penetration test failed due to an IP allowlist
<a name="_penetration_test_failed_due_to_an_ip_allowlist"></a>

If the endpoint that a penetration test targets has an IP allowlist enabled, you can add a private VPC configuration with an associated [VPC NAT Gateway](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html) to your penetration test. You can then use the NAT Gateway IP address to allowlist outbound traffic from the penetration test.

## Penetration test login blocked by an identity provider
<a name="_penetration_test_login_blocked_by_an_identity_provider"></a>

A penetration test might report a login failure for an application that delegates sign-in to a third-party identity provider. The provider might have blocked the agent’s browser instead of rejecting the credentials. Providers that apply anti-automation controls can refuse an automated browser before they evaluate the credentials. They usually report that the browser or app is not secure.

 **Solution:** 

Provide a credential that the agent can replay, rather than one it has to earn by completing the provider’s sign-in flow. For longer tests, prefer an AWS Lambda function, because it can return a fresh session for each run.
+ Sign in yourself and capture the resulting session cookie or bearer token.
+ Store it in AWS Secrets Manager, or return it from an AWS Lambda function. For more information, see [Select static credential from connected AWS Secrets Manager](provide-testing-credentials.md#provide-testing-credentials-secrets-manager).
+ Select it as the credential for the penetration test.
+ Use the **Agent Space login prompt** to state how to apply it, for example which header to set on each request.
+ Keep the session valid for the duration of the test.
+ Point the agent at a sign-in path that isn’t delegated to the provider, such as a local test account or an API key, if the application offers one.

## Getting additional help
<a name="_getting_additional_help"></a>

If you continue to experience issues after trying these troubleshooting steps:
+ Check the AWS Security Agent service status page
+ Contact AWS Support for assistance with complex configuration issues