Authenticated scans

Ostorlab supports authenticated scans of mobile applications, web applications, and their backend servers. Credentials can be set at scan creation with the "+ Test Credentials" button of the "Test Credentials" step.

What do I need before I start?

You need a test account on the target, its credentials, the 2FA details if the login asks for a code, and network access from the scanner to the target.

A test account on the target. We recommend a dedicated test account that does not lock out after failed logins.
The credentials for that account. For example a login and password, or a Puppeteer script for a login flow with several steps. See Which credential types can I add?.
The 2FA method, if the login needs one. Some methods need preparation, such as a dedicated testing phone number for SMS. See How do I handle OTP and MFA?.
Network access to the target. See What network access does the scanner need?.
For a mobile scan, the application. Upload an APK or AAB file for Android or a non-encrypted IPA file for iOS, or scan the application from the store.

Which credential types can I add?

You can add Login & Password, Custom Credentials, Basic Authentication, Script, Certificate and HTTP Headers credentials, plus four 2FA types (SMS, Email, TOTP and Manual). The table below describes each one.

When creating a scan, click + Test Credentials in the Test Credentials step.

Add Test Credentials Button Location

A menu will appear with the credential types. You can add several test credentials to the same scan.

Test Credentials Configuration Menu

You can also manage credentials from the Test Credentials page (Scanning > Test Credentials in the menu), then select them when you create a scan. The following credential types are available:

Type	Use it for
Login & Password	A simple authentication flow that requires a username and a password.
Basic Authentication	Targets that use the HTTP Basic Authentication scheme.
Certificate	A TLS/SSL client certificate for mutual TLS. For mobile applications, the certificate must be in the PEM format.
Script	A Puppeteer script for complex authentication flows or interactions like checkout.
Custom Credentials	Key-value pairs for custom form fields, such as username, password and domain name.
HTTP Headers	Headers such as `Authorization` or `User-Agent`, commonly used by APIs.
2FA SMS, 2FA Email, 2FA TOTP, 2FA Manual	A login that asks for a one-time code. See How do I handle OTP and MFA?.

Login and Password Input Fields

For a full web walkthrough, see Authenticated Web Scan. The Web Deep Agentic Scan, Mobile Deep Agentic Scan and Multi Asset Scan guides include the same credentials step.

Web App Authentication with Puppeteer Script / Chrome Recorder

If you have web applications that require a more complex authentication flow, you can upload Puppeteer scripts that will be executed during the scan. These scripts can be generated using the Chrome DevTools Recorder. See Scan Web App with Chrome's Recorder Puppeteer Script.

Puppeteer Script Upload Interface

For mobile applications that require authentication with a certificate, you can upload your certificate. The certificate must be in the PEM format.

Certificate Authentication Option

Upload your certificate.

Certificate Upload Dialog

How do I handle OTP and MFA?

Add a 2FA credential next to the login credential: SMS, Email, TOTP or Manual.

You create each one from Scanning > Test Credentials > New Credential. Choose the method that matches how your application sends the code:

Method	What you provide	Key condition
2FA SMS	The Sender Phone Number your application sends OTP messages from.	Contact Ostorlab Support for a dedicated testing phone number, and set it on the test account.
2FA Email	The Email Sender address, and the test mailbox's email address and password.	IMAP/SMTP access must be enabled on the mailbox. If the mailbox provider enforces 2FA, use an App Password, not the regular password.
2FA TOTP	The Base32-encoded TOTP Secret (seed).	Enable TOTP on the test account and keep the seed from the authenticator setup.
2FA Manual	A Sender reference label.	The scan pauses at the 2FA step. You enter the code from the scan details, and the scan stays paused until you do.

For step-by-step instructions, see Two-Factor Authentication (2FA) for Automated Scans.

Complex Authentication Schemes for Mobile Applications

Complex authentication schemes like OTP or the random numerical pad are either automated using Appium scripts or manually performed for one-offs by an Ostorlab support member. If your application requires a custom authentication scheme, please get in touch with us by email: support@ostorlab.dev for advice.

Can I test with more than one user role?

You can add several test credentials to one scan. Login and password credentials also accept an optional role value, which you can set in the UI, through the API or in the CI integrations.

In the UI, you can add several test credentials to one scan, and give each login and password credential a "Role".
In the API, a scan takes a list of credential IDs (credentialIds), and you set the role in the role field of the LoginPasswordTestCredentials type. See API.
In CI integrations, you can pass a role with the login and password:
- GitLab: OSTORLAB_CREDENTIALS takes a semicolon-separated list in the format login,password,role,url. The role and URL are optional for mobile scans.
- Bitrise: --test-credentials-role is an optional role field, used with --test-credentials-login and --test-credentials-password.

What network access does the scanner need?

Allowlist the scanner IP addresses so that WAFs and firewalls do not interfere with the scan. If the target is not internet facing, use a reverse proxy or an on-prem scanner; see Scanning Internal Web Applications.

Open the scan's Call Coverage and review the requests and screens to confirm the scanner logged in and reached protected areas.

To open it, see Check Call Coverage.
For 2FA logins, see Validating Results.

If the scanner does not get past a flow with several steps, you can guide it with UI Prompts. UI Prompts are natural language instructions for multistep actions such as account creation. The Call Coverage of the scan shows the UI Prompts it used.

Most failed logins come from one of four causes: the scanner cannot reach the target, an SMS or email code is not captured, the scan is paused on a Manual 2FA step, or the flow is too complex for a login and password. Find the matching case below.

The scanner cannot reach the target

Check the allowlist and the internal access options in What network access does the scanner need?.

The SMS code is not captured

Make sure the test account has SMS 2FA enabled.
Confirm your application's anti-spam or rate-limiting policies allow incoming messages from the gateway.
Check that the Sender Phone Number exactly matches the number shown on the device when an OTP is received.

The email code is not captured

Make sure the email body shows the code in a clear, readable format.
Verify that IMAP/SMTP access is enabled on the mailbox and that the credentials, especially the App Password, are correct.
Make sure the mailbox is not protected by an additional 2FA layer that stops the scanner from logging in to it.

The scan is paused

A 2FA Manual credential pauses the scan until you enter the code. Open the scan details and submit the token, as described in Entering the Token.

The login flow is too complex for a login and password

For web applications, record the flow as a Puppeteer script.
For multistep flows, add UI Prompts.

If your application uses a custom authentication scheme, or the login still fails, contact us at support@ostorlab.dev.