Manual Chapter : Signature Syntax

Applies To:

Show Versions 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
Manual Chapter

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>";
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
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
or
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
/H
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