Note: This guide assumes existing familiarity with GoScript.  If you have not used GoScript before then it is recommended to start with our basic GoSCript Guide: A Guide to GoScript.

AppCheck has a system for returning the body of the last emailed received at a given @ptst.io email addresses:

https://ptst.io/latest_email_by_to?to=[email address]

You can generate a unique email address using https://ptst.io/generate_random_account.

For example, using the generator I have created the address 378b5757-d74c-4fc8-a23e-f113aa4b8155@ptst.io.  To access the latest email sent to this address use https://ptst.io/latest_email_by_to?to=378b5757-d74c-4fc8-a23e-f113aa4b8155@ptst.io.

Note: If you are setting up multiple scans that will run concurrently against the same authentication system then it would be best to use a unique email address for each one to avoid conflicts.  See Selecting an Account for your Authenticated Web Application Scan.

Using a pre-written GoScript function (which uses JavaScript to perform an HTTP GET request) we can retrieve an email within a GoScript.  If we arrange for an MFA code to be sent to that address we can therefore retrieve the email, extract the code and use it within the script.

Overview

The process for setting up an authentication GoScript using email-based OTP is as follows:

1. Register a new, unique email address using the generator at https://ptst.io/generate_random_account.
2. Use this email address to register an account with the target application.
3. In GoScript:
   1. Use the chosen email address to log in, triggering the target application's MFA system so that it emails that address.
   2. Wait for the email to come through.
   3. Use the pre-written GoScript function from this guide, which uses JavaScript to:
      
      1. Retrieve the contents of the email from https://ptst.io/latest_email_by_to?to=[email address].
      2. Extract the OTP code.  The pattern required to extract the token will vary between MFA systems, but an example can be seen in the script below.
      3. Save the OTP code to a window object.
   4. Wait until that window object has been written.
   5. Use the value from that variable in the login form's OTP box.
   6. Finish the sign-in process.

Detailed Guide

A GoScript function, getOTPFromEmail, to retrieve the OTP code (steps 3.2.x above) is included in the example at the end of this guide.  You can copy this function directly in to your own GoScript.

Note: The order of the functions within your script does not matter.  You can paste the getOTPFromEmail function before or after your auth functions.

IMPORTANT: You will need a pause between logging in and getting the token from the email. If you do this too quickly you might end up taking the token from the previous email. pause: 10 will usually suffice.

The function requires two arguments.  The first is the email address being used; the second is a regular expression which extracts the OTP code from the body of the email.  This regular expression will need to be written specifically for the particular MFA system being used.

This GoScript command sends your email address and Regular Expression to the getOTPFromEmail function:

getOTPFromEmail: [email address] /[regular expression]/

For example, using the email address generated above, and a simple Regular Expression, I would call the getOTPFromEmail function like this:

getOTPFromEmail: 378b5757-d74c-4fc8-a23e-f113aa4b8155@ptst.io /code\sis:\s([0-9\s]+)\n/

This Regular Expression looks for the string "code is: " followed by a series of numbers and white-space, followed by a newline character.  The numbers and white-space are in a pair of brackets () and so they form the first Regular Expression capture group.  The contents of the capture group, not the whole matched string, are extracted and used as the OTP code.

Note: Since the arguments are separated by spaces, they cannot include spaces within them, which is why in this example I've used \s in the Regular Expression.

The function stores the resulting OTP code as a variable in the window object called otp_code.

To retrive the code for use within your GoScript, first wait for it to be written to the window object:

wait for: js: window.otp_code

Then save it as local GoScript variable:

oneTimePassword := js: window.otp_code 

Finally, to use this token in a form on the target login page (where the field in the form is called "otp"):

otp = {oneTimePassword}

Example

A complete example script, using the email address stored in the {username} variable, and the regular expression described above:

def auth.login
  go: https://scanner.appcheck-ng.com
  wait for: AppCheck Login
  
  username = {username}
  password = {password}
  click: Agree to Terms and Conditions
  click: Login
  wait for: You will shortly receive a verification code via email

  pause: 10

  getOTPFromEmail: {username} /code\sis:\s([0-9\s]+)\n/
  wait for: js: window.otp_code
  oneTimePassword := js: window.otp_code
  otp = {oneTimePassword}
  press: Enter
  wait for: Log out

def getOTPFromEmail emailAddress pattern
  js:
    function getLatestEmailByAddress(address) {
      var request = new XMLHttpRequest;
      request.open("GET", "https://ptst.io/latest_email_by_to?to="+address, !1);
      request.send();
      try {
        return JSON.parse(request.responseText).message_payload
      } catch (e) {
        console.error(e)
      }
    }

    var match = String(getLatestEmailByAddress("{emailAddress}")).match({pattern});
    if (match) {
      code = match[1];
      code = code.replace(/\s+/g, '');
      window.otp_code = code; 
    }

The section in bold does not require any changes and can be copied directly into your own GoScript.  You will only need to complete the auth.login function as detailed above, and add auth.confirm and auth.logout functions as described in Authentication GoScripts.

Note: The getOTPFromEmail function removes white-space before, after, and within the OTP code. If this is not desired for your MFA system, you will need to modify the function, removing/commenting out the line:

code = code.replace(/\s+/g, '');