Skip to content

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 form-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
    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
    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
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.
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 Default 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