Overview

HawkScan's support of customized authentication and authorization workflows doesn't end with Authentication scripts; you can also take advantage of ZAP's httpsender script functionality to extend this functionality into areas such as header management.

Scripting Overview

HawkScan supports several ZAP script types -- notably, authentication, session, and httpsender scripts -- which you can use in conjunction with stackhawk.yml to configure HawkScan to:

(authentication scripts) authenticate to your application using a script containing your custom authentication logic
1. HawkScan supports scripts written in javascript or kotlin
(session scripts) re-authenticate to your application using that same script should authentication lapse during a long-running scan
(httpsender scripts) manipulate specific elements of the HTTP messages between the scanner and target application, for purposes such as:
1. adding custom headers to every request from the scanner
2. manipulating header values in sophisticated ways (e.g., cryptographically signing each request or manipulating cookies in flight)

How to Add a Script to Your HawkScan Configuration

Step 1: Write (or Obtain) an httpsender script

Once you've determined the need for an httpsender script, you'll need to write the script...or maybe not -- first check our HawkScan Examples repository for example scripts that are already written for you.

Script-writing guidelines:

the script language must be javascript or kotlin
script language should be specified in the stackhawk.yml configuration (see below)
the script needs to follow the ZAP httpsender JavaScript template in that it needs to include the functions that you see there
- don't leave out any of the functions, even if you don't populate them

Step 2: Configure HawkScan to Find and Run the Script

To configure HawkScan to call your script, the hawkAddOn.scripts configuration must be in place in stackhawk.yml:

hawkAddOn.scripts
- this specifies the following information about every script (including httpsender scripts) that HawkScan will be calling:
  - name: filename of the script
  - language: JAVASCRIPT or KOTLIN
  - type: authentication, session, etc
  - path: relative path from the location of stackhawk.yml to look for the script in a subdirectory named according to the script type (/httpsender, /authentication, or /session)
    see the folder structure explainer in the examples readme for visual examples

Example yml snippet for hawkAddOn.scripts:

hawkAddOn:
  scripts:
    - name: your-scriptname-here.js
      language: JAVASCRIPT #supported options: JAVASCRIPT, KOTLIN
      type: httpsender
      path: script

(HawkScan is looking for the script in ./scripts/httpsender/your-scriptname-here.js relative to the stackhawk.yml in the above example)

Example Script: Header Manipulation

The Add Custom Headers httpsender script on HawkScan Examples is a kotlin example in which two custom headers are set which will be added to every request HawkScan makes.

Note: While hawkAddOn.replacer can also be used to add headers, it does so in a static fashion, while httpsender scripts can include sophisticated logic to manage headers.

Additional Information

For information on using authentication scripts, see Using custom Authentication scripts with HawkScan.

For more information on ZAP scripting in general, see our ZAP Deep Dive: Scripting ZAP video:

Authenticating HawkScan to applications using Basic Auth

Authenticating HawkScan to applications using custom JSON payloads

Using custom authentication scripts with HawkScan

'JSONObject not found' error returned by HawkScan session script

Authenticating HawkScan to applications using token injection