Manual Chapter : Signature Syntax

Applies To:

Show Versions Show Versions

BIG-IP ASM

  • 12.1.6, 12.1.5, 12.1.4, 12.1.3, 12.1.2, 12.1.1, 12.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.

Note: 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.

Note: 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 valuecontent keyword for request attack signatures only. You cannot combine this scope with any other scope in a single rule.

Note: 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"; xmlonly;
   valuecontent:"url=http"; plaintextonly;

For example, suppose you have the following signature:

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

The signature matches in the following situations.

  • 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 ...  
Tip: 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.

Note: 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 ...  
Tip: 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.

Note: 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 ...
Tip: 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.

Note: 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 ...
Tip: 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;
Note: 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.

Note: 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.

Note: 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