Signature rule patterns
You can add a new pattern to a signature rule or modify an existing pattern of a signature rule to specify a string or expression that characterizes an aspect of the attack that the signature matches. To determine which patterns an attack exhibits, you can examine the logs on your web server, use a tool to observe connection data in real time, or obtain the string or expression from a third-party report about the attack.
Caution:
Any new pattern that you add to a signature rule is in an AND relationship with the existing patterns. Do not add a new pattern to an existing signature rule if you do not want a potential attack to have to match all of the patterns in order to match the signature.
Each pattern can consist of a simple string, a PCRE-format regular expression, or the built-in SQL injection or cross-site scripting pattern. Before you attempt to add a pattern that is based on a regular expression, you should make sure that you understand PCRE-format regular expressions. PCRE expressions are complex and powerful; if you do not understand how they work, you can unintentionally create a pattern that matches something that you did not want (a false positive) or that fails to match something that you did want (a false negative).
If you are not already familiar with PCRE-format regular expressions, you can use the following resources to learn the basics, or for help with some specific issue:
- “Mastering Regular Expressions”, Third Edition. Copyright (c) 2006 by Jeffrey Friedl. O’Reilly Media, ISBN: 9780596528126.
- “Regular Expressions Cookbook”. Copyright (c) 2009 by Jan Goyvaerts and Steven Levithan. O’Reilly Media, ISBN: 9780596520687
- PCRE Man page/Specification
- PCRE Man Page/Specification
- Wikipedia PCRE entry
- PCRE Mailing List
If you need to encode non-ASCII characters in a PCRE-format regular expression, the Citrix ADC platform supports encoding of hexadecimal UTF-8 codes. For more information, see “PCRE Character Encoding Format.”
To configure a signature rule pattern
-
Navigate to Security > Citrix Web App Firewall > Signatures.
-
In the details pane, select that signatures object that you want to configure, and then click Open.
-
In the Modify Signatures Object dialog box, in the middle of the screen beneath the Filtered Results window, either click Add to create a signature rule, or select an existing signature rule and click Open.
Note: You can modify only signature rules that you added. You cannot modify the default signature rules.
Depending on your action, either the Add Local Signature Rule or the Modify Local Signature Rule dialog box appears. Both dialog boxes have the same contents.
-
Under the Patterns window in the dialog box, either click Add to add a new pattern, or select an existing pattern from the list beneath the Add button and click Open. Depending on your action, either the Create New Signature Rule Pattern or the Edit Signature Rule Pattern dialog box appears. Both dialog boxes have the same contents.
-
In the Pattern Type drop-down list, choose the type of connection that the pattern is intended to match.
- If the pattern is intended to match request elements or features, such as injected SQL code, attacks on web forms, cross-site scripts, or inappropriate URLs, choose Request.
- If the pattern is intended to match response elements or features, such as credit card numbers or safe objects, choose Response.
-
In the Location area, define the elements to examine with this pattern.
The Location area describes what elements of the HTTP request or response to examine for this pattern. The choices that appear in the Location area depend upon the chosen pattern type. If you chose Request as the pattern type, items relevant to HTTP requests appear; if you chose Response, items relevant to HTTP responses appear.
In addition, as you choose a value from the Area drop-down list, the remaining parts of the Location area change interactively. Following are all configuration items that might appear in this section.
-
Area
Drop-down list of elements that describe a particular portion of the HTTP connection. The choices are as follows:
- HTTP_ANY. All parts of the HTTP connection.
- HTTP_COOKIE. All cookies in the HTTP request headers after any cookie transformations are performed. Note: Does not search HTTP response “Set-Cookie:” headers.
-
HTTP_FORM_FIELD. Form fields and their contents, after URL decoding, percent decoding, and removal of excess whitespace. You can use the
<Location>tag to further restrict the list of form field names to be searched. - HTTP_HEADER. The value portions of the HTTP header after any cross-site scripting or URL decoding transformations.
- HTTP_METHOD. The HTTP request method.
- HTTP_ORIGIN_URL. The origin URL of a web form.
- HTTP_POST_BODY. The HTTP post body and the web form data that it contains.
- HTTP_RAW_COOKIE. All HTTP request cookie, including the “Cookie:” name portion. Note: Does not search HTTP response “Set-Cookie:” headers.
- HTTP_RAW_HEADER. The entire HTTP header, with individual headers separated by linefeed characters (\n) or carriage return/line-feed strings (\r\n).
- HTTP_RAW_RESP_HEADER. The entire response header, including the name and value parts of the response header after URL transformation has been done, and the complete response status. As with HTTP_RAW_HEADER, individual headers are separated by linefeed characters (\n) or carriage return/line-feed strings (\r\n).
- HTTP_RAW_SET_COOKIE. The entire Set-Cookie header after any URL transformations have been performed Note: URL transformation can change both the domain and path parts of the Set-Cookie header.
- HTTP_RAW_URL. The entire request URL before any URL transformations are performed, including any query or fragment parts.
- HTTP_RESP_HEADER. The value part of the complete response headers after any URL transformations have been performed.
- HTTP_RESP_BODY. The HTTP response body
- HTTP_SET_COOKIE. All “Set-Cookie” headers in the HTTP response headers.
- HTTP_STATUS_CODE. The HTTP status code.
- HTTP_STATUS_MESSAGE. The HTTP status message.
- HTTP_URL. The value portion of the URL in the HTTP headers, excluding any query or fragment ports, after conversion to the UTF-* character set, URL decoding, stripping of whitespace, and conversion of relative URLs to absolute. Does not include HTML entity decoding.
-
URL
Examines any URLs found in the elements specified by the Area setting. Select one of the following settingss.
- Any. Checks all URLs.
- Literal. Checks URLs that contain a literal string. After you select Literal, a text box is displayed. Type the literal string that you want in the text box.
- PCRE. Checks URLs that match a PCRE-format regular expression. After you select this choice, the regular expression window is displayed. Type the regular expression in the window. You can use the Regex Tokens to insert common regular expression elements at the cursor, or you can click Regex Editor to display the Regular Expression Editor dialog box, which provides more assistance in constructing the regular expression that you want.
- Expression. Checks URLs that match a Citrix ADC default expression.
-
Field Name
Examines any form field names found in the elements specified by the Area selection.
- Any. Checks all URLs.
- Literal. Checks URLs that contain a literal string. After you select Literal, a text box is displayed. Type the literal string that you want in the text box.
- PCRE. Checks URLs that match a PCRE-format regular expression. After you select this choice, the regular expression window is displayed. Type the regular expression in the window. You can use the Regex Tokens to insert common regular expression elements at the cursor, or you can click Regex Editor to display the Regular Expression Editor dialog box, which provides more assistance in constructing the regular expression that you want.
- Expression. Checks URLs that match a Citrix ADC default expression.
-
-
In the Pattern area, define the pattern. A pattern is a literal string or PCRE-format regular expression that defines the pattern that you want to match. The Pattern area contains the following elements:
- Match A drop-down list of search methods that you can use for the signature. This list differs depending on whether the pattern type is Request or Response.
Request Match Types PCRE. A PCRE-format regular expression. NOTE: When you choose PCRE, the regular expression tools beneath the Pattern window are enabled. These tools are not useful for most other types of patterns.
-
Injection. Directs the Web App Firewall to look for injected SQL in the specified location. The Pattern window disappears, because the Web App Firewall already has the patterns for SQL injection.
-
CrossSiteScripting. Directs the Web App Firewall to look for cross-site scripts in the specified location. The Pattern window disappears, because the Web App Firewall already has the patterns for cross-site scripts.
-
Expression. An expression in the Citrix ADC default expressions language. This is the same expressions language that is used to create Web App Firewall policies and other policies on the Citrix ADC appliance. Although the Citrix ADC expressions language was originally developed for policy rules, it is a highly flexible general purpose language that can also be used to define a signature pattern.
When you choose Expression, the Citrix ADC Expression Editor appears beneath Pattern window. For more information about the Expression Editor and instructions on how to use it, see “To add a firewall rule (expression) by using the Add Expression dialog box
Response Match Types:
-
Literal. A literal string
-
PCRE. A PCRE-format regular expression.
Note:
When you choose PCRE, the regular expression tools beneath the Pattern window are enabled. These tools are not useful for most other types of patterns.
- Credit Card. A built-in pattern to match one of the six supported types of credit card number.
Note:
The Expression match type is not available for Response-side signatures.
-
Pattern Window (unlabeled)
In this window, type the pattern that you want to match, and fill in any additional data.
- Literal. Type the string you want to search for in the text area. - CRE. Type the regular expression in the text area. Use the Regex Editor for more assistance in constructing the regular expression that you want, or the Regex Tokens to insert common regular expression elements at the cursor. To enable UTF-8 characters, click UTF-8. - Expression. Type the Citrix ADC advanced expression in the text area. Use Prefix to choose the first term in your expression, or Operator to insert common operators at the cursor. Click Add to open the Add Expression dialog box for more assistance in constructing the regular expression that you want. Click Evaluate to open the Advanced Expression Evaluator to help determine what effect your expression has. - Offset. The number of characters to skip over before starting to match on this pattern. You use this field to start examining a string at some point other than the first character. - Depth. How many characters from the starting point to examine for matches. You use this field to limit searches of a large string to a specific number of characters. - Min-Length. The string to be searched must be at least the specified number of bytes in length. Shorter strings are not matched. - Max-Length. The string to be searched must be no longer than the specified number of bytes in length. Longer strings are not matched. - Search method. A check box labeled fastmatch. You can enable fastmatch only for a literal pattern, to improve performance.
- Click OK.
- Repeat the previous four steps to add or modify additional patterns.
- When finished adding or modifying patterns, click OK to save your changes and return to the Signatures pane.
Caution:
Until you click OK in the Add Local Signature Rule or Modify Local Signature Rule dialog box, your changes are not saved. Do not close either of these dialog boxes without clicking OK unless you want to discard your changes.