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 source:/trunk/src/net/lukemurphey/nsia/scan/HttpResponseData.java |
| operation | | See source:trunk/src/net/lukemurphey/nsia/scan/ScriptDefinition.java#L40 source:trunk/src/net/lukemurphey/nsia/scan/ScriptDefinition.java#L38 |
| variables | | See source:trunk/src/net/lukemurphey/nsia/scan/scriptenvironment/Variables.java source:trunk/src/net/lukemurphey/nsia/scan/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 |