Manual Chapter : Signature Syntax

Applies To:

Show Versions

BIG-IP ASM

17.1.1, 17.1.0, 17.0.0, 16.1.5, 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0, 16.0.1, 16.0.0, 15.1.9, 15.1.8, 15.1.7, 15.1.6, 15.1.5, 15.1.4, 15.1.3, 15.1.2, 15.1.1, 15.1.0, 15.0.1, 15.0.0, 14.1.5, 14.1.4, 14.1.3, 14.1.2, 14.1.0

Signature Syntax

The content rule option

Use the

content

rule option to match a specified string located anywhere in the full content of the request.

The

content

rule option matches when the specified string is found anywhere in the full content of the request or response.

The system does not perform any normalization for the

content

rule option.

You can use the

content

keyword for request or response attack signatures. To apply the signature to responses, note the following:

Enable the

Apply Response Signatures

setting for the related file type.

In the rule itself, set the

Apply to

option to

Response

   content:"ABC";

The uricontent rule option

Use the

uricontent

rule option to match a specified string located anywhere in the URI of the request.

The

uricontent

rule option matches when the specified string is found anywhere in the normalized URI, including the query string. The string match is case-sensitive, and must be exact.

You can use the

uricontent

keyword for request attack or bot signatures only. You cannot use the

objonly

flag in bot signatures.

   uricontent:"ABC";

The headercontent rule option

Use the

headercontent

rule option to match a specified string located in the HTTP request header.

The

headercontent

rule option matches a specified string that is found anywhere in the HTTP request headers. The string match is case-sensitive, and must be exact.

You can use the

headercontent

keyword for request attack or bot signatures only. In bot signatures, the

useragentonly

flag is mandatory.

The system does not perform any normalizations for the

headercontent

rule option.

   headercontent:"ABC";

   headercontent: "MyMaliciousBot"; useragentonly; ipp: "/MyMaliciousBot v0.[0-9]/H";
      useragentonly;

The valuecontent rule option

Use the

valuecontent

rule option to match a specified string located in an alphanumeric user-input parameter.

The

valuecontent

rule option matches when a specified string is found anywhere within a alphanumeric user-input parameter, or if found in the complete payload when the Apply Value and Content Signatures content profile is selected. The system applies

valuecontent

rules only to parameters defined in the security policy. The rule matches against each parameter separately, on the full name and value pair.

You can use the

jsononly

xmlonly

gwtonly

httponly

, and

plaintextonly

modifiers with

valuecontent

to explicitly enforce signatures on specific profiles.

You can use the

valuecontent

keyword for request attack signatures only. You cannot combine this scope with any other scope in a single rule.

Any signature with a rule that contains the

valuecontent

option is considered a

parameter signature

, that is, a signature that applies to the user-input, alphanumeric parameters that are defined within a security policy. The system applies parameter signatures to each parameter name and value pair (that is, to the

name=value

string using the equal sign).

In other words, you cannot use the

valuecontent

option with other

content

rule options. You can disable a parameter signature at both the parameter level, and the security policy level.

   valuecontent:"ABC";
   valuecontent:"ABC"; httponly;
   valuecontent:"ABC"; jsononly;
   valuecontent:"ABC"; plaintextonly;
   valuecontent:"ABC"; xmlonly;

For example, suppose you have the following signature:

valuecontent:"soda";
valuecontent:"bar"; distance 0;

It will match in the following scenarios.

A request goes to a URL in the form data content profile, and its content is a parameter defined as alphanumeric (like the default wildcard *). It matches a request such as the following:

POST /a_form_data_url.html HTTP/1.1
Host: beni.core.com

alpha_numeric_parameter=sodabar

A request goes to a URL that has Request Body Handling set to

Apply value and content signatures

. Its content matches a request such as the following:

POST /a_value_signature_url.html HTTP/1.1
Host: beni.core.com
Content-Length: 548

Some other payload with unusual formatting, which is not form data then suddenly

sodabar

occurs then another payload continues.

A parameter defined as alphanumeric occurs in the query string:

GET /some_url.html?alpha_numeric_parameter=sodabar HTTP/1.0

The reference rule option

Use the

reference

rule option to provide an external reference or link.

Use the

reference

rule option in a rule to provide an external reference or link to information related to the rule, its source, or any other relevant documentation.

Here are the reference types that you can use in this rule option:

Type	Value	Example
url	URL	reference:url,www.reference.com;
bugtraq	Bugtraq ID	reference:bugtraq,1234;
cve	CVE ID	reference:cve,2007-1234;
nessus	Nessus Plugin ID	reference:nessus,1234;

   reference:url,www.reference.com;
   reference:bugtraq,1234;
   reference:cve,2007-1234;
   reference:nessus,1234;

The nocase modifier

Use the

nocase

