Provide authentication credentials for penetration testing

Provide credentials to enable AWS Security Agent to test authenticated areas of your web applications. Without credentials, the agent can only test publicly accessible pages and APIs.

Configure authentication credentials

Advanced options

If you select Advanced setting, you can choose from three credential strategies:

Input credentials directly

Use advanced setting

When you select an advanced credential strategy (Secrets Manager, Lambda, or IAM role), AWS Security Agent retrieves your credentials directly from the configured AWS resource using the service role. Use the Agent Space login prompt to provide the agent with instructions on how to apply those credentials to your application - for example, which login URL to navigate to and which form fields to fill in.

Select available IAM role for agent to assume

Use this option for applications using AWS Cognito, API Gateway with IAM authentication, or other AWS-native authentication systems. The IAM role must have a trust relationship allowing AWS Security Agent to assume it and permissions to access your application’s authentication system.

Select static credential from connected AWS Secrets Manager

Use this option to retrieve credentials securely from AWS Secrets Manager with encryption, rotation, and access auditing.

The IAM role must have secretsmanager:GetSecretValue and secretsmanager:DescribeSecret permissions.

The agent retrieves the secret value directly from Secrets Manager. Use the Agent Space login prompt to tell the agent how to apply those credentials to your application’s login flow - for example, which URL to navigate to and which form fields to fill in. You may use any format to store your secret, as the agent will interpret the format using the instructions you provide in the login prompt.

For example, if the agent is to submit a username/password login form at https://example.com/login, you may format your secret as JSON with username and password fields. If the application requires TOTP-based 2FA, include a totpSecret field with either the TOTP secret directly or a full otpauth://totp/ URI:

{
  "username": "test-user",
  "password": "secure-password-here",
  "totpSecret": "JBSWY3DPEHPK3PXP"
}

Then, configure the authentication instructions: . Set Access URL to https://example.com (or any other URL selected from the list of target endpoints). . Enter the following into Agent Space login prompt: "Navigate to https://example.com/login and enter the provided username and password into the form."

As another example, if you instead have an API key to be provided in an HTTP header, you may store it as plaintext:

"api-key-here"

Then, configure the authentication instructions: . Enter the following into Agent Space login prompt: "Set the X-API-Key header to the provided API key for all requests."

Select available Lambda function to retrieve credentials dynamically

Use this option for complex authentication systems, dynamic credential generation, or integration with external identity providers.

The IAM role must have lambda:InvokeFunction permissions and the function must complete within 30 seconds.

When the penetration test runs, AWS Security Agent invokes your AWS Lambda function synchronously and passes an event that identifies the penetration test and the specific credential being resolved:

{
  "pentest_arn": "arn:aws:securityagent:us-west-2:111122223333:pentest/pt-abcd1234-5678-90ab-cdef-EXAMPLE11111",
  "actor_identifier": "Credential1"
}

The agent uses the function’s output directly as the credential. Use the Agent Space login prompt to tell the agent how to apply those credentials to your application, the same way you would with AWS Secrets Manager. Refer to Select static credential from connected AWS Secrets Manager for examples of how to format the output of your Lambda function and supported authentication types.

Configure email MFA

Use email MFA when your application sends a one-time code or verification link by email as part of its authentication flow. If your application uses an authenticator app instead, provide a TOTP secret as described in Input credentials directly.

When you enable email MFA, AWS Security Agent generates a unique forwarding address for each credential. You then create a rule in your email provider that forwards only your application’s MFA messages to that address. During login, AWS Security Agent reads the forwarded message and submits the code or link to complete authentication.

Enable email MFA in the console

Enable email MFA with the AWS CLI or API

Set enableEmailMfa to true for the actor in the assets parameter of your create-pentest or update-pentest request. For example:

aws securityagent create-pentest \
  --title "My penetration test" \
  --agent-space-id "your-agent-space-id" \
  --assets '{"actors": [{"identifier": "test-user", "enableEmailMfa": true}]}'

AWS Security Agent returns an mfaForwardingAddress for each actor in the assets field of the response.

Set up email forwarding

Create a separate forwarding rule for each credential that uses email MFA. The general steps are the same for every provider:

The following providers support forwarding to the MFA forwarding address:

The following providers do not support forwarding to the MFA forwarding address:

Any other provider that forwards to an unverified external address also works. Consult your provider’s documentation for the equivalent steps.

Data retention

AWS Security Agent stores the messages that it receives at the forwarding address only to complete the penetration test login. AWS Security Agent automatically deletes these messages 24 hours after receiving them.

Configure multiple credentials

To test different user roles or authentication systems:

Login Optimization

Login Optimization allows AWS Security Agent to learn navigation patterns from previous penetration test runs and apply them to subsequent runs. These patterns include login flows and multi-step authentication workflows. This reduces the time the agent spends re-discovering how to authenticate, resulting in faster scans and more consistent testing coverage.

How Login Optimization works

On the first penetration test run, the agent discovers how to navigate your application’s login flow using the credentials you provide. It records the successful navigation steps and generates a skill file that captures the learned login workflow.

On subsequent runs, the agent reads the saved skill file and applies the learned navigation pattern directly, skipping the discovery phase. This means:

Enable or disable Login Optimization

Login Optimization is enabled by default. To disable or re-enable it:

When disabled, the agent re-discovers the login flow from scratch on every run. Previously learned navigation skills are preserved and will be applied again if the feature is re-enabled.