A Guide to GoScript

GoScript is a scripting language that can be used to describe browser interactions, and is an advanced feature unique to Appcheck, combing 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) soltutions.

• 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.

 

How GoScript Works

A GoScript is a series of commands, one per line.  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" using various identifiers including the element's ID, name, label, content, adjacent text, etc.  If you have the text "Add to Basket" next to a button the GoScript engine will assume it's the button, not the next, that you want to click.

It will then click on that element.

This matching process isn't 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 full selector to specify the target element, eg

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

Tip: You can get a selector for an element by selecting it in your web browser's Developer Tools -> Inspector then selecting Copy -> Selector (the exact name of this option varies between browsers)

Note: Some instructions, such as the equals (=) instruction, have the target on the left hand side.  In this case you cannot use a selector starting with a hash (#) since the line would then be interpreted as a comment

 

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 techniques

# 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 = [e-mail]
password = Password123

# End of example

Tip: 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

Instruction	Description	Examples
#	A line beginning with # is a comment.  This is used for adding notes to a GoScript and has no effect when the GoScript runs.	#This is a comment.  It has no effect when the GoScript runs.
go:	Tell the browser to go directly to the given URL as though by entering it into the address bar (ie not by interacting with any element on the existing page)	go: http://www.example.com
wait for:	Wait for a given string to appear on the page	wait for: Welcome
pause:	Wait a given number of seconds	pause: 15
=	Set the value of a field.  You can use {username} and {password} to access the credentials set in the scan configurations. Note: Spacing is important - make sure you include a space on either side of the = as shown in the examples.	#This example includes the username directly within the script. username = joe #This example uses the {} placeholder, and therefore imports the #password from the scan configuration at run-time. password = {password}
click:	Find a page element and trigger a 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)
press:	Press the specified key	press: enter
type:	Press a series of keys, useful for entering text and triggering listeners	type: QWERTY
js:	Run the following JavaScript	js: document.getElementsByClassName('form-control')[0].value = 'test'; js: someFunction();

Authentication GoScripts

An Authentication GoScript contains two functions, auth.login and auth.confirm.  Use the keyword "def" and the name of the function to begin it, and then indent the function contents.  When you stop indenting, you've ended that function.  Tip: the example below should make this clearer.

auth.login is used to authenticate with the application, beginning an authenticated session.  It should end with a "wait for:" command that looks for a string that appears once authentication has completed.  If that string does not appear, the script will fail, and the scanner will know that authentication was not successful.

auth.confirm is run periodically to test whether the session is still authenticated.  It should end with a "wait for:" command that looks for a string that appears only when logged in.  If that string does not appear, the script will fail, and the scanner will know that it is not logged in. 

{username} and {password} can be used instead of storing the actual credentials in the script.  These placeholders will be replaced with the credentials from the scan configuration at runtime.  This is good practice and allows you to share/re-use scripts without sharing credentials.

If auth.confirm completes successfully then the scanner proceeds with the scan; if auth.confirm fails then the scanner runs auth.login again.

Example:

def auth.login
  go: https://www.website.com
  wait for: Forgot password?

  username = {username}
  password = {password}
  click: Login
  wait for: My Account

def auth.confirm
  go: https://www.website.co.uk
  wait for: My Account
  # The above "wait for" command will time out if "My Account" does not
  # appear on the page within 30 seconds.  This counts as a failure,
  # which tells the scanner that it needs to run auth.login again

Tip: The first line of auth.login is often go: to the target site's root URL, and the last line is often wait for: a string which appears only when logged in.  That's what we need to do to test that we're still logged in!  That means these two lines can often be re-used for the auth.confirm function, as seen in the example above.  This is a common pattern.

Note: Some applications, particularly Single Page Applications (SPAs), use data submitted with each request to maintain the session, so navigating to a page using the browser's address bar will log you out.  In these situations avoid using go: commands - instead look for an element which always appears and click: it.  This is often the company logo in the top left, which might take you back to a dashboard for example, and this can be used to confirm you're still logged in:

def auth.confirm
  click: #company_logo
  wait for: My Dashboard
  #In this example if the GoScript engine cannot see an element with ID company_logo,
  #or if clicking it does not take us to a page containing "My Dashboard", then the
  #function fails, and the GoScript engine knows it is logged out and that it should
  #run auth.login again.

 

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 approriate box).

When testing the script it will be marked as Passed if no component failed.  If writing an authentication script you want it to fail if it was not able to log in, so you should "wait for:" a string that only appears when logged in - the tester will time out (and fail) if that string does not appear in 30 seconds.  It's a good idea to test the script with the wrong credentials to confirm this works as expected.

There are two things to be aware of when developing your script:

1. You must save (and then re-open) your script before clicking Test Script.  If you click Test Script without saving first it will run the last saved version of the script.
2. 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.