modifier to make a word case-insensitive.

You can use the

nocase

modifier with any of the keywords to make it not case-sensitive.

   content:"ABC"; nocase;

The offset modifier

Use the

offset

modifier to specify that the previous keyword matches within its scope starting no less than the specified number of bytes from the beginning of the scope.

You can use the

offset

modifier to modify keywords in any scope. The scope determines where the offset matching begins. For example, the rule

uricontent:"ABC"; offset:10;

matches these requests:

   xxxx123456789012345
   GET /234567890ABC ...
   GET /2345678901ABC ...

but not these requests:

   xxxx123456789012345
   GET /23456789ABC ...
   GET /2345678ABC ...

The line of numbers at the top shows the number of bytes.

Here is an example rule with the

offset

modifier:

   content:"ABC"; offset:10;
   uricontent:"ABC"; offset:10;

The example matches these requests:

   12345678901234567890
   GET /67890ABC ...
   GET /678901ABC ...

but not these:

   12345678901234567890
   GET /6789ABC ...
   GET /678ABC ...

The plaintextonly modifier

The

plaintextonly

modifier is used to explicitly enforce signatures on text messages.

You can use the

plaintextonly

modifier only in attack signatures, not in bot signatures.

Use the

plaintextonly

modifier with

valuecontent

to enforce signatures.

For example:

valuecontent:”url=http”; plaintextonly;

Without the

plaintextonly

keyword, this signature would match any parameter named

url

that starts with

http

, possibly causing false positives. With the keyword, the signature has to match the entire string (including the equal sign) inside a WebSocket message, making it a more specific signature.

The depth modifier

Use the

depth

modifier to specify that the previous keyword matches within its scope ending not more than the specified number of bytes from the beginning of the scope.

You can use the

depth

modifier to modify keywords for any scope. The scope determines where the depth matching begins. For example, the rule

uricontent:"ABC"; depth:10;

matches these requests:

   xxxx123456789012345
   GET /234567ABC ...
   GET /23456ABC ...

but not these requests:

   xxxx123456789012345
   GET /2345678ABC ...
   GET /23456789ABC ...

The line of numbers at the top shows the number of bytes.

You can combine the

offset

and

depth

modifiers to define both the beginning and end boundaries of the area in which the keyword can match. For example, the rule

content:"ABC"; offset:10; depth:20;

matches these requests:

   1234567890123456789012345
   GET /67890ABC ...
   GET /678901234567ABC ...

but not these requests:

   1234567890123456789012345
   GET /678ABC ...
   GET /6789ABC ...

Here is an example rule with the

depth

modifier:

   content:"ABC"; depth:10;
   uricontent:"ABC"; depth:10;

The example matches these requests:

   12345678901234567890
   GET /67ABC ...
   GET /6ABC ...

but not these:

   12345678901234567890
   GET /678ABC ...
   GET /6789ABC ...

The distance modifier

The

distance

modifier specifies that the previous keyword matches no less than the specified number of bytes from the prior keyword.

You can use the

distance

modifier only in attack signatures, not in bot signatures.

Use the

distance

modifier to specify that the previous keyword matches no less than the specified number of bytes from the prior keyword. The

distance

modifier is similar to the

offset

modifier. The

distance

modifier enforces a minimum number of bytes relative to the end of the previously specified keyword, whereas the

offset

modifier is an absolute value that starts matching from the beginning of the corresponding keyword scope.

Use the

distance

modifier when the rule includes two keywords, and you want to enforce that the second keyword appears (anywhere) after the first keyword. Note that without the

distance

modifier, no positional relationship exists between two keywords in a rule. As such, the rule

content:"ABC"; content:"XYZ";

, without the

distance

modifier, matches both of these requests:

   GET /ABCXYZ ...
   GET /XYZABC ...

Example rule with the

distance

modifier:

   content:"ABC"; content:"XYZ"; distance:10;

The example matches these requests:

   xxxxxxxx12345678901234567890
   GET /ABC1234567890XYZ ...
   GET /ABC12345678901XYZ ...

but not these:

   xxxxxxxx12345678901234567890
   GET /ABC123456789XYZ ...
   GET /ABC12345678XYZ ...

The line of numbers at the top shows the number of bytes.

The within modifier

The

within

modifier specifies that the previous keyword matches no more than the specified number of bytes from the prior keyword.

You can use the

within

modifier only in attack signatures, not in bot signatures.

Use the

within

modifier to specify that the previous keyword matches no more than the specified number of bytes from the prior keyword. The

within

modifier is similar to the

depth

modifier, except that the

within

modifier enforces a maximum number of bytes relative to the end of the previously specified keyword, whereas the

depth

modifier is an absolute value that starts matching from the beginning of the corresponding keyword scope.

You can combine the

distance

and

within

