Response Processing Modules

Home > API > Response-Processing-Modules

Response Processing Modules

1. Intro

When enabled for either the scanner or the proxy, response processing modules are run on every HTTP response received. They are written in Javascript.

They are located in the directory:

scripts/scanner/modules/response

Response processing modules can do things like execute regular expressions on response body content or header fields. They can also store information in the internal knowledge base and generate alerts.

2. Module object

Every response processing module must declare two things: a module object, and a run() function. The module object must set the value of the type property to "response-processor".

var module = {
  name : "E-Mail Finder Module",
  type: "response-processor",
   defaultDisabled: true
};

If set to true, the property defaultDisabled will cause the module to be unselected by default. This is useful for modules that are unstable or expensive to run.

3. run(request, response, ctx) function

The run() function is the entry point for the module. Vega invokes it, passing three parameters:

• request: Request Object representing the original HTTP request.
• response: Response Object representing the original HTTP response.
• ctx: Response Processing Module Context Object storing information about the module context. The context object also exposes the Vega API.

4. Request Object

The request parameter is a org.apache.http.HttpRequest object storing the original request for which the response is being processed. The module can access properties of this object such as the request line (which contains the URI) and headers.

4.1 Useful Properties of the Request Object

A detailed description of the Request Object can be found on its Wiki page.

request.requestLine.method:

The HTTP method (String).

request.requestLine.uri:

The URI (String).

request.headers:

An array of HTTP Header objects sent with the request. The elements of the array are objects with String name and value properties.

5. Response Object

A detailed description of the Response Object can be found on its Wiki page.

6. Context Object ( ctx )

The context object stores information about the module's environment (scan environment or proxy) and exposes the Vega API for generating alerts and accessing the knowledgebase. The context for a response processing module is different than the context for basic modules.

6.1 Generating Alerts

context.alert(type, request, response, properties)

This method is used to generate an alert.

Example:

ctx.alert("vdirlist", request, response, {
          output:   response.bodyAsString,
          key:      "vdirlist:" + key,
          resource: request.requestLine.uri
});

The type parameter corresponds to the filename, without its extension, of the XML alert that is to be used to render the alert.

The request and response parameters are the same objects as were passed to the run() function.

The final parameter is a properties object, which is defined in this example anonymously. The properties object has as properties the following key/value pairs:

output:

A segment of data to be used in the "output" section of the alert. For example: matched content from the response body.

resource:

The affected resource, to be included in the alert. This is often the URI, but it could be part of the URI.

key:

A unique string that can be used to prevent the generation of multiple alerts for the same issue. The scheme for generating such a string will depend on the characteristics of the module and is up to the module writer to design. In the below example, we generate the key from the web path. This is relatively simple, and more complex schemes to prevent duplicate alerts may be necessary (e.g. incorporating detected data from the response.):

var key = request.requestLine.uri;
var index = sub.indexOf('?');

if (index >= 0) {
  key = key.substring(0, index);
}

6.2 Storing and Retrieving Properties

Vega has an internal knowledge base where arbitrary information can be shared between modules using key/value pairs. There are several methods to store and retrieve different types of data.

Storing and retrieving Objects:

void context.setProperty(String name, Object value)

Object context.getProperty(String name, Object value)

Storing and retrieving Strings:

void context.setStringProperty(String name, String value)

String context.getStringProperty(String name, String value)

Storing and retrieving Integers:

void context.setIntegerProperty(String name, Integer value)

Integer context.getIntegerProperty(String name, Integer value)

A module can obtain a List of all keys in the knowledge base with this method:

List<String> context.propertyKeys()

Home > API > Response-Processing-Modules