Custom Test Scripts Configuration

Custom test scripts enable you to add to HawkScan application security tests using custom business logic. In your Custom Test Script, you can define the criteria for alerting and the solution for the test. Then you can configure your stackhawk.yml file to include your script when it runs.

To add a Custom Test Script to HawkScan, complete the following steps:

Write the Custom Test Script
Register the Custom Test Script
Add the Plugin Id to the Custom Test Script
Add the Custom Test Script Config

Write the Custom Test Script

StackHawk only supports Custom Test Scripts that meet the following criteria:

Must be written in JavaScript or Kotlin
Must include either a scan() or scanNode()example function, or both
Must be an active scan test

See our Custom Test Script template and example for more information on what to include and how your script should be written.

Custom Test Scripts files should be stored in a folder named after their script type, ‘active’. This folder should be included in the same directory as the stackhawk.yml file.

The following example includes an outline and explanation for the different params and settings available for an active Custom Test Script written in Kotlin using the scan() method of the ScriptsActiveScanner constructor.

sample-script.kts

/**
 * Scans a specific parameter in an HTTP message.
 * The scan function will typically be called for every parameter in every URL and Form for every page.
 * @param activeScanner the ActiveScan parent object that will do all the core interface tasks
 *     (i.e.: sending and receiving messages, providing access to Strength and Threshold settings,
 *     raising alerts, etc.).
 * @param origMessage the HTTP Message being scanned.
 * @param param the name of the parameter being manipulated for this test/scan.
 * @param value the original parameter value.
 */
fun scan(activeScanner: ScriptsActiveScanner, origMessage: HttpMessage, param: String, value: String) {
    // Copy requests before reusing them
    val msg = origMessage.cloneRequest()
    
    activeScanner.setParam(msg, param, "Your attack")

    activeScanner.sendAndReceive(msg, false, false)

    // Test the response here, and make other requests as required
    if (true) {
        activeScanner.newAlert()
            .setRisk(1)
            .setName("Active Vulnerability title")
            .setDescription("Full description")
            .setParam(param)
            .setAttack("Your attack")
            .setEvidence("Evidence")
            .setOtherInfo("Any other info")
            .setSolution("The solution")
            .setReference("https://example.com")
            .setCweId(0)
            .setWascId(0)
            .setMessage(msg)
            .raise()
    }
}

Register the Custom Test Script

For StackHawk’s platform to recognize and include the Custom Test Script in a HawkScan, it must be registered using the StackHawk CLI. When you register the Custom Test Script, the StackHawk CLI will generate a Plugin Id that you will then add to your Custom Test Script and stackhawk.yml files. You only need to generate a Plugin Id for your Custom Test Script once. Then, after the Plugin Id is added to your Custom Test Script and stackhawk.yml files, HawkScan will continue to include your Custom Test Script whenever you run it.

Registration uses the Application Id in your stackhawk.yml configuration file in your working directory to associate your test script to your organization.

To register your Custom Test Script, replace the sample script name with your own and use the following command:

shell

hawk register plugin my-custom-script

Sample response:

New Script Id: 1000014
- Add this ID to your StackHawk YAML under hawkAddOn: .scripts.-id
- Add this ID to your Plugin Script under pluginId

NOTE: Custom Test Scripts are limited to 50 per organization. Reach out to StackHawk Support to add more.

Add the Plugin Id to the Custom Test Script

After registering your Custom Test Script, you must add the Plugin Id to your Custom Test Script file. The following selection of code is an example of how you can configure your Custom Test Script settings, including the Plugin Id.

sample-script.kts

...
fun alert(activeScanner: ScriptsActiveScanner, msg: HttpMessage, evidence: String){
    activeScanner.newAlert()
        .setPluginId(1000014)
        .setRisk(1)
        .setName("Active Vulnerability")
        .setDescription("Protects against orcs.")
        .setParam(param)
        .setAttack("Orc extravaganza")
        .setEvidence(evidence)
        .setOtherInfo("Orcs fight dirty")
        .setSolution("Destroy the ring of power")
        .setReference("https://example.com")
        .setCweId(0)
        .setWascId(0)
        .setMessage(msg)
        .raise()
}
...

Script Settings Reference

WARNING: Name, WascId, Description, Solution, and Reference cannot be edited for the Custom Test Script associated with the Plugin Id once the vulnerability has been detected and recorded in StackHawk’s database.

Setting	Value Type	Description
PluginId (required)	int	Plugin Id returned when you registered the Custom Test Script.
Risk	int	Accepted values: 1(low), 2(medium), 3(high) Describes the risk to the app if the custom test script finds an exploit.
Name	string	The name of the exploit. This name can be different than the name of the script and what you specified when you registered the script. Defaults to ‘Script Active Scan Rules’. Once set it cannot be changed.
Description	string	Description of the problem. This setting is optional but recommended.
Param	string	The name of the parameter you are manipulating.
Attack	string	The value to attack the param with.
Evidence	string	The value that indicates the app was exploited. For example, the response body or response header.
OtherInfo	string	Any additional information you may want to include. For example, a link to the CVE.
Solution	string	A description of how to fix the problem.
Reference	string	Any reference you find helpful. For example, a link to the online reference to the vulnerability.
CweId	int	The Common Weakness Enumeration Id.
WascId	int	The Web Application Security Consortium Threat Classification Reference Id.

Add the Custom Test Script Config

After you have added the Plugin Id to your Custom Test Script file and updated all of the script’s settings, you must configure your stackhawk.yml file to include the Custom Test Script.

The following selection of YAML is an example of how you can configure your stackhawk.yml file, including the Plugin Id.

stackhawk.yml

...
hawkAddOn:
  scripts:
    - name: custom.kts
      id: 1000014
      type: active
      path: scripts
      language: KOTLIN
...

YAML Options Reference

Param	Type	Description
Id (required)	int	Plugin Id returned when you registered the Custom Test Script.
Type (required)	string	The type of Custom Test Script. Must be ‘active’, as it is the only supported type for now.
Path	url	File path to the ‘active’ folder containing the script file. The default is the current directory.
Name (required)	string	The name of the Custom Test Script file, incluing the extension.
Language (required)	string	The name of the language the Custom Test Script is using. Must be ‘JAVASCRIPT’ or ‘KOTLIN.’

View Scan Results

After you have completed the steps to add your Custom Test Script, you can run HawkScan and it will include your new test. The findings will include the custom tag on the results page.

Testing Custom Test Scripts

To test your Custom Test Scripts in HawkScan, you can add the following configuration to only run your Custom Test Scripts and not the default scan policy.

stackhawk.yml

...
hawk:
  scan:
    policyName: CUSTOM_SCRIPTS
...