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.

...
hawkAddOn:
  scripts:
    - name: custom.js
      id: 1000014
      type: active
      path: scripts
      language: JAVASCRIPT
...

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