Scanning with Custom
Test Scripts

Congratulations, responsible developer!  You’ve shifted left and incorporated HawkScan into your CI/CD pipeline. You are now finding and fixing vulnerabilities before they see the light of day. 

But what about vulnerabilities specific to your custom business logic?  Your application handles private information and you need to ensure you’re providing protection for that data.  Or maybe you want to take advantage of scripts already written by the ZAP community.

Well now you can. StackHawk has released beta support for Custom Test Scripts; active scripts written in JavaScript and run in HawkScan. Custom Test Scripts are a way to create your own vulnerability test. HawkScan will use your custom logic to attack targets in your application and report the results to the StackHawk platform. 

Simply write the script, register the script to the StackHawk platform, and add reference to it in your stackhawk.yml configuration file.  Now your own custom logic to verify the security of your application can be run on every PR.

Writing your own Custom Test Scripts

One of the more common issues that web applications face is tenancy violation.  You have one application serving multiple customers belonging to all different companies and nobody should be seeing data from companies they don’t belong to.  But HawkScan doesn’t know that Shirley belongs to Company A and Bob belongs to Company B.  It just knows that your application is free and clear of the OWASP Top Ten.

To solve this problem, we can write a naïve algorithm to check for tenancy violation in an active JavaScript Custom Test Script.  Your script needs to include the `scanNode()` or the `scan()` function (you could write more, I’m not the boss of you) that should call the `newAlert()` function when an alert is detected. The `scan()` function runs for every parameter in every url on that page whereas the `scanNode()` is run once on the page.  The following `scanNode()` function will run with the authentication specified (Shirley’s logged in this time) and will raise an alert when it hits the `/users` endpoint and Bob’s user details are on display.

The scanNode Function

function scanNode(as, msg) {

   var uri = msg.getRequestHeader().getURI();


   log("scanning " + uri);

   // Copy requests before reusing them
   msg = msg.cloneRequest();


   var request_header = msg.getRequestHeader();
   uri = request_header.getURI();

   //Path to request users
   uri.setPath(uri.getPath().toString() +  "/users");

   request_header.setHeader("Content-Type", "application/json");
   
   //Run modified message against the target
   as.sendAndReceive(msg, false, false);

   var response_header = msg.getResponseHeader();
   var response_body = msg.getResponseBody();

   //Check for users outside of logged in user's tenancy
   var evidence_idx = response_body.toString()
       .indexOf("Bob");

   log(msg);

   // Test the response here, and make other requests as required
   if (response_header.getStatusCode() == 200 && evidence_idx >= 0) {
       alert(as, msg, response_body.toString().substring(evidence_idx));
   }

}

The `scanNode()` function takes two parameters that will be provided by the scanner.  The ScriptsActiveScanner and HttpMessage.  The `HttpMessage` here is the request sent to the node you’re scanning.  Since this is an active scan, I can modify the message to try to attack the node.  In the example above, I naïvely append “/users” to each message path and then check if the response contains a user that the authenticated user shouldn’t see.  HawkScan will load the script and run it as if it were a built-in plugin.  If the function finds a positive response (a tenancy violation), it calls our convenience `alert()` which will create and send the alert to the scanner.

The alert Function

var RISK = 2 // 0: info, 1: low, 2: medium, 3: high
var TITLE = "Tenancy Check failed"
var DESCRIPTION = "User was able to access users not in their company"
var SOLUTION = "Enforce tenancy"
var REFERENCE = "https://personal.rhul.ac.uk/vsai/149/Multi-tenancy%20doc%20300614.pdf"
var OTHER = "see: https://www.cloudreach.com/en/blog/multi-tenant-security-in-the-cloud-what-you-need-to-know/"
var PLUGIN_ID = "" //Custom Plugin ID

function alert(as, msg, evidence) {
   as.newAlert()
       .setPluginId(PLUGIN_ID)
       .setRisk(RISK)
       .setName(TITLE)
       .setDescription(DESCRIPTION)
       .setEvidence(evidence)
       .setOtherInfo(OTHER)
       .setSolution(SOLUTION)
       .setReference(REFERENCE)
       .setMessage(msg)
       .raise();
}

The `newAlert()` function returns a builder for an `Alert` and `raise()` will build the alert and send it to the scanner.  In this example, the `PLUGIN_ID` refers to a custom Id, unique to your company and test script.  I’ve passed in my evidence index (the spot where I saw the unauthorized content in the response body) and my `HttpMessage` that I manipulated to attack the application.  The title, description, and additional parameters you can define, so provide useful feedback for yourself!  A full list of available options for alert parameters can be found in the Script Settings Reference.

The StackHawk Platform

If the scan finds an alert based on your custom script, the alert is reflected in the StackHawk platform, along with other vulnerabilities the scan detected.

You can then view the details and triage just like you would with any other finding!

And that’s all you have to do to start writing custom validations for your application!

Examples

1. HawkScan Examples 

2. Zap Community Scripts

Getting Started With Custom Test Scripts

1. Create a StackHawk account

2. Read the guide to Getting Started

3. Contact your sales representative and let them know you want to use Custom Test Scripts

4. Read the guide to configuring Custom Test Scripts

5. Script away!

📺 Watch a Quick Demo