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:

  1. Write the Custom Test Script
  2. Register the Custom Test Script
  3. Add the Plugin Id to the Custom Test Script
  4. 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
  • 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 JavaScript using the scan() method of the ScriptsActiveScanner constructor.

sample-script.js

/**
 * 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 as - 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.). This is an ScriptsActiveScanner object.
 * @param msg - the HTTP Message being scanned. This is an HttpMessage object.
 * @param {string} param - the name of the parameter being manipulated for this test/scan.
 * @param {string} value - the original parameter value.
 */
function scan(as, msg, param, value) {
	// Debugging can be done using println like this
	print('scan called for url=' + msg.getRequestHeader().getURI().toString() + 
		' param=' + param + ' value=' + value);
	
	// Copy requests before reusing them
	msg = msg.cloneRequest();
	
	// setParam (message, parameterName, newValue)
	as.setParam(msg, param, 'Your attack');
	
	// sendAndReceive(msg, followRedirect, handleAntiCSRFtoken)
	as.sendAndReceive(msg, false, false);
	
	// Test the response here, and make other requests as required
	if (true) {	// Change to a test which detects the vulnerability
		// risk: 1: low, 2: medium, 3: high
		as.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('References')
			.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.js

...
function alert(as, msg, evidence) {
    as.newAlert()
        .setPluginId(1000014)
        .setRisk(1)
        .setName('Active Vunerability')
        .setDescription('Protects against orcs.')
        .setParam(param)
        .setAttack('Orc extravaganza')
        .setEvidence(evidence)
        .setOtherInfo('Orcs fight dirty')
        .setSolution('Destroy the ring of power')
        .setReference('JRR Tolkien, Lord of the Rings')
        .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.js
      id: 1000014
      type: active
      path: scripts
      language: JAVASCRIPT
...

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’, as it is the only supported language for now.

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