Project

General

Profile

ThreatScript Definitions » History » Version 14

Luke Murphey, 05/17/2010 01:12 AM

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 11 Luke Murphey
 * Reference: url,threatfactor.com
17 1 Luke Murphey
 */
18 1 Luke Murphey
19 1 Luke Murphey
importPackage(Packages.ThreatScript);
20 1 Luke Murphey
importPackage(Packages.HTTP);
21 1 Luke Murphey
22 8 Luke Murphey
function analyze( httpResponse, variables, environment ){
23 1 Luke Murphey
24 1 Luke Murphey
	var parser = httpResponse.getDocumentParser();
25 1 Luke Murphey
	var location = new URL( httpResponse.getLocation() );
26 1 Luke Murphey
27 1 Luke Murphey
	//Get a list of all script tags
28 1 Luke Murphey
	var tagNameFilter = new TagNameFilter("form");
29 1 Luke Murphey
	var nodesList = parser.extractAllNodesThatMatch(tagNameFilter); 
30 1 Luke Murphey
        if( nodesList.size() > 0 ){
31 1 Luke Murphey
	     return new Result( true, "A form was detected" );
32 1 Luke Murphey
	}
33 1 Luke Murphey
        
34 1 Luke Murphey
	return new Result( false, "No forms detected" );
35 1 Luke Murphey
}
36 1 Luke Murphey
</code>
37 1 Luke Murphey
</pre>
38 2 Luke Murphey
39 3 Luke Murphey
h2. Analysis Function
40 3 Luke Murphey
41 12 Luke Murphey
ThreatScripts must provide an analyze function that takes 3 arguments:
42 3 Luke Murphey
43 7 Luke Murphey
| *Name*       | *Type*            | *Note*                                                                           |
44 7 Luke Murphey
| httpResponse | HttpResponseData  | See source:trunk/src/net/lukemurphey/nsia/scan/HttpResponseData.java             |
45 7 Luke Murphey
| variables    | Variables         | See source:trunk/src/net/lukemurphey/nsia/scan/scriptenvironment/Variables.java  |
46 7 Luke Murphey
| environment  | Environment       | See source:trunk/src/net/lukemurphey/nsia/scan/ScriptDefinition.java#L605        |
47 1 Luke Murphey
48 1 Luke Murphey
h2. Baseline Function
49 1 Luke Murphey
50 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.
51 4 Luke Murphey
52 4 Luke Murphey
Below is an example:
53 4 Luke Murphey
54 4 Luke Murphey
<pre>
55 4 Luke Murphey
<code class="javascript">
56 4 Luke Murphey
function baseline( environment ){
57 4 Luke Murphey
	var previousValue = environment.get("LastObservedHash");
58 4 Luke Murphey
59 4 Luke Murphey
	if( previousValue != null && previousValue.getValue() != null ){
60 4 Luke Murphey
		environment.set("Hash", previousValue.getValue() );
61 4 Luke Murphey
	}
62 4 Luke Murphey
63 4 Luke Murphey
	return true;
64 4 Luke Murphey
}
65 4 Luke Murphey
</code>
66 4 Luke Murphey
</pre>
67 4 Luke Murphey
68 14 Luke Murphey
h2. Terminate Function
69 3 Luke Murphey
70 14 Luke Murphey
ThreatScripts can also declare a terminate function that allows the scan engine to terminate the definition it execution exceeds the maximum execution time.
71 14 Luke Murphey
72 14 Luke Murphey
Below is an example of a (useless) rule that uses the terminate function to stop execution:
73 14 Luke Murphey
74 14 Luke Murphey
<pre>
75 14 Luke Murphey
<code class="javascript">
76 14 Luke Murphey
importPackage(Packages.ThreatScript);
77 14 Luke Murphey
78 14 Luke Murphey
var keep_going = true;
79 14 Luke Murphey
80 14 Luke Murphey
function analyze( httpResponse, operation, environment ){
81 14 Luke Murphey
82 14 Luke Murphey
    while(keep_going ){
83 14 Luke Murphey
        //Infinite loop
84 14 Luke Murphey
    }
85 14 Luke Murphey
86 14 Luke Murphey
    return new Result( false, "Definition did not match the input");
87 14 Luke Murphey
}
88 14 Luke Murphey
89 14 Luke Murphey
function terminate(){
90 14 Luke Murphey
    keep_going = false; //Will cause the analysis to stop
91 14 Luke Murphey
}
92 14 Luke Murphey
</code>
93 14 Luke Murphey
</pre>
94 3 Luke Murphey
95 1 Luke Murphey
h2. Meta-Data
96 1 Luke Murphey
97 1 Luke Murphey
ThreatScripts must provide a meta-data that indicates the following information:
98 1 Luke Murphey
99 3 Luke Murphey
| *Name*  | *Valid Input*                                      | *Notes* |
100 3 Luke Murphey
| Name    | <category>.<sub_category>.<definition_name>        |         |
101 3 Luke Murphey
| Version | integer                                            | Should be incremented each time the definition is updated |
102 3 Luke Murphey
| ID      | integer                                            | Must be 1000000 or greater (only official definitions can be less than 1000000)        |
103 3 Luke Murphey
| Message | message to be displayed when definition matches    |         |
104 3 Luke Murphey
| Severity| Either: Low, Medium or High                        |         |
105 3 Luke Murphey
| Invasive| Either: True or False (this argument is optional)  |         |
106 1 Luke Murphey
107 1 Luke Murphey
This meta-data is provided in a comment as name-value pairs (see above ThreatScript example).
108 1 Luke Murphey
109 9 Luke Murphey
h3. Definition Name
110 8 Luke Murphey
111 1 Luke Murphey
{{include(Definition_Naming_Convention)}}
112 1 Luke Murphey
113 9 Luke Murphey
h3. Definition Severity
114 9 Luke Murphey
115 9 Luke Murphey
{{include(Definition_Severity)}}
116 11 Luke Murphey
117 11 Luke Murphey
h3. Definition References 
118 11 Luke Murphey
119 11 Luke Murphey
{{include(Definition_References)}}
120 11 Luke Murphey
121 11 Luke Murphey
Note that definition references are defined a comment block with the "Reference:" as a prefix (Example: "// Reference: url,threatfactor.com").
122 9 Luke Murphey
123 3 Luke Murphey
h2. Available Packages
124 1 Luke Murphey
125 3 Luke Murphey
A series of packages are available to ThreatScripts in order to perform analysis.
126 3 Luke Murphey
127 1 Luke Murphey
| *Package*            | *Class*            | *Description*                                     |
128 13 Luke Murphey
|/9.HTTP               | URL                | Same as java.net.URL                              |
129 1 Luke Murphey
                       | TagNameFilter      | See http://htmlparser.sourceforge.net/javadoc/org/htmlparser/filters/TagNameFilter.html |
130 13 Luke Murphey
                       | GetRequest         | Web-client for performing HTTP Get requests  |
131 13 Luke Murphey
                       | PostRequest        | Web-client for performing HTTP Post requests |
132 13 Luke Murphey
                       | DeleteRequest      | Web-client for performing HTTP Delete requests |
133 13 Luke Murphey
                       | PutRequest         | Web-client for performing HTTP Put requests |
134 13 Luke Murphey
                       | TraceRequest       | Web-client for performing HTTP Trace requests |
135 13 Luke Murphey
                       | HeadRequest        | Web-client for performing HTTP Head requests |
136 13 Luke Murphey
                       | OptionsRequest     | Web-client for performing HTTP Option requests |
137 13 Luke Murphey
|/2.<default>          | StringUtils        | Provides a trim function for Strings, see source:/trunk/src/net/lukemurphey/nsia/scan/scriptenvironment/StringUtils.java              |
138 13 Luke Murphey
| Debug                | Provides method that allows scripts to create log messages, see source:/trunk/src/net/lukemurphey/nsia/scan/scriptenvironment/Debug.java              |
139 7 Luke Murphey
|/2.ThreatScript       | Result             | Indicates the results of analysis, see source:/trunk/src/net/lukemurphey/nsia/scan/scriptenvironment.Result.java                 |
140 7 Luke Murphey
                       | DataAnalysis       | Provides functions useful for analysis, see source:/trunk/src/net/lukemurphey/nsia/scan/ScriptSignatureUtils.java            |
141 1 Luke Murphey
142 1 Luke Murphey
143 1 Luke Murphey
h2. Debugging ThreatScripts
144 8 Luke Murphey
145 8 Luke Murphey
ThreatScripts can create event log messages by using the sendMessage() function in the Debug class. Simply call _Debug.sendMessage_ with a string as an argument to create an event log message. The event log messages can be viewed in the event log for NSIA.
146 8 Luke Murphey
147 8 Luke Murphey
Generally, script created log messages are used only for debugging and should be disabled on rules you want to use in production.
148 8 Luke Murphey
149 8 Luke Murphey
h2. General Notes When Writing Definitions
150 8 Luke Murphey
151 8 Luke Murphey
h3. ThreatScript Maximum Runtime
152 8 Luke Murphey
153 8 Luke Murphey
ThreatScript  definitions are forceably terminated by the scan engine if the script runs for longer than 10 seconds. Thus, it is important to write definitions that can complete within the timeframe alloted; otherwise, the definition will be flagged as having an error.
154 8 Luke Murphey
155 8 Luke Murphey
h3. Maximum Data Size
156 8 Luke Murphey
157 8 Luke Murphey
The scan engine only provides the first 1 MB of the data observed to the scan engine. Therefore, do not design ThreatScripts that won't work if only the first 1 MB of a larger file is provided.