modifiers to define both the beginning and end boundaries of the area in which the keyword can match, relative to the end of the previous keyword match.

For example, the rule

content:"ABC"; content:"XYZ"; distance:10; within:20;

matches these requests:

   xxxxxxxx12345678901234567890 
   GET /ABC1234567890XYZ ... 
   GET /ABC12345678901234567XYZ ...

but not these requests:

   xxxxxxxx1234567890123456789012345 
   GET /ABC123456789XYZ ... 
   GET /ABC123456789012345678XYZ ...

The line of numbers at the top shows the number of bytes.

   content:"ABC"; content:"XYZ"; within:10;

The example matches these requests:

   xxxxxxxx12345678901234567890
   GET /ABC1234567XYZ ...
   GET /ABC123456XYZ ...

but not these:

   xxxxxxxx12345678901234567890
   GET /ABC12345678XYZ ...
   GET /ABC123456789XYZ ...

The objonly modifier

The

objonly

modifier works with the

uricontent

keyword to look for a match that must be found in the URI.

Use the

objonly

modifier with the

uricontent

keyword to specify that the match must be found within the URI and not the query string. For example, in the URI,

GET /index.html?q=1,

the object part is

/index.html

   uricontent:"ABC"; objonly;

The example matches these requests:

   GET /ABC ...
   GET /ABC?param=123 ...

but not this request:

   GET /123?param=ABC ...

The norm modifier

Use the

norm

modifier to apply additional normalization processes or normalize parameter and value pairs.

Use the

norm

modifier to specify that the system applies additional normalization processes to parameter and value pairs before applying the rule. The additional normalization processes include transformations to mitigate evasion techniques commonly used in cross-site scripting (XSS), SQL-Injection, and Command Execution attacks.

   valuecontent:"ABC"; norm;

The

norm

modifier applies only to the

valuecontent

rule option. See the

valuecontent

rule option for additional information.

The escape character (|)

Use the escape character (|) to escape special characters and in keywords.

When writing rules in user-defined signatures, you use the pipe symbol (|) to escape special characters in keywords. You use the ASCII-equivalent hexadecimal values to represent the characters in the argument and surround them with pipe symbols. The system escapes all of the values that occur between the two pipe symbols in the argument.

You must escape the following characters when using them in a keyword argument:

Colon (:)

Semicolon (;)

