Overview

When it comes to applications, while several authentication methods are more common than others, the set of possible authentication methods and variants is extremely large.

Out of the box, HawkScan can handle many common authenticated scanning scenarios using the documented configuration options for stackhawk.yml.

Some applications, however, may require additional steps or authentication methods that are not available with the standard configuration elements.

Using HawkScan's support for authentication scripts, you can extend HawkScan's authentication capabilities to match many unique authentication scenarios.

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)

How to Add a Script to Your HawkScan Configuration

Step 1: Write (or Obtain) an Authentication Script

The first step here is to map out your application's authentication mechanism, answering questions such as:

On what endpoint url does the login form (or API POST endpoint) reside?
Is the login host the same host as the application to be scanned?
What is the order of operations / authentication flow needed to authenticate to the application? For example:
- GET a particular URL
- Capture a cookie or parameter from the response header or body
- Send a POST to an endpoint along with credentials and information contained from the initial GET

Once you've determined the authentication flow, you're ready to write your authentication script.

But wait...you may not have to. First, check our HawkScan Examples repository for example scripts that are already written for you.

We maintain example scripts -- and their corresponding stackhawk.yml configuration -- for various scenarios in the examples repository, such as:

Oauth Authentication Flows for providers such as:
- Okta
- Auth0
- Firebase
- Keycloak
Custom JSON POST formatting (e.g., for credentials that are embedded within other json sections)
Exchanging tokens for cookies

If the example scripts don't fit your scenario -- or if they can't be modified to do so -- you may write your own script.

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 JavaScript template in that they need to include the functions that you see there (don't leave out any of the credentials or parameters 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, 2 configurations must be in place in stackhawk.yml:

app.authentication.script
- this specifies:
  - the authentication script to be called
  - credentials to be passed to the script as part of the login process
  - any additional parameters that the script will need (login url, form parameters, etc)
hawkAddOn.scripts
- this specifies the following information about every script (including authentication 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 snippets:

app.authentication.script:

    script:
      name: your-scriptname-here.js #supported: javascript, kotlin
      parameters:
        issuer: ${ISSUER} #IDP login endpoint
        grant_type: ${GRANT_TYPE} #OAuth flow type
        scope: ${SCOPE} #AuthZ access scope
      credentials:
        client_id: ${YOUR_CLIENT_ID} # your credentials values here
        client_secret: ${YOUR_CLIENT_SECRET}

hawkAddOn.scripts:

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

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

Specific yml examples (which correspond to specific auth scripts) are available in the example configs section of the examples repository.

Additional Information

For more information on using httpsender scripts, see Using custom httpsender 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 an API Key

Authenticating HawkScan to applications using custom JSON payloads

Using custom httpsender scripts with HawkScan

'null: nodename nor servname' error returned by HawkScan authentication script