GoScript is a scripting language that can be used to describe browser interactions, and is an advanced feature unique to AppCheck, combining the power of automated scanning with the guidance of a human to step through complex user journeys and processes.

GoScript can be used to model complex journeys in order to test deep into the application and access screened application portions (such as areas that require authentication).

Some example uses include:

• Authenticating the scanner in your application, including Single Sign On (SSO) and some (but not all) Multi-Factor Authentication (MFA) solutions.  See Authentication GoScripts for more information on this, after familiarising yourself with the basic of the language, below.

• Navigating complex flows involving multiple stages, forms or screens, navigating them like a user would, eg sign-up flows; purchases/shopping cart journeys.

• Submitting forms that require specific, known input, which the scanner would be unlikely to guess (eg the user must type a valid ID number).

• Improving scanning of single page applications by going through targeted processes as opposed to clicking blindly.

Contents

• How GoScript Works
• Identifying Page Elements
• Basic Example
• Commands
• Functions
• Saving and Testing GoScripts

How GoScript Works

A GoScript is a series of commands, one per line, that tell the scanner to perform an action within a web browser.  Most commands take the form:

[instruction]: [target element]

eg

click: Add to Basket

In this example the GoScript engine will try to identify an element on the current page matching the text "Add to Basket" and click on that element.

The GoScript engine (part of the AppCheck scanner) goes through these commands, in order, using a standard web browser (there are some AppCheck customizations, but its behaviour should be exactly like that of a normal browser with a human user).

When writing GoScripts remember that they run in an ordinary web browser.  A human could follow the same script and acheive the same results.  It is helpful to think of your script as simply a series of steps that a user with a browser follows.

Identifying Page Elements

The GoScript engine uses various identifiers to find the item you're describing.  These include the element's ID, name, label, content, adjacent text, and more.  For example, if the text "Add to Basket" appears on the page next to a button, and you tell GoScript to click "Add to Basket", the GoScript engine will assume it's the button, not the text, that you want to click.

In this example we use the text that appears directly on the button:

click: Add to Basket

The matching process is not perfect, and sometimes the GoScript engine will not find the element you're after.  In these cases, or if you simply want to be very specific, you can use a CSS selector or XPath to specify the target element, eg

click: #some_objects > span:nth-child(2) > i:nth-child(1)

You can get a selector/xpath for an element by selecting it in your web browser's Developer Tools -> Inspector then selecting Copy -> Selector/XPath (the exact name of these options varies between browsers).

 \#pwd = ThisIsNotMyPassword

Basic Example

This example uses the scanned application's search facility to locate an item, select it and add it to the shopping basket.

# Search for a specific book
go: http://www.amazon.co.uk/
searchtextbox = Grey hat hacking book 3rd
click: Go

# Go to the book's product page
wait for: the ethical hackers handbook
click: Gray Hat Hacking The Ethical Hackers Handbook, 3rd Edition
wait for: Thwart malicious network intrusion by using cutting-edge

# Add it to our basket
click: Add to Basket
wait for: Added to basket

# Begin checkout process
click: Proceed to checkout
wait for: Create your Amazon account
email = test@tesing.com
password = Password123
# End of example

You can insert blank lines to make your script easier to read - this will have no effect on how the script runs.  I like to use blank lines to break up a script into logical sections.

Commands

#

# These three lines are just comments and have no effect when the GoScript
 # runs. The fourth line is not a comment, it is a real GoScript command,  
 # because the hash character (#) is not the first non-space character:
click: #some_objects > span:nth-child(2) > i:nth-child(1)

go:

go: http://www.example.com

wait for:

wait for: Welcome

=

# This example includes the username "joe" directly within the script.  The value "joe" 
 # is applied to the form field identified as "username".  This could be the form
 # field's ID, name, label, adjacent text, etc.  The GoScript engine will try a number
 # of ways to find a matching form field.
username = joe

# This example uses a variable to import the value of {password} from the scan configuration
 # and applies it to the form field identified as "passwd".
passwd = {password}

click:

# This example uses the text "Log In" which could match various attributes
# of an element on the page.
click: Log In

# This example uses a selector which uniquely identifies a specific element.
click: #some_objects > span:nth-child(2) > i:nth-child(1)

hover: 

hover: Log In

press:

press: enter

type:

type: QWERTY

pause:

pause: 15

js:

# Single-line examples:
js: document.getElementsByClassName('form-control')[0].value = 'test';
js: document.querySelector('#some_object > span').click();
js: someFunction();

# Multi-line example:
js:
  var myElement = document.getElementsByClassName('form-control')[0];
  myElement.value = 'test';
  document.querySelector('#some_object > span').click();
  someFunction();

Commands which search for and interact with an element, such as click: or the = command, will wait a number of seconds for a matching element to be found.  The commands (and therefore the script) will fail if no matching element appears.  You can think of this as a built in wait for: command.

Functions

Functions are mostly used in Authentication GoScripts, in which case you use specific function names as described in the linked guide.  You can also write your own custom functions, though it is very rare for this to be required by an end user (it is mostly found in scans configured by AppCheck engineers).  If you ever do need to write your own custom functions, see Custom Functions in GoScript.

Functions can written by using the keyword "def " and the name of the function to begin it:

def myFunction

and then indent the function contents:

def myFunction
  # First line of function

When you stop indenting, you've ended that function:

def myFunction
  # First line of function
# This line is not part of myFunction

Saving and Testing GoScripts

You can write, test and save your scripts at https://scanner.appcheck-ng.com/goscript.

Once it is verified as working you can import the script into a scan configuration using the Import GoScript button in the Authenticated Scanning section (for Authentication Scripts) or the Advanced Settings section (for workflow GoScripts) of the Web Application Scanner Settings (or just copy-paste it into the appropriate box).

When testing the script it will be marked as Passed if no GoScript command failed. You must write your script in such a way that it will fail if it did not achieve the desired result. For example: the command to go: to a page that does not exist may not fail, because the command may succeed in loading the returned page even if it is a 404 page or a redirect. You will need a wait for: command after the go: command, which fails if an expected string is not present.

When you import a script into a scan the scan now has its own copy of the script.  Changes made at /goscript will not alter the version saved in the scan.