Applies To:

Show Versions Show Versions

Manual Chapter: Syntax for Creating User-Defined Attack Signatures
Manual Chapter
Table of Contents   |   << Previous Chapter   |   Next Chapter >>

Attack signatures are composed of several different rule options and modifiers that you can combine to form complex rules that define the exact characteristics of the input to be matched. This appendix describes the syntax and usage for the rule options and modifiers that you need to follow when writing attack signatures. For information on attack signatures in general, refer to Chapter 6, Working with Attack Signatures.
The individual unit or rule building block is called a rule option. You can combine the various rule options into a single rule, with an implied AND operator between them. This means that all rule options must be satisfied for the rule to match. For more information on combining rule options, see Syntax considerations for parameter attack signatures.
The keyword rule options search for specific fixed strings in different parts of the input, which are referred to as scopes. (See Overview of rule option scopes, for more information on scopes.) Table C.1 lists the keyword rule options and their general usage.
Matches an alpha-numeric user-input parameter (or an extra-normalized parameter, if using the norm modifier); used for parameter values and XML objects. See Using the valuecontent rule option, for syntax information, and Scope modifiers for the pcre and re2 rule options, for more information on scope modifiers.
An XML payload is checked for attack signatures when the valuecontent keyword is used in the signature.
Note: The valuecontent parameter replaces the paramcontent parameter that was used in the Application Security Manager versions earlier than 10.0.
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.
Note: While Application Security Manager still fully supports PCRE, F5 recommends writing new attack signatures with the re2 rule option instead. Using RE2 provides performance enhancements for signature matching processes.
The re2 rule option performs a regular expression match on different parts of the input, and accepts the open-source RE2 regular expression syntax. You can find full syntax information here, http://code.google.com/p/re2/wiki/Syntax.
Limit the scope of the preceding uricontent keyword to the URI part only. See Using the objonly modifier, for syntax information.
Used with the valuecontent keyword modifier. Applies the signature if the request contains XML content. Refer to Scope modifiers for the pcre and re2 rule options, for more information.
Used with the valuecontent keyword modifier. Applies the signature if the request contains JSON content. Refer to Scope modifiers for the pcre and re2 rule options, for more information.
Used with the valuecontent keyword modifier. Applies the signature if the request contains Google Web Toolkit (GWT) content. Refer to Scope modifiers for the pcre and re2 rule options for more information.
Scopes are the elements of a request or a response to which the rule option applies. Most of the rule options apply to request elements, however, some can apply to response bodies. Table C.3 lists the scopes and their corresponding rule options to use in the attack signature.
Use the content keyword. For additional information, see Using the content rule option.
Use the uricontent keyword. For additional information, see Using the uricontent rule option.
Use the uricontent keyword with objonly modifier. For additional information, see Using the headercontent rule option, and Using the objonly modifier.
Use the headercontent keyword. For additional information, see Using the headercontent rule option.
HTTP parameters in query string or POST data
Use the valuecontent keyword. For additional information, see Using the valuecontent rule option.
HTTP parameters with additional normalizations
Use the valuecontent keyword with the norm modifier. For additional information, see Using the valuecontent rule option, and Using the norm modifier.
You can modify the pcre rule option to apply to any of the scopes described in the previous section, Overview of rule option scopes. For the pcre and re2 rule options, you can use the modifiers described in Table C.4.
Table C.4 Description of pcre and re2 modifiers 
PCRE or RE2 modifiers
If you do not specify a modifier, the pcre or re2 rule option applies to either the full content of the request, or the response body.
The U modifier specifies the URI scope.
The O modifier specifies the URL only scope.
The H modifier specifies the HTTP headers scope.
The P modifier specifies the parameters scope.
The N modifier specifies the parameters with additional normalizations scope.
The V modifier specifies the combined parameters scope and normalization scope.
For the URI and parameter scopes, the system always applies a normalization process before applying the rule options. For parameters, you can also specify the norm modifier with the valuecontent keyword to have the system perform additional normalizations. The additional parameter normalizations help mitigate common evasion techniques used in XSS, SQL-Injection and Command Execution attacks.
Note: Applying the norm modifier to the valuecontent keyword may boost the effectiveness of certain signatures, which, in turn, may cause an increased number of false-positives.
The following sections describe the usage and provide syntax examples of each of the rule options and modifiers. When you write a rule, use the semicolon character to separate the rule options, and use the colon character to separate option keywords and their arguments. Note that arguments which are strings must be in quotation marks.
The content rule option matches when the specified string is found anywhere in the full content of the request. The string match is case-sensitive, and must be exact. Figure C.1 shows an example of the content keyword.
Figure C.1 Syntax example of the content keyword
You can use the content keyword for request or response attack signatures. If you want the attack signature to apply to responses, there are two additional actions:
Ensure that you enable the Apply Response Signatures setting for the related file type.
In the rule itself, set the Apply to option to Response.
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. Figure C.2 shows an example of the uricontent keyword.
Figure C.2 Syntax examples of the uricontent keyword
You can use the uricontent keyword for request attack signatures only.
The headercontent rule option matches when the specified string is found anywhere in the HTTP request headers. The string match is case-sensitive, and must be exact. Figure C.3 shows an example of the headercontent keyword.
Figure C.3 Syntax examples of the headercontent keyword
You can use the headercontent keyword for request attack signatures only.
The valuecontent rule option matches when the specified string is found anywhere within a specific alpha-numeric user-input parameter. 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. The string match is case-sensitive, and must be exact.
Figure C.4 shows examples of the valuecontent keyword.
Figure C.4 Syntax examples of the valuecontent keyword
You can use the valuecontent keyword for request attack signatures only.
The pcre and re2 rule options match the regular expression found within the slash (/) characters matches. The scope of the match depends on the pcre or re2 modifiers that you specify. For details about the syntax used within the regular expression itself, refer to either the pcre documentation, which is available at http://pcre.org, or the re2 documentation which is available at http://code.google.com/p/re2/.
Note: While Application Security Manager still fully supports PCRE, F5 recommends writing new attack signatures with the re2 rule option instead. Using RE2 provides performance enhancements for signature matching processes.
Figure C.5 shows syntax examples of the pcre keyword.
Figure C.5 Syntax examples of the pcre rule option
Figure C.6 shows syntax examples of the re2 keyword.
Figure C.6 Syntax examples of the re2 rule option
You can use the following modifiers with the pcre or re2 rule options. Table C.5 describes the scope modifiers. You can use only one scope modifier for the pcre or re2 rule options.
Table C.5 Scope modifiers for the pcre and re2 rule option
Table C.6 describes the matching action modifiers that you can use with the pcre or re2 rule options. You can use one or more matching action modifiers.
Table C.6 Matching action modifiers for pcre and re2 rule options 
pcre, re2
Change the dot character (.) to match any character whatsoever, including a new line, which normally it would not match.
pcre, re2
Change the caret character (^) and the dollar sign character ($) from matching the start or end of the scope to matching the start or end of any line anywhere within the scope.
pcre, re2
The match is relative to the end of the last keyword match. (This modifier is similar to the distance:0; modifier.)
Use the reference rule option in a rule to provide an external reference or link to information regarding the rule, its source, or any other relevant documentation. Figure C.7 shows syntax examples of the reference keyword.
Figure C.7 Syntax examples of the reference rule option
Table C.7 lists the reference types.
Table C.7 Reference types of the reference rule option
Use the nocase modifier with one of the keyword rule options to make it not case-sensitive. Figure C.8 shows syntax examples of the nocase modifier.
Figure C.8 Syntax example of the nocase modifier
Use the offset modifier to specify that the previous keyword matches within its scope beginning not less than the specified number of bytes from the beginning of the scope. Figure C.9 shows syntax examples of the offset modifier.
Figure C.9 Syntax examples of the offset modifier
For example, the content rule in Figure C.9 matches these requests:
You can use the offset modifier to modify keywords for any scope. The scope determines where the offset matching begins. For example, the rule uricontent:"ABC"; offset:10; matches these requests:
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. Figure C.10 shows examples of the depth modifier.
Figure C.10 Syntax examples of the depth modifier
For example, the content rule in Figure C.10 matches these requests:
You can use the depth modifier to modify keywords for any scope. The scope determines where the depth matching begins. For example, in Figure C.10, the rule uricontent:"ABC"; depth:10; matches these requests:
You can combine the offset and depth modifiers to define both the beginning and ending boundaries of the area in which the keyword can match. For example, the rule content:"ABC"; offset:10; depth:20; matches these requests:
Use the distance modifier to specify that the previous keyword matches not 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, while the offset modifier is an absolute value that starts matching from the beginning of the corresponding keyword scope. Figure C.11 shows a syntax example of the distance modifier.
Figure C.11 Syntax example of the distance modifier
The example rule shown in Figure C.11 matches these requests:
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:0; 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:
Use the within modifier to specify that the previous keyword matches not 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, while the depth modifier is an absolute value that starts matching from the beginning of the corresponding keyword scope. Figure C.12 shows a syntax example of the within modifier.
Figure C.12 Syntax example of the within modifier
For example, the rule in Figure C.12 matches these requests:
You can combine the distance and within modifiers to define both the beginning and ending 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:
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. Figure C.13 shows a syntax example of the objonly keyword.
Figure C.13 Syntax example of the objonly modifier
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. Refer to A note about normalization, for more information on normalization. Figure C.14 shows a syntax example of the norm modifier.
Figure C.14 Syntax example of the norm modifier
Note: The norm modifier applies only to the valuecontent rule option. See Using the valuecontent rule option, for additional information.
For user-defined attack signature rules, you can use the pipe symbol (|) to escape special characters that cannot easily be represented as-is in the keyword arguments. You use the ASCII-equivalent hexadecimal values to represent the characters in the argument. Figure C.15 shows syntax examples of escaping characters.
The system escapes all of the values that occur between the two pipe symbols in the argument. For example, the first rule in Figure C.15, where |00| represents the null character, matches the string ABC<NULL>XYZ. The second rule in Figure C.15, where |22 22| represents two double quotation marks, matches the string ABC""XYZ.
Note that for the pcre rule option, you use the \x escape sequence, and not the pipe symbols, to escape characters. See the PCRE documentation, which is available at http://pcre.org, for more information. The list of characters that you must escape is the same as those that apply to the other rule options.
Any attack signature that contains the valuecontent option in its rule is considered a parameter signature, that is, an attack signature that applies to the user-input, alpha-numeric parameters that are defined within a security policy. The system applies parameter attack signatures to each parameter name and value pair (name=value) individually.
You cannot use the valuecontent option with other content rule options.You can disable the parameter attack signature at both the parameter level, and the security policy level.
Response attack signature rules can contain only rule options and modifiers that apply to the entire content of the response. In other words, for response rules, you can use the content and reference keywords, and any applicable modifiers for these keywords. You can also use the pcre or re2 rule options for responses, as long as you do not use a scope modifier for the pcre or re2 keyword.
You can combine rule options together to form composite rules. The rule options (or option clusters, since you can combine several rule options to form a single assertion, by using keywords combined with modifiers) are combined with an implied AND operator, so that all of the conditions specified in a rule must be satisfied in order to satisfy the rule as a whole.
You can combine different scopes within one rule as long as you do not use any relative modifiers. For example, the following rule is invalid because it includes two scopes (content and uricontent), and within is a relative modifier.
You cannot combine the valuecontent rule option, nor the pcre P or re2 P rule option, with other scope keywords. The parameter rule options must be the only scope keywords in their respective rules. You can, however, combine the parameter keywords with additional valuecontent or pcre P or re2 P keywords, including those that have the norm (or N, for pcre or re2) modifier.
It is important that you do not combine rules that conflict. The following examples demonstrate both a valid rule combination and an invalid combination, where there are conflicting or illegal rule options and keywords.
Figure C.16 Valid combined-rule example of the valuecontent keyword
Figure C.17 Invalid combined-rule example of the valuecontent keyword
Error message: Invalid rule.
Combination Error: HTTP-based value content and general content cannot be combined in a single rule.
The rule combination in Figure C.17 is invalid because of the U modifier. The U modifier indicates that the pcre expression should match the URI scope of the request. You cannot combine the U modifier with the paramcontent keyword.
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.
However, you can use the not character (!) in front of a regular expression even without a positive condition. You can use a single negative regular expression in a signature.
Table of Contents   |   << Previous Chapter   |   Next Chapter >>

Was this resource helpful in solving your issue?




NOTE: Please do not provide personal information.



Incorrect answer. Please try again: Please enter the words to the right: Please enter the numbers you hear:

Additional Comments (optional)