Inserting Darwinium JS Profiling

This article primarily covers the configuration needed to dynamically insert Darwinium JavaScript profiling into pages when using a CDN (Edge) deployment.

On Edge deployments, this process is a Darwinium journey configuration task rather than a direct developer task.

• You may wish to first familiarise yourself with the Darwinium Portal, basics of Authoring Journeys and Deployment.
• For overview and context of the JavaScript Profiling see JavaScript Profiling
• If not on Edge/CDN deployment, see Tags Deployment for inserting and initiating JavaScript Tags manually.

Profiling Insert -> Collect Flow

Prior:

• Darwinium .journey.yaml configuration file has been created, built and deployed
• Journey file has been authored to define steps that create:
  • worker on GET request /loginpage to insert Darwinium profiling upon page load.
  • worker on the subsequent POST request /login to consume the resulting profiling and make decision.

Realtime User flow:

1. End user performs /loginpage GET request to load page.
2. On the response, the Darwinium Edge worker inserts the JavaScript profiling code directly into the page, at the location specified in journey configuration file.
3. User proceeds on page (eg. filling credentials)
4. Upon user initiating /login POST request (eg. login button pressed), the profiling code is stopped, and collects it as a protobuf encoded profileBlob.
5. The profileBlob is added as a header dwn-profiling to the /login POST request.
6. The Darwinium worker on the /login POST request route extracts the profileBlob from the dwn-profiling header of the request. The dwn-profiling header is not passed to the origin.
7. The profileBlob is decoded back into the useful profiling data when sent to Darwinium, and is available to use in risk decisioning and investigations on this Darwinium event.
8. (optional) While async by default, the journey configuration file can instruct the worker to wait for attributes like Darwinium JourneyID or risk score to run.
   1. those can then insert into header to the origin for consumption and decisioning.
   2. adding these dependencies do incur latency of the worker computation (eg. computing journey_id) or callout to Darwinium (full risk score)

Configuration

The below configuration will instruct Darwinium to insert and collect profiling against a page.

Install Snippet

1. Enter Workflows of Darwinium Portal and Install the Darwinium Profiling snippet
   1. Marketplace (right hand tabs) > Install. Snippets enable templated options while journey editing.
      
      
   2. The relevant files are downloaded into your workflows:
   • dwn_profiling.snippet: Enables option in journey config
   • fpjs > dwn_profiling.js: The actual JS profiling code that will be inserted.
     
     
2. Add the snippet to your journey.yaml file. (See Journeys)
   
   
   1. open the journey.yaml file > Configuration (top) > Snippets > Add snippet > ...
   2. specify the path to the snippet just installed. Likely dwn_profiling.snippet
   3. You may need to now close and reopen journey for snippet to take effect.

Page insert/extract config menu

1. Open your journey file and the step where profiling desired. It is recommended on GET requests, and to rerun profiling on multiple pages in the journey to detect anomalies
   

2. Go to Data Mappings > Response > Body Mappings. This is where we can instruct the worker to insert or extract things from the response request.

3. Set the configuration to expect a page

   1. Body Type -> Regular
   2. Body Rule -> With HTML/XML Path
   3. Mode -> html

4. This menu allows operations to be performed against locations in the page. The paths should be specified as XPath (see Injection and Extraction Menu)
   

Insert profiling into desired page location

Darwinium recommends inserting profiling in the head with XPath

/html/head

or if performance a concern and willing to trade off quality and presence of that profiling

/html/body

See JavaScript profiling.

6. If the snippet was installed successfully, you will get option in drop down to Inject darwinium profiling
   

Configure the profiling template

The template has options to configure, based on:

1. the structure of the GET request page being inserted into
2. the request intended to collect and transmit the profiling on
   Hover the (i) for inline help.

Application HTTP Requests
What type of request is expected to add the collected profiling to?
Tip: using developer console network tab can isolate the Type of the intended request.

• XMLHttpRequest: JS is attached to window.XMLHttpRequest that inserts a header named dwn-profiling into the request. XMLHttpRequest is also known as Ajax
• fetch: JS is attached to window.fetch that inserts a header named dwn-profiling into the request.
• none: dwn-profiling is inserted as a new form input field on HTTP form POST requests.

Fetch/xhr URL Restricted to

Use this parameter to restrict the injection of the dwn-profiling header in application XMLHttpRequest or fetch requests. That is important if the site enforces and rejects requests containing unexpected headers.

• For fetch and XMLHttpRequest: This is the URL prefix of the request to collect profiling on, often a POST. Profiling data will only be inserted to fetch or XMLHttpRequest requests that are made to this URL. e.g. /example/login
  • URL query parameters are ignored as part of the URL restriction.
• For form posts: This is not used and should be set to none as best practice.

Note

• none will disable HTTP header injection on all requests.
• any means all requests to the same domain will have profiling headers injected. You can use this when there could be multiple different follow on POST requests and comfortable that dwn-profiling header will be added to any follow on request.

Form Post CSS Selector

• For HTTP form post requests: Restricts dwn-profiling form post injection to only ones that match the configured CSS selector.
• Example: Any of the following CSS Form Selectors would work

