Browser Actions Authentication with Escape¶

Description¶

The Browser Actions authentication preset is ideal for scenarios where Browser Agent authentication method falls short, as it leverages browser actions to perform login tasks. This preset is especially effective for form-based authentication where inputs are provided directly. Contrary to the Browser Agent preset, this preset does not use an AI Agent to perform the actions, but rather a browser automation actions based on Playwright actions and locators. 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_actions
    login_url: https://example.com/login
    logged_in_detector_timeout: 10
    users:
    -   username: frontend-user@example.com
        actions:
        -   action: fill
            auto_submit: false
            locator: input[name="username"]
            value: user@escape.tech
        -   action: fill
            auto_submit: false
            locator: input[name="password"]
            value: password123
        -   action: check
            locator: input[type="checkbox"]
        -   action: select
            locator: select#country
            value: France
        -   action: click
            locator: button[type="submit"]

presets:
-   type: browser_actions
    login_url: https://example.com/login
    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
        actions:
        -   url: https://example.com/login
            action: goto
        -   action: fill
            auto_submit: false
            locator: input[name="username"]
            value: user@escape.tech
        -   action: fill
            auto_submit: false
            locator: input[name="password"]
            value: password123
        -   action: check
            locator: input[type="checkbox"]

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 to perform the login on
`type` *	`Const[browser_actions]`	`browser_actions`
`users` *	`List[`BrowserActionsUserPreset`]`		The list of users to generate tokens for.

Objects¶

BrowserActionsUserPreset¶

Property	Type	Default	Description
`actions` *	`List[`CheckAction`,`ClickAction`,`FillAction`,`FocusPageAction`,`GotoAction`,`SelectAction`,`SleepAction`,`WaitElementAction`,`WaitTextAction`]`		The actions to perform on the browser
`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.
`username` *	`string`		The username of the user.

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

CheckAction¶

Property	Type	Default	Description
`action` *	`Const[check]`	`check`
`locator` *	`string`		The selector of the checkbox to check

ClickAction¶

Property	Type	Default	Description
`action` *	`Const[click]`	`click`
`locator` *	`string`		The selector to click on

FillAction¶

Property	Type	Default	Description
`action` *	`Const[fill]`	`fill`
`auto_submit`	`boolean`	`false`	Whether the form should be automatically submitted after the fill action
`locator` *	`string`		The selector to fill
`value` *	`string`		The value to fill in the field

FocusPageAction¶

Property	Type	Default	Description
`action` *	`Const[focus_page]`	`focus_page`
`url_pattern` *	`string`		The pattern to find in the URL to focus on a page. Should be a regex allowing to match the page using Python `re.findall()`.

GotoAction¶

Property	Type	Default	Description
`action` *	`Const[goto]`	`goto`
`url` *	`string`		The URL to navigate to

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

SelectAction¶

Property	Type	Default	Description
`action` *	`Const[select]`	`select`
`locator` *	`string`		The selector of the dropdown to select from
`value` *	`string`		The value to select

SleepAction¶

Property	Type	Default	Description
`action` *	`Const[sleep]`	`sleep`
`seconds` *	`number`		The time to sleep in seconds

WaitElementAction¶

Property	Type	Default	Description
`action` *	`Const[wait_element]`	`wait_element`
`locator` *	`string`		The selector to wait for
`timeout`	`number`	`10`	The timeout (seconds) to wait for the element to be visible

WaitTextAction¶

Property	Type	Default	Description
`action` *	`Const[wait_text]`	`wait_text`
`timeout`	`number`	`10`	The timeout (seconds) to wait for the text to be visible
`value` *	`string`		The text to wait for until visible, case-insensitive

Enums¶

BrowserLocation¶

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

HTTPLocation¶

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