Basic Module Context Object
The basic module context object exposes the Vega API to the module.
Obtaining the Pathstate Object
The module can get information about the PathState node that it is associated with the context by requesting the PathState object. Module developers should become familiar with this data structure.
IPathState ctx.pathState()
Generating New Requests
The simplest way to generate a new request is to ignore the path state and schedule an entirely new (i.e. not altered) request:
ctx.submitRequest(HttpUriRequest request, callback)
Where request is a Request Object that has been created by the module developer.
Fuzzing
Indexes
All request submitted within Vega are assigned an index, either by the module developer, or implicitly, in creation order. The index is local to the context and can be used to refer to a submitted request (and its response, it received and saved) by any callback function associated with it. Indexes are frequently used to compare the responses of two or more altered requests when a callback is processing the final response of a check that required multiple requests to be received.
Submitting Altered Requests
Many modules will need to send a request that is a modification of a path state node. The simplest way to submit an altered request is via the following methods:
ctx.submitAlteredRequest(callback, String value) ctx.submitAlteredRequest(callback, String value, int Index)
This is the most basic way to submit an altered request. The value parameter will replace the fuzzable parameter in the case of a parametric path state node, or be appended to the end of a path in the case of a directory. The index parameter allows for the module developer to assign the request to an integer which can be referred to later (i.e. in the callback).
Generating Multiple Altered Requests
ctx.submitMultipleAlteredRequests(callback, String[] values)
This function allows the module developer to submit multiple such requests at once.
Appending or Replacing Known Variables
ctx.submitAlteredRequest(callback, String value, Boolean append) ctx.submitAlteredRequest(callback, String value, Boolean append, int index) ctx.submitMultipleAlteredRequests(callback, String value, Boolean append)
This variation allows for a flag to be set indicating whether or not the fuzzing value should be appended to or replace o a parameter value found during the crawl.
Callback function
The callback function passed to the function used to generate three requests must have these three parameters:
handler(request, response, ctx)
request: Object representing the original HTTP request.
response: Object representing the HTTP response.
ctx: Object storing information about the module context. The context object also exposes the Vega API.
Tracking Multiple Responses
In the cases where modules send multiple requests, the callback will be run for each response. The callback function can save the request and response for analysis and comparison when all of the responses have returned.
addRequestResponse(HttpUriRequest request, Response response)
The callback can also increment the response count within the context when it runs:
int incrementResponseCount() boolean allResponsesReceived()
This function returns an integer value indicating the number of responses received and inform the callback when it is processing the final response. The module can also call allResponsesReceived().
Page Fingerprints
Many web application security checks, including those in Vega, are based on using page similarity to identify interesting behavior. Vega extracts a page fingerprint from each page analyzed. It is these fingerprints that are compared to one another to determine page similarity.
For example, if one is testing for SQL injection, and is using arithmetic to do it, one test could work like so:
- Send two requests (1, 2) with arithmetic expressions in SQL that would be evaluated as true by the database if there is an SQL injection occurring
- Send one request (3) with an expression that should not evaluate as true if there is an SQL injection occurring
If the page fingerprints 1 and 2 are the same, but 1 and 3 are different, then it is possible that a SQL injection vulnerability is present.
boolean isFingerprintMatch(int index1, int index2) boolean isFingerprintMatch(int idx, IPageFingerprint fp)
The function above compares the fingerprints of two responses, referred to by the indexes. The second compares an index to a fingerprint (e.g. the path fingerprint).
Other Context Functions
Running Response Processing Modules
ctx.responseChecks(int index) ctx.responseChecks(Request request, Response Response)
The module can request that the response processing modules be run on a response.
ctx.contentChecks(Request request, Response response)
Runs the content analysis checks, e.g., for persistent XSS.
Module Failure
setModuleFailed() boolean hasModuleFailed()
The module can, for example, in a callback, set a failure flag in the context that can be checked by other callbacks associated with the context.
Debug Output
debug(String message)
The debug() function can be used to output debug messages to the console.
Request Highlighting
Modules can specify literal strings or regular expressions for highlighting in saved responses are rendered in the HTTP message viewer. There are three methods to do this. If case insensitive regular expression matching is desired, a specific method for this must be used.
ctx.addRegexCaseInsensitiveHighlight() ctx.addRegexHighlight() ctx.addStringHighlight()
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.
param:
The implicated parameter (if applicable).
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, the key is the URI (without parameters). 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); }
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 > Basic-Module-Context-Object
Have feedback on Vega? Our documentation? Please tell us.