Browser Agent Authentication with Escape¶

Description¶

The Browser Agent authentication preset is ideal for scenarios where traditional authentication methods fall short, as it leverages browser actions to perform login tasks. This preset is especially effective for frontend-based authentication where inputs are provided directly. This preset uses an AI Agent to automatically perform the actions to log you in with the provided credentials. By default, the preset automatically extracts cookies, localStorage andsessionStorage from the browser. If your scan is a Frontend scan, everything will be injected into the scanner's engine, to clone the browser behavior. If your scan is an API scan, only the cookies will be injected. If your authentication process stores credentials in local/session storage and you need to authenticate an API, be sure to configure the extractions and injections parameters accordingly.

Examples¶

presets:
-   type: browser_agent
    login_url: https://auth.example.com/login
    logged_in_detector_timeout: 10
    users:
    -   username: frontend-user@example.com
        password: pass
        additional_fields:
        -   auto_submit: false
            locator: company
            value: Escape

presets:
-   type: browser_agent
    login_url: https://auth.example.com/login
    logged_in_detector_text: Welcome back user(user@example.com) !
    logged_in_detector_timeout: 10
    injections:
    -   key: Authorization
        location: header
        prefix: 'Bearer '
        variable: access_token
    extractions:
    -   name: token
        jq: .token
        key: token
        location: browser_local_storage
        origin: https://auth.example.com
    users:
    -   username: api-user
        password: pass

Extensive Configuration¶

Property	Type	Default	Description
`auto_extraction_urls`	`List[string]`	`null`	The API URLs to auto-extract requests headers from.Extracted headers will be injected automatically into every single authenticated request sent by the scanner.This is particularly useful when authentication API scans using Browser-based authentication.
`extractions`	`List[`BrowserExtraction`]`	`null`	The extractions used to extract from the browser like `page`, `browser_local_storage`, `browser_session_storage`, or `browser_cookies`.
`injections`	`Union[`BrowserInjection`,`HTTPInjection`]`	`null`	The injection configuration used to inject the tokens into either the HTTP requests, or another browser for Frontend scans.
`logged_in_detector_text`	`string`	`null`	The text to detect in the last page to validate the user is logged in, case-insensitive
`logged_in_detector_timeout`	`integer`	`10`	The timeout to wait for the logged in text to be detected (in seconds)
`login_url` *	`string`		The url that presents the login form
`type` *	`Const[browser_agent]`	`browser_agent`
`users` *	`List[`BrowserAgentUserPreset`]`		The list of users to generate tokens for.

Objects¶

BrowserAgentPresetAdditionalFillAction¶

Property	Type	Default	Description
`auto_submit`	`boolean`	`false`	If true, the field will be submitted automatically after being filled
`locator` *	`string`		The locator that will be used to get the value of the field
`value` *	`string`		The value that will be used to set the field

BrowserAgentUserPreset¶

Property	Type	Default	Description
`additional_fields` *	`List[`BrowserAgentPresetAdditionalFillAction`]`		Additional fields to be used in the login form in the form `selector`:`value`
`cookies`	`Dict[string, string]`	`null`	Optional cookies injected during the authentication process and in authentified requests.
`headers`	`Dict[string, string]`	`null`	Optional headers injected during the authentication process and in authentified requests.
`password` *	`string`		The password that will be used to auto login
`username` *	`string`		The username or email that will be used to auto login

BrowserExtraction¶

Property	Type	Default	Description
`jq`	`string`	`null`	The jq expression to extract the value from the session storage item
`key` *	`string`		The key to use for the extracted value, depending on the location. In the case of Page location, this represents a Playwright selector
`location` *	BrowserLocation		The location of the browser where the value should be extracted.
`name` *	`string`		The name of the variable to store the extracted value into that will be used for injection
`origin` *	`string`		The URL of the page, origin of the local/session storage, or cookies where the value should be extracted.
`regex`	`string`	`null`	The regex to use to extract the token from the key value. By default the entire value is taken.

BrowserInjection¶

Property	Type	Description
`key` *	`string`	The key to use for the injected token. Its usage depends on the location.
`location` *	BrowserLocation	The location of the browser where the token should be injected
`origin` *	`string`	The origin of the local storage or session storage where the token should be injected
`variable` *	`string`	The name of a variable to retrieve to create the token's value. If not provided, the token will be infered as the first successful extraction of the procedure

HTTPInjection¶

Property	Type	Default	Description
`key` *	`string`		The key to use for the injected token. Its usage depends on the location. For headers, cookies,and query parameters, this key describes the name of the header, cookie or query parameter. For a body location, the key is the field where the token should be injected within the request bodies
`location` *	HTTPLocation		The location of the HTTP request where the token should be injected
`prefix`	`string`	`null`	A prefix to prepend to the token before it is injected
`variable` *	`string`		The name of a variable to retrieve to create the token's value. If not provided, the token will be infered as the first successful extraction of the procedure

Enums¶

BrowserLocation¶

Value
`page`
`browser_local_storage`
`browser_session_storage`
`browser_cookies`

HTTPLocation¶

Value
`header`
`cookie`
`body`
`query`