Introduction

If your scanner is failing to authenticate or access protected parts of your application, login errors will prevent the scanner from reaching anything beyond public-facing pages, leading to incomplete security assessments. If the application encounters any error when logging in, you will see an RCA displayed in the dashboard. This guide covers the most common causes and their solutions.

Prerequisites

• Your target must already be verified and in the Pending Setup stage.

• You must have a login sequence recorded using the Chrome DevTools recorder and exported as a JSON file.

• You must be a super admin to upload custom Puppeteer scripts, as they are critical for scan execution.

Instructions

Step 1: Implement IP Whitelisting (Recommended First Step)

The most common cause of login failure is a firewall, WAF, or security system blocking the scanner's automated requests. Always attempt this before any other fix.

Add Astra's static scanning IPs to your allow-list in each of the following:

• Application firewall

• Login system

• CAPTCHA provider

• MFA system

For the full list of Astra's static IP ranges, refer to Astra IP Ranges.

Step 2: Clean the Puppeteer Recording File

Errors during upload often arise from unnecessary actions captured during the recording process.

• Open the exported JSON file in a text editor such as VS Code.

• Remove browser-internal pages: delete any entries pointing to internal URLs such as "url": "chrome://new-tab-page/".

• Remove Meta key events: delete any keyDown or keyUp events associated with the Meta key.

• Clean the final step: locate the assertedEvents array in the very last step and delete its content, but do not delete the entire step.

• Once cleaned, save the file and re-upload it in Step 4 (Login Recording) of the scanner setup.

Step 3: Add Custom Pause Statements

If your website takes longer than usual to load due to network latency, the scanner may attempt to interact with elements before they are fully rendered, causing errors such as "Element Not Interactable," "Expected condition failed: waiting for presence of element," or "Element is not clickable at point."

• Download the login recording from the Astra dashboard and open it in a code editor.

• Insert the following custom pause step before any failing steps:

{
    "type": "customStep",
    "name": "pause",
    "parameters": {
        "target": "20000"
    }
}

• Adjust the target value in milliseconds based on your page load time (e.g., "20000" for 20 seconds).

Step 4: Bypass CAPTCHA Protection

Automated scanners cannot solve standard CAPTCHAs. If your login page is protected by CAPTCHA, use one of the following approaches:

• IP Whitelisting (Recommended): Add Astra's scanner IPs to bypass the CAPTCHA challenge entirely. This is the most secure approach.

• Disable CAPTCHA (Non-Production Only): Disable server-side CAPTCHA verification for the scanner. This can be disabled entirely or scoped specifically to Astra's scanner.

• HTTP Header Method: Capture an authenticated cookie from your browser and add it to the Extra Headers field in Scanner Setup.

Step 5: Bypass Two-Factor Authentication (2FA)

Automated scanners cannot handle dynamic SMS-based 2FA prompts. Use one of the following approaches:

• IP Whitelisting (Recommended): Add Astra's scanner IPs to bypass 2FA. This is the most secure approach for production environments.

• Static 2FA Code (Non-Production Only): Set a static OTP supported by your staging environment. This requires code-level changes in your application.

• Advanced TOTP: If using an authenticator app, export your recording as a Puppeteer JS file and raise a support ticket with your TOTP MFA secret so Astra can implement a custom script.

Expected Outcome

After successfully uploading a cleaned or configured file, the target status will change to Active. During a scan, the Login Recording stage in the progress bar should mark as successful with a checkmark, indicating the scanner has reached the authenticated areas of your application.

Related Tasks

• Incorrect Login Configuration: If you use the same domain for different modules (e.g., /admin vs /user) that require different login flows, configure them as separate targets.

• Duplicate Vulnerabilities: If you see duplicates in your results, check the scan results page to view unique findings for that specific scan.

• Requesting a Rescan: Once login issues are resolved and vulnerabilities are addressed, you can request an automated or manual rescan to verify your remediations.

• IP-Based Restricted Access: For applications restricted to specific IPs, you can also use a secret HTTP header to allow Astra's scanner to bypass your security rules.

• Support: If errors persist despite the above steps, create a support ticket via the dashboard widget, contact your account manager, or email help@getastra.com with steps to reproduce the issue and relevant screenshots.