form#my_form_id
form[action='/example/post']
form[method='post']

For the following HTML form
<form action="/example/post" method="post" id="my_form_id"/>

You should use a CSS selector that identifies the intended form(s) and will likely be robust to page changes. If no form with the CSS selector is found it will fail open, but profiling will not be attached to any request anymore.

• For XMLHttpRequest and fetch: This is not used and should be set to none as best practice.

Enable Keyboard Biometrics
Default = true

Leave on if intention to collect behavioural biometrics data about how the user types and interacts with mapped input text field, including:

• Cadence
• Shortcut Usage (autofill, paste, copy, cut)
• Navigations (tabs, arrows, backspaces, deletes)
  And generating Darwinium behavioural signatures.

Enable Mouse Biometrics
Default = true

Leave on to collect mouse stroke data including: Clicks (left, right, middle, scroll click), Num movements, Movement profile (curvature, inflexion, distance), Movement timing (dwell time, move/scroll interval, speed)
Mouse off screen.

Enable Touch Biometrics
Default = true

Leave on to collect tap data on mobile browsers including: Tap profiles (size, pressure, radius), Num swipes, Swipe profile (left/right handedness, curvature, inflexion, distance), Swipe timing (dwell time, move/scroll interval, speed)

Enable Sensor Biometrics
Default = true

Leave on to collect sensor data on mobile browsers including: Accelerometer
Gyroscope, Magnetometer, Proximity sensor, Light sensor

Enable Geolocation
Default = false

Use the Geolocation API to request user precise location. This is very useful as a trust indicator and more accurate than other forms of browser geolocation profiling by utilising combination of GPS, WIFI and IP.

Enable Device Sensor (mainly for iOS)
Default = false

Leave on to collect sensor data on iOS devices.

Single Page App/Shadow DOM Support
Default = false

Select this option only if your form or keyboard input elements are:

• Dynamically rendered via JavaScript (as part of a single page application)
• Nested beneath a Shadow DOM on a page.
• This option can be false when neither of those are true, or also if keyboard biometrics is disabled.

Add keyboard biometrics contexts (optional)

A small but separate JS code snippet is inserted for additional profiling of keyboard interactions against specific input text fields on the page.

1. In same insertion menu, add a new line with +
2. As with profiling, Insert into desired location on page (recommend /html/head)
3. Select Enable Keyboard Biometrics On Input Field... from dropdown
   

In CSS Input Selector of the Input Field

• The CSS Input Selector of the input field on the page to which Darwinium Keyboard Biometrics will be attached.
• The CSS Selector must be explicit enough to select only the correct input field. Care must be taken to ensure that the CSS Selector does not match multiple input fields on the page.
• Example CSS Input Selectors:

input#my_email_id
input[name='email_example']
input[id='my_email_id']
input[type='email']

For the HTML Input:
<input type="email" id="my_email_id" name="email_example"/>

Tips:

• Right click > inspect element on the input fields of interest to find their properties
• Use web developer console to confirm validity of CSS selector in isolating an input field

document.querySelector("input[id='my_email_id']")

Context of the Input Field
Choosing which Darwinium CONTEXT to assign the input field. These are from a fixed list and should match the purpose of the field as close as possible. The CONTEXT are used to search for the keyboard biometrics attributes associated with that text field.

ACCOUNT_NUMBER
ADDRESS_STREET1
ADDRESS_STREET2
ADDRESS_STREET3
BANK_ACCOUNT_NUMBER
BANK_ACCOUNT_ROUTING_NUMBER
CREDIT_CARD
CURRENCY_AMOUNT
DATE_OF_BIRTH
DRIVERS_LICENSE
EMAIL
FIRST_NAME
FULL_NAME
GENERAL_PURPOSE_ONE
GENERAL_PURPOSE_TWO
IBAN
LAST_NAME
LOGIN
PASSWORD
POLICY_NUMBER
SOCIAL_SECURITY
TELEPHONE
USER_NAME

Deploying the JS profiling to live

The instruction to insert the profiling code will now be compiled upon next commit and build of this journey, and made live upon the deploy of that build.

See Deployment

The Darwinium edge worker will insert the JS (found in fpjs > dwn_profiling.js) into the page on the GET request step, and collected and transmitted in either Header or form body of the subsequent request.

You can verify the profiling is inserted by:

1. inspecting the contents of the page for the Darwinium JS fragments
   In <head>:
   
   Main Darwinium JS profiling
   
   Behavioural biometrics keyboard context tagging of the email input field
   In <form>:
   
   For form, dwn-profiling form input field that will be inserted

2. Observing POST to aps.wowscale.com. This is Darwinium's packet filtering profiling domain that performs a subset of the connection profiling.
   
   
   
   

You can verify dwn-profiling header is being collected on the request by:

1. In network tab, checking the Header (or Body if form) of the follow on request, usually POST:
   

2. Checking in Darwinium Portal that profiling.javascript attributes are being populated. Example search:

profiling.javascript.os != null

Additional profiling resources

See JavaScript profiling for additional considerations

See Tags deployment for inserting JavaScript Tags manually