Double quotation mark (")

Backward slash (\)

Pipe (|)

All binary characters (not ASCII-printable characters), including:

ASCII 0x00 through 0x1F

ASCII 0x7F through 0xFF

The space character (ASCII 0x20)

   content:"ABC|20|XYZ";
   content:"ABC|22 22|XYZ";

In the example, where

|20|

represents the space character, the first rule matches the string

ABC XYZ

. In the second rule in the example, where

|22 22|

represents two double quotation marks, the rule matches the string

ABC""XYZ

Note that there is a different syntax when escaping characters in regular expressions. Refer to the

pcre

and

re2

documentation for details or look online at

https://re2.googlecode.com/hg/doc/syntax.html

The not character

Use the not (!) character to negate a string and make it an exception to the rule.

Do not use negation in bot signatures.

You can place the not (!) character in front of a string to make that string an exception to a rule. However, the negative keyword cannot be the only keyword in a signature, so you cannot use the not character (!) without a positive condition before it. A relationship, such as distance, must exist between the negative and positive keywords.

You can use the not (!) character in front of a regular expression even without a non-negative keyword.

Here are some examples of using the not (!) character.

   content:"ABC"; content:!"CDE"; distance:1;
   uricontent:"ABC"; uricontent:!"CDE"; distance:0;
   headercontent:"ABC"; headercontent:!"CDE"; distance:0;
   valuecontent:"ABC"; valuecontent:!"CDE"; distance:0;
   content:"ABC"; pcre:!"/<regex>/";
   re2:!"/<regex>/";

The re2 rule option

Use the

re2

rule option to perform a regular expression match on different parts of the input.

The

re2

rule option performs a regular expression match on different parts of the input, and accepts the open-source RE2 regular expression syntax (as of Application Security Manager™ version 11.2). You can find the full syntax at

https://re2.googlecode.com/hg/doc/syntax.html

. The

re2

syntax is similar to the pcre regular expression syntax.

The scope of the match depends on the

re2

modifiers that you specify.

   re2:"/regex/[options]";
   re2:!"/regex/[options]";

In regular expressions, you must escape the following characters: period (.), caret (^), dollar sign ($), asterisk (*), plus sign (+), question mark (?), parentheses [( )], left square bracket ([), left curly brace ({), backslash (\), and vertical bar (|); and inside character classes you need to escape caret (^), hyphen (-), right square bracket (]), and backslash (\). Note that when escaping characters in regular expressions using

re2

, you use

re2

escape sequences, and not the pipe symbol, to escape characters.

Note that you do not need to escape semicolons that are not followed by whitespace, such as:

re2: "/soda;bar/";

If an argument requires a semicolon followed by whitespace, you can either escape the semicolon as follows:

re2: "/soda\x3b bar/";

or escape the whitespace (one or more spaces) after the semicolon:

re2: "/soda;\s+bar/";

You can also escape both the semicolon and the whitespace in the same regular expression:

re2: "/soda\x3b\s+bar/";

For the

re2

escape sequences, look online at https://re2.googlecode.com/hg/doc/syntax.html.

The pcre rule option

Use the

pcre

rule option to perform a regular expression match on different parts of the input.

Although Application Security Manager™ supports PCRE, F5 recommends using the

re2

rule option instead (as of Application Security Manager™ version 11.2). Using

re2

provides performance enhancements for signature matching processes.

The

pcre

rule option performs a regular expression match on different parts of the input, and is based on the Perl-compatible regular expressions (PCRE) syntax.

The scope of the match depends on the PCRE modifiers that you specify. For details about the syntax used within the regular expression itself, refer to the PCRE documentation at

pcre.org

   pcre:"/<regex>/";
   pcre:"/<regex>/<modifiers>";

pcre

has a different syntax (other than the vertical bar) for escaping characters (as explained at

pcre.org

The ipp rule option

Use the

ipp

rule option in a bot signature to perform a regular expression match on different parts of the input.

The

ipp

option, used only for bot signatures, performs a regular expression match on the input (instead of using

pcre

re2

). (The

ipp

option is analogous to the Snort keyword

pcre

.) The

ipp

option uses an Intel-based regular expression engine (processor-optimized) that is available on the BIG-IP system. For example:

   headercontent: "MyMaliciousBot"; useragentonly; ipp: "/MyMaliciousBot v0.[0-9]/H";
      useragentonly;

This bot signature searches for

MyMaliciousBot

in the user-agent, and if found, it runs the regular expression

"/MyMaliciousBot v0.[0-9]/H"

on the user-agent header. The

useragentonly

modifier narrows down the header scope to the user agent only, and can be used only when the previous modifier was

headercontent

, or

ipp

with the

modifier. An HTTP request that contains the header

User-Agent: MyMaliciousBot v0.8

is considered a bot as a result of using this signature.

Scope modifiers for re2, pcre, and ipp

This table describes the scope modifiers for the

re2

pcre

, and

ipp

rule options. You can use only one scope modifier for each rule option.

modifier	What it affects
none (using no modifier)	Full content of the request or response body
U	URI scope
O	URL-only scope (does not apply to ipp )
H	HTTP headers scope
P	Parameters scope (does not apply to ipp )
N	Parameters with additional normalizations scope (does not apply to ipp )
V	Combined parameters and normalization scope

Matching action modifiers for re2 and pcre

This table describes the matching action modifiers for the

re2

pcre

, and

ipp

rule options. You can use one or more modifier for each rule option.

Matching action modifier	Effect	Applies to
i	The match is not case-sensitive.	pcre , re2 , ipp
s	The dot character (.) matches any character, including a new line, which normally it would not match.	pcre , re2 , ipp
m	The caret (^) and the dollar sign ($) match the start or end of any line anywhere within the scope (instead of matching the start or end of the scope).	pcre , re2 , ipp
R	The match is relative to the end of the last keyword match. (This modifier is similar to the distance:0; modifier.)	pcre

Subscriptions

Product Usage

Trials

Registration Keys

Downloads

Applies To:

BIG-IP ASM

Signature Syntax

The content rule option

The uricontent rule option

The headercontent rule option

The valuecontent rule option

The reference rule option

The nocase modifier

The offset modifier

The plaintextonly modifier

The depth modifier

The distance modifier

The within modifier

The objonly modifier

The norm modifier

The escape character (|)

The not character

The re2 rule option

The pcre rule option

The ipp rule option

Scope modifiers for re2, pcre, and ipp

Matching action modifiers for re2 and pcre

Have a Question?

About F5

Education

F5 Sites

Support Tasks

Subscriptions

Product Usage

Trials

Registration Keys

Downloads

Applies To:

BIG-IP ASM

Signature Syntax

The content rule option

The uricontent rule option

The headercontent rule option

The valuecontent rule option

The reference rule option

The nocase modifier

The offset modifier

The plaintextonly modifier

The depth modifier

The distance modifier

The within modifier

The objonly modifier

The norm modifier

The escape character (|)

The not character

The re2 rule option

The pcre rule option

The ipp rule option

Scope modifiers for re2, pcre, and ipp

Matching action modifiers for re2 and pcre

Have a Question?

Follow Us

About F5

Education

F5 Sites

Support Tasks