ThreatPattern Definitions¶

• ThreatPattern Definitions
  • Definition Verb
  • Definition Name
  • Definition Body
    • Meta-Data Options
    • Data Analysis Options (Evaluators)
    • Variable Options
  • How Definitions Analyze Data
    • Mixed Mode Evaluators
    • Differences from Snort
  • Definition References

ThreatPattern's similar in concept to the signatures used by the Snort IDS system.

Definition Verb¶

The rules start with a action that indicates what the system should do with the rule. The action verbs are as follows:

Verb	Operation	Notes
Eval	Causes the rule to be evaluated but no action taken.	Only valid when an Set option is used. Used to set a flag that may be used in another signature (allows the rules to maintain state).
Alert	Causes the rule to indicate that a match has been found.	Used only to determine if the site may be compromised.
Block	Causes the resource to be blocked (end user cannot access)	Useful when using a proxy to control access to the servers; this is not currently used yet.

Definition Name¶

Definitions must have a name that is composed of three parts: a category, sub-category, and name. The part are separated by periods (like "category.subcategory.name"). The category and sub-category are important because the user can create exceptions and disable definitions by category or sub-category. Therefore, it is important that you use category names that makes sense; otherwise, the user may disable or enable your definition inadvertently.

In some cases a definition may be created for a specific site-group or rule. It is recommended that the definition be named such it is clear it is site-group or rule specific. Oftentimes, this done by appending an underscore to the category name (e.g. "_Acme.InformationLeak.ConfidentialDocumentFound").

Definition Body¶

The definition is composed of options that are used to make conclusions about the data provided. Below is a list of the various options:

Meta-Data Options¶

The following options are used to provide information about the definition:

Option	Required	Value	Example	Description
ID	Yes	<integer>	ID=10012441
Message	Yes	<string>	Message="Malicious Website Discovered"
Version		<integer>	Version=3
Reference		<string>	url,threatfactor.com	Types of references are: url ,bugtraq, cve, nessus, arachnids, mcafee
Severity		<string>	Severity="Medium"	Must be either low, medium or high and is required if the definition verb is alert or block

Data Analysis Options (Evaluators)¶

The following options are used to analyze the data:

Option	Required	Value	Example	Description
String		<string>	String=haxored	Looks for the given String value
Regex		PCRE	Regex=/apple/i	Looks for the given Regex (in PCRE format)
Byte		Bytes	Byte=90 90 90	Looks for the given bytes
ContentType		PCRE or <string>	ContentType=/text.*//i	Matches a given content type. The content type is inferred by the scanning engine based upon the file contents, HTTP headers and file extension.
URI		<string>	URI="http://google.com"
IgnoreCase				Synonymous with "NoCase"
BasicEncoding		<string>		Causes the evaluator to skip character set encoding and treat the data as if it is raw bytes (or ASCII encoded)
IsDataAt		<integer>		Determines if data is at the given position (i.e. equates to false if the data stream ends before the value provided)
Offset		<integer>	Offset=128	Sets how much data should be skipped from the previous operator
Depth		<integer>	Depth=1024	Sets a maximum depth into the data that the definition will examine (relative to the beginning of the data stream)
Within		<integer>	Within=512	Sets how many characters or bytes to analyze for the previous option before giving up. This is oftentimes used to increase the performance of definitions by limiting the amount of data they have to analyze.
ByteTest		operation	4 digits >= 128 (hexadecimal)	Can accept options such as big-endian, little-endian, hexadecimal, absolute-value and can operate on both digits (character representations of a number) or bytes (integer values)
ByteJump		operation	4 bytes (big-endian, align-8)	Can accept options such as big-endian, little-endian, hexadecimal, absolute-value, octal, align-4 and align-8 and can operate on both digits (character representations of a number) or bytes (integer values)

Variable Options¶

The following options are used to set and read variables. Variables are values that are set by one definition and can be read by other definitions. For example, one definition could set a variable named "ActiveXFound" if an ActiveX control is found on a page and other definitions that look for specific ActiveX controls can check to determine if the variable "ActiveXFound" exist before bothering to analyze the data for a specific ActiveX control.

Below are the relevant variables:

Option	Required	Value	Example	Description
Set		<string>	Set="IframeFound"	Sets the given variable (allows rules to maintain state)
UnSet		<string>	UnSet="IframeFound"	Unsets the given variable (allows rules to maintain state)
IfSet		<string>	IfSet="ActiveX"	Makes the action dependent upon whether the variable exists
IfNotSet		<string>	IfNotSet="ActiveX"	Opposite of above
Toggle		<string>	Toggle="JavaScriptFound"

How Definitions Analyze Data¶

A definition is considered a match when all of the evaluators match the data. For example the definition below will match on any combination of both "Foo" and "Bar" (in no particular order):

Alert("Example.Test.FooBar"){
        Message="Foo Bar Was found";
        Severity="Low";
        ID=1000001;
        Version=1;
        String="Foo";
        String="Bar";
}

Evaluators can be made relative to one another by using the Offset or Within options. The following definition will match when data contains "Bar" 4 or more characters after "Foo".

Alert("Example.Test.FooBar"){
        Message="Foo Bar Was found";
        Severity="Low";
        ID=1000001;
        Version=1;
        String="Foo";
        String="Bar"; Offset=4;
}

For performance reasons, you may want to place a limit on how many characters the definition will analyze. In the following example, we have added a limit to that causes the definition to only consider the 64 characters after "Foo" when looking for "Bar":

Alert("Example.Test.FooBar"){
        Message="Foo Bar Was found";
        Severity="Low";
        ID=1000001;
        Version=1;
        String="Foo";
        String="Bar"; Offset=4; Within="64";
}

Evaluators can be negated using the exclamation mark. The following definition matches when the data contains "Foo" but does not include "Bar" within 64 characters:

Alert("Example.Test.FooBar"){
        Message="Foo Bar Was found";
        Severity="Low";
        ID=1000001;
        Version=1;
        String="Foo";
        String!="Bar"; Within="64";
}

Mixed Mode Evaluators¶

NSIA will not allow evaluators that look for byte patterns to be used relative to evaluators looking for strings unless the BasicEncoding option is used. This is due to the fact that the number of bytes per character is highly variable depending on the charset involved; NSIA does not have a method to accurately account for this. Definitions with evaluators that look for data based on raw bytes and character are referred to as "mixed mode" evaluators and result in undefined behavior. Therefore, a definition such as the one below will be rejected:

Alert("Example.Test.FooBar"){
        Message="Foo Bar Was found";
        Severity="Low";
        ID=1000001;
        Version=1;
        Byte=46 6F 6F ;
        String="Bar"; Offset=4;
}

However, the following definition would be accepted since the evaluators are not relative to one another:

Alert("Example.Test.FooBar"){
        Message="Foo Bar Was found";
        Severity="Low";
        ID=1000001;
        Version=1;
        Byte=46 6F 6F ;
        String="Bar";
}

Differences from Snort¶

NSIA PatternDefinitions function similarly to Snort but have some notable differences:

• NSIA does not have a distance option. Instead, the offset option should be used since it function equivalently.
• In Snort, the byte_test and byte_jump options can be specified as relative or absolute. In NSIA, you must follow the ByteJump or ByteTest operator with an Offset option that specifies whether the option is relative or absolute. Otherwise, NSIA treats it as having an absolute offset of 0 (beginning of the data).
• The Snort "rawbytes" option is "BasicEncoding" in NSIA.
• The ByteTest option in NSIA uses the following syntax as opposed to Snort's comma deliminated format: ByteTest="<number> <datatype> (<modifiers>)". Here is an example: ByteTest="2 bytes=65281(unsigned)"
• The Offset, Depth and Within options can be used with other options than just those that do string lookups. For example, these options can be used between Regex, ByteTest, ByteJump and String evaluators.

Definition References¶

References can be defined to point users to additional information. The references are formatted with the prefix before the argument that is used to create the argument (e.g. "bid,39545" creates a link to BugTraq writeup for issue 39545).

Generic URLs can be created with the url prefix (e.g. "url,google.com" creates a link to Google.com).

The following types of references exist:

Name	Prefix	Links To
BuqTraq	bugtraq	http://www.securityfocus.com/bid
CVE	cve	http://cve.mitre.org/cve/
Nessus	nessus	http://www.nessus.org/plugins/index.php?view=all
Arachnids	arachnids	(URL is now defunct, don't use this anymore)
McAfee	mcafee	http://vil.nai.com/vil/default.aspx
URL	url
OSVDB	osvdb	http://osvdb.org/show/osvdb
USN	usn	http://www.ubuntu.com/usn/
Milw0rm	milworm	http://milw0rm.com/exploits
Secunia	secunia	http://secunia.com/advisories/
RHSA	rhsa	http://rhn.redhat.com/errata/
Microsoft KB	microsoft_kb	http://support.microsoft.com/kb/
Microsoft Security Bulletin	microsoft_bulletin	http://www.microsoft.com/technet/security/bulletin/