ThreatScript Definitions¶

ThreatScript Definitions are written in ECMAScript (basically the same as JavaScript). The ThreatScript definitions return a Result object which indicates whether a match was observed.

ThreatScript Example¶

Below is an example of a ThreatScript that triggers if the web-page has a form element.

/*
 * Name: Example.General.Has_Form_Tag
 * Version: 1
 * ID: 1000000
 * Message: Indicates if the page has as a form tag
 * Severity: Low
 */

importPackage(Packages.ThreatScript);
importPackage(Packages.HTTP);

function analyze( httpResponse, operation, variables, environment, defaultRule ){

    var parser = httpResponse.getDocumentParser();
    var location = new URL( httpResponse.getLocation() );

    //Get a list of all script tags
    var tagNameFilter = new TagNameFilter("form");
    var nodesList = parser.extractAllNodesThatMatch(tagNameFilter); 
        if( nodesList.size() > 0 ){
         return new Result( true, "A form was detected" );
    }

    return new Result( false, "No forms detected" );
}

Analysis Function¶

ThreatScripts must provide an analyze function that takes 5 arguments:

Name	Type	Note
httpResponse		See source:trunk/src/net/lukemurphey/nsia/scan/HttpResponseData.java
operation		See source:trunk/src/net/lukemurphey/nsia/scan/ScriptDefinition.java#L40
variables		See source:trunk/src/net/lukemurphey/nsia/scan/scriptenvironment/Variables.java
environment		See source:trunk/src/net/lukemurphey/nsia/scan/ScriptDefinition.java#L605
defaultRule

Baseline Function¶

ThreatScripts may declare a baseline function that will allow the definition to be configured to baseline itself against the previous set of scan results. The baseline function is called by NSIA when a user presses the baseline method for a rule. The objective of the baseline function is to view the provided scan results and ignore the particular finding for the given resource in the future. For example, a definition that triggers when the hash of the web-page changes may define a baseline function that causes it to not trigger unless the web-page hashes changes to yet another value.

Below is an example:

function baseline( environment ){
    var previousValue = environment.get("LastObservedHash");

    if( previousValue != null && previousValue.getValue() != null ){
        environment.set("Hash", previousValue.getValue() );
    }

    return true;
}

Meta-Data¶

ThreatScripts must provide a meta-data that indicates the following information:

Name	Valid Input	Notes
Name	<category>.<sub_category>.<definition_name>
Version	integer	Should be incremented each time the definition is updated
ID	integer	Must be 1000000 or greater (only official definitions can be less than 1000000)
Message	message to be displayed when definition matches
Severity	Either: Low, Medium or High
Invasive	Either: True or False (this argument is optional)

This meta-data is provided in a comment as name-value pairs (see above ThreatScript example).

Definitions must have a name that is composed of three parts: a category, sub-category, and name. The part are separated by periods (like "category.subcategory.name"). The category and sub-category are important because the user can create exceptions and disable definitions by category or sub-category. Therefore, it is important that you use category names that makes sense; otherwise, the user may disable or enable your definition inadvertently.

In some cases a definition may be created for a specific site-group or rule. It is recommended that the definition be named such it is clear it is site-group or rule specific. Oftentimes, this done by appending an underscore to the category name (e.g. "_Acme.InformationLeak.ConfidentialDocumentFound").

Available Packages¶

A series of packages are available to ThreatScripts in order to perform analysis.

Package	Class	Description
HTTP	URL	Same as java.net.URL
	TagNameFilter	See http://htmlparser.sourceforge.net/javadoc/org/htmlparser/filters/TagNameFilter.html
<default>	StringUtils	Provides a trim function for Strings, see source:/trunk/src/net/lukemurphey/nsia/scan/scriptenvironment/StringUtils.java
ThreatScript	Result	Indicates the results of analysis, see source:/trunk/src/net/lukemurphey/nsia/scan/scriptenvironment.Result.java
	DataAnalysis	Provides functions useful for analysis, see source:/trunk/src/net/lukemurphey/nsia/scan/ScriptSignatureUtils.java