Project

General

Profile

ThreatScript Definitions » History » Version 9

Luke Murphey, 04/23/2010 01:46 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 8 Luke Murphey
function analyze( httpResponse, variables, environment ){
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 7 Luke Murphey
| *Name*       | *Type*            | *Note*                                                                           |
43 7 Luke Murphey
| httpResponse | HttpResponseData  | See source:trunk/src/net/lukemurphey/nsia/scan/HttpResponseData.java             |
44 7 Luke Murphey
| variables    | Variables         | See source:trunk/src/net/lukemurphey/nsia/scan/scriptenvironment/Variables.java  |
45 7 Luke Murphey
| environment  | Environment       | See source:trunk/src/net/lukemurphey/nsia/scan/ScriptDefinition.java#L605        |
46 1 Luke Murphey
47 1 Luke Murphey
h2. Baseline Function
48 1 Luke Murphey
49 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.
50 4 Luke Murphey
51 4 Luke Murphey
Below is an example:
52 4 Luke Murphey
53 4 Luke Murphey
<pre>
54 4 Luke Murphey
<code class="javascript">
55 4 Luke Murphey
function baseline( environment ){
56 4 Luke Murphey
	var previousValue = environment.get("LastObservedHash");
57 4 Luke Murphey
58 4 Luke Murphey
	if( previousValue != null && previousValue.getValue() != null ){
59 4 Luke Murphey
		environment.set("Hash", previousValue.getValue() );
60 4 Luke Murphey
	}
61 4 Luke Murphey
62 4 Luke Murphey
	return true;
63 4 Luke Murphey
}
64 4 Luke Murphey
</code>
65 4 Luke Murphey
</pre>
66 4 Luke Murphey
67 3 Luke Murphey
68 3 Luke Murphey
69 1 Luke Murphey
h2. Meta-Data
70 1 Luke Murphey
71 1 Luke Murphey
ThreatScripts must provide a meta-data that indicates the following information:
72 1 Luke Murphey
73 3 Luke Murphey
| *Name*  | *Valid Input*                                      | *Notes* |
74 3 Luke Murphey
| Name    | <category>.<sub_category>.<definition_name>        |         |
75 3 Luke Murphey
| Version | integer                                            | Should be incremented each time the definition is updated |
76 3 Luke Murphey
| ID      | integer                                            | Must be 1000000 or greater (only official definitions can be less than 1000000)        |
77 3 Luke Murphey
| Message | message to be displayed when definition matches    |         |
78 3 Luke Murphey
| Severity| Either: Low, Medium or High                        |         |
79 3 Luke Murphey
| Invasive| Either: True or False (this argument is optional)  |         |
80 1 Luke Murphey
81 1 Luke Murphey
This meta-data is provided in a comment as name-value pairs (see above ThreatScript example).
82 1 Luke Murphey
83 9 Luke Murphey
h3. Definition Name
84 8 Luke Murphey
85 1 Luke Murphey
{{include(Definition_Naming_Convention)}}
86 1 Luke Murphey
87 9 Luke Murphey
h3. Definition Severity
88 9 Luke Murphey
89 9 Luke Murphey
{{include(Definition_Severity)}}
90 9 Luke Murphey
91 9 Luke Murphey
h3. Definition References
92 9 Luke Murphey
93 9 Luke Murphey
{{include(Definition_References)}}
94 9 Luke Murphey
95 3 Luke Murphey
h2. Available Packages
96 1 Luke Murphey
97 3 Luke Murphey
A series of packages are available to ThreatScripts in order to perform analysis.
98 3 Luke Murphey
99 1 Luke Murphey
| *Package*            | *Class*            | *Description*                                     |
100 1 Luke Murphey
|/2.HTTP               | URL                | Same as java.net.URL                              |
101 1 Luke Murphey
                       | TagNameFilter      | See http://htmlparser.sourceforge.net/javadoc/org/htmlparser/filters/TagNameFilter.html |
102 7 Luke Murphey
|/2.<default>             | StringUtils        | Provides a trim function for Strings, see source:/trunk/src/net/lukemurphey/nsia/scan/scriptenvironment/StringUtils.java              |
103 7 Luke Murphey
| Debug        | Provides method that allows scripts to create log messages, see source:/trunk/src/net/lukemurphey/nsia/scan/scriptenvironment/Debug.java              |
104 7 Luke Murphey
|/2.ThreatScript       | Result             | Indicates the results of analysis, see source:/trunk/src/net/lukemurphey/nsia/scan/scriptenvironment.Result.java                 |
105 7 Luke Murphey
                       | DataAnalysis       | Provides functions useful for analysis, see source:/trunk/src/net/lukemurphey/nsia/scan/ScriptSignatureUtils.java            |
106 1 Luke Murphey
107 1 Luke Murphey
108 1 Luke Murphey
h2. Debugging ThreatScripts
109 8 Luke Murphey
110 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.
111 8 Luke Murphey
112 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.
113 8 Luke Murphey
114 8 Luke Murphey
h2. General Notes When Writing Definitions
115 8 Luke Murphey
116 8 Luke Murphey
h3. ThreatScript Maximum Runtime
117 8 Luke Murphey
118 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.
119 8 Luke Murphey
120 8 Luke Murphey
h3. Maximum Data Size
121 8 Luke Murphey
122 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.