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, followed by our guide to Authentication GoScripts.  The elements described in this guide are simply a component to use within an Authentication GoScript. 

Some login processes involve the use of email for receiving either One Time Passwords (OTPs) or single-use URLs ("Magic Links").  This can be achieved in GoScript by using an email address controlled by AppCheck ([anything]@ptst.io) which the GoScript system can access.

AppCheck provides 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, the generator has been used to create the address 378b5757-d74c-4fc8-a23e-f113aa4b8155@ptst.io.  The body of the latest email sent to this address can be seen at https://ptst.io/latest_email_by_to?to=378b5757-d74c-4fc8-a23e-f113aa4b8155@ptst.io.

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 scan to avoid conflicts.  See Selecting an Account for your Authenticated Web Application Scan.

Using GoScript's HTTP Mode we can retrieve a value from an email within a GoScript.  If we arrange for the OTP or Magic Link to be sent to that address we can therefore retrieve the email, extract the value and use it within the script.

• Overview
• Detailed Guide
• Examples

Overview

The process for setting up an authentication GoScript using email-based OTP or Magic Links 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 GoScript's HTTP Mode to retrieve the code from the email
   4. Use the value from that variable in the login form's OTP box, or use a go: command to visit the URL of the Magic Link.
   5. Finish the sign-in process.

Detailed Guide

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, for example pause: 10 to allow ten seconds for the email to be delivered.

The following GoScript snippet uses HTTP mode to make a request to the ptst.io email server and extract the token using a regular expression:

set mode: http
go: https://ptst.io/latest_email_by_to?to={username}
extractedValue := [re] {regex}

For example, using the email address generated above, and a simple Regular Expression (looking for a code):

set mode: http
go: https://ptst.io/latest_email_by_to?to=378b5757-d74c-4fc8-a23e-f113aa4b8155@ptst.io
extractedValue := [re] 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.

In another example, this uses a regular expression to select the first URL found in the email body:

set mode: http
go: https://ptst.io/latest_email_by_to?to=378b5757-d74c-4fc8-a23e-f113aa4b8155@ptst.io
extractedValue := [re] href=\"(.*?)\" 

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 extracted value is stored in a variable called extractedValue.

This value can then be used as a new target URL (in the case of a magic link), or as the input for a text box (in the case of a One Time Password).

For Example, to enter the value as a One Time Password in the "otp" field on the web page:

set mode: browser
otp = {extractedValue}

or to visit the URL of the Magic Link:

set mode: browser
go: {extractedValue}

In both cases, we first go back into browser mode.

Examples

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

One Time Password

A complete example auth.login function, using the email address stored in the {username} variable and a regular expression stored in the {regex} variable to extract an OTP and use it in the login process.

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

  # Give the email some time to arrive
  pause: 10

  # Switch to HTTP mode to retreive the OTP from the email without leaving the login form in the browser
  set mode: http
  go: https://ptst.io/latest_email_by_to?to={username}
  extractedValue := [re] {regex}

  # Go back to the browser to enter the code and finish logging in
  set mode: browser
  otp = {extractedValue}
  press: Enter
  wait for: Log out

Magic Link

A complete example script, using the email address stored in the {username} variable and  and a regular expression stored in the {regex} variable to extract a Magic Link and follow it.

def auth.login
  go: https://scanner.appcheck-ng.com
  wait for: AppCheck Login
  
  # Log in to the application to trigger the email
  username = {username}
  password = {password}
  click: Agree to Terms and Conditions
  click: Login
  wait for: You will shortly receive a login link via email

  # Give the email some time to arrive
  pause: 10

  # Switch to HTTP mode to retreive the magic link from the email without leaving the login form in the browser
  set mode: http
  go: https://ptst.io/latest_email_by_to?to={username}
  extractedValue := [re] {regex}

  # Go back to the browser to enter the code and finish logging in
  set mode: browser
  go: {extractedValue}
  wait for: Log out