ThreatFactor NSIA

h1. 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.

h2. ThreatScript Example

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

<pre><code class="javascript">

/*

 * 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" );

}

</code>

</pre>

h2. 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  |        |        |

h2. 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:

<pre>

<code class="javascript">

function baseline( environment ){

	var previousValue = environment.get("LastObservedHash");

	if( previousValue != null && previousValue.getValue() != null ){

		environment.set("Hash", previousValue.getValue() );

	}

	return true;

}

</code>

</pre>

h2. 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).

{{include(Definition_Naming_Convention)}}

h2. Available Packages

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

| *Package*            | *Class*            | *Description*                                     |

|/2.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              |

|/2.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            |