Project

General

Profile

ThreatScript Definitions » History » Version 5

Luke Murphey, 04/10/2010 04:11 PM

1 1 Luke Murphey
h1. ThreatScript Definitions
2 1 Luke Murphey
3 1 Luke Murphey
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.
4 1 Luke Murphey
5 1 Luke Murphey
h2. ThreatScript Example
6 1 Luke Murphey
7 1 Luke Murphey
Below is an example of a ThreatScript that triggers if the web-page has a form element.
8 1 Luke Murphey
9 1 Luke Murphey
<pre><code class="javascript">
10 1 Luke Murphey
/*
11 1 Luke Murphey
 * Name: Example.General.Has_Form_Tag
12 1 Luke Murphey
 * Version: 1
13 1 Luke Murphey
 * ID: 1000000
14 1 Luke Murphey
 * Message: Indicates if the page has as a form tag
15 1 Luke Murphey
 * Severity: Low
16 1 Luke Murphey
 */
17 1 Luke Murphey
18 1 Luke Murphey
importPackage(Packages.ThreatScript);
19 1 Luke Murphey
importPackage(Packages.HTTP);
20 1 Luke Murphey
21 1 Luke Murphey
function analyze( httpResponse, operation, variables, environment, defaultRule ){
22 1 Luke Murphey
23 1 Luke Murphey
	var parser = httpResponse.getDocumentParser();
24 1 Luke Murphey
	var location = new URL( httpResponse.getLocation() );
25 1 Luke Murphey
26 1 Luke Murphey
	//Get a list of all script tags
27 1 Luke Murphey
	var tagNameFilter = new TagNameFilter("form");
28 1 Luke Murphey
	var nodesList = parser.extractAllNodesThatMatch(tagNameFilter); 
29 1 Luke Murphey
        if( nodesList.size() > 0 ){
30 1 Luke Murphey
	     return new Result( true, "A form was detected" );
31 1 Luke Murphey
	}
32 1 Luke Murphey
        
33 1 Luke Murphey
	return new Result( false, "No forms detected" );
34 1 Luke Murphey
}
35 1 Luke Murphey
</code>
36 1 Luke Murphey
</pre>
37 2 Luke Murphey
38 3 Luke Murphey
h2. Analysis Function
39 3 Luke Murphey
40 3 Luke Murphey
ThreatScripts must provide an analyze function that takes 5 arguments:
41 3 Luke Murphey
42 3 Luke Murphey
| *Name*       | *Type* | *Note* |
43 4 Luke Murphey
| httpResponse |        | See source:/trunk/src/net/lukemurphey/nsia/scan/HttpResponseData.java       |
44 4 Luke Murphey
| operation    |        | See source:trunk/src/net/lukemurphey/nsia/scan/ScriptDefinition.java#L38       |
45 4 Luke Murphey
| variables    |        | See source:trunk/src/net/lukemurphey/nsia/scan/Variables.java       |
46 3 Luke Murphey
| environment  |        |        |
47 3 Luke Murphey
| defaultRule  |        |        |
48 1 Luke Murphey
49 1 Luke Murphey
h2. Baseline Function
50 1 Luke Murphey
51 4 Luke Murphey
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.
52 4 Luke Murphey
53 4 Luke Murphey
Below is an example:
54 4 Luke Murphey
55 4 Luke Murphey
<pre>
56 4 Luke Murphey
<code class="javascript">
57 4 Luke Murphey
function baseline( environment ){
58 4 Luke Murphey
	var previousValue = environment.get("LastObservedHash");
59 4 Luke Murphey
60 4 Luke Murphey
	if( previousValue != null && previousValue.getValue() != null ){
61 4 Luke Murphey
		environment.set("Hash", previousValue.getValue() );
62 4 Luke Murphey
	}
63 4 Luke Murphey
64 4 Luke Murphey
	return true;
65 4 Luke Murphey
}
66 4 Luke Murphey
</code>
67 4 Luke Murphey
</pre>
68 4 Luke Murphey
69 3 Luke Murphey
70 3 Luke Murphey
71 1 Luke Murphey
h2. Meta-Data
72 1 Luke Murphey
73 1 Luke Murphey
ThreatScripts must provide a meta-data that indicates the following information:
74 1 Luke Murphey
75 3 Luke Murphey
| *Name*  | *Valid Input*                                      | *Notes* |
76 3 Luke Murphey
| Name    | <category>.<sub_category>.<definition_name>        |         |
77 3 Luke Murphey
| Version | integer                                            | Should be incremented each time the definition is updated |
78 3 Luke Murphey
| ID      | integer                                            | Must be 1000000 or greater (only official definitions can be less than 1000000)        |
79 3 Luke Murphey
| Message | message to be displayed when definition matches    |         |
80 3 Luke Murphey
| Severity| Either: Low, Medium or High                        |         |
81 3 Luke Murphey
| Invasive| Either: True or False (this argument is optional)  |         |
82 1 Luke Murphey
83 3 Luke Murphey
This meta-data is provided in a comment as name-value pairs (see above ThreatScript example).
84 3 Luke Murphey
85 1 Luke Murphey
{{include(Definition_Naming_Convention)}}
86 3 Luke Murphey
87 3 Luke Murphey
h2. Available Packages
88 3 Luke Murphey
89 3 Luke Murphey
A series of packages are available to ThreatScripts in order to perform analysis.
90 3 Luke Murphey
91 3 Luke Murphey
| *Package*            | *Class*            | *Description*                                     |
92 3 Luke Murphey
|/2.HTTP               | URL                | Same as java.net.URL                              |
93 3 Luke Murphey
                       | TagNameFilter      | See http://htmlparser.sourceforge.net/javadoc/org/htmlparser/filters/TagNameFilter.html |
94 3 Luke Murphey
|<default>             | StringUtils        | Provides a trim function for Strings, see source:/trunk/src/net/lukemurphey/nsia/scan/scriptenvironment/StringUtils.java              |
95 5 Luke Murphey
|/2.ThreatScript       | Result             | Indicates the results of analysis, see source:/trunk/src/net/lukemurphey/nsia/scan/scriptenvironment.Result.java                 |
96 3 Luke Murphey
                       | DataAnalysis       | Provides functions useful for analysis, see source:/trunk/src/net/lukemurphey/nsia/scan/ScriptSignatureUtils.java            |