Product Documentation

Configuring and using the Learning feature

The learning feature is a repetitive pattern filter that observes activity on a web site or application protected by the Web App Firewall, to determine what constitutes normal activity on that web site or application. It then generates a list of up to 2,000 suggested rules or exceptions (relaxations) for each security checks that includes support for the learning feature. Users normally find it easier to configure relaxations by using the learning feature than by entering the necessary relaxations manually.

The security checks that support the learning feature are:

  • Start URL check
  • Cookie Consistency check
  • Form Field Consistency check
  • Field Formats check
  • CSRF Form Tagging check
  • HTML SQL Injection check
  • HTML Cross-Site Scripting check
  • XML Denial-of-Service check
  • XML Attachment check
  • Web Services Interoperability check

You perform two different types of activities when using the learning feature. First, you enable and configure the feature to use it. You can use learning on all traffic to your protected web applications, or you can configure a list of IPs (called the Add Trusted Learning Clients list) from which the learning feature should generate recommendations. Second, after the feature has been enabled and has processed a certain amount of traffic to your protected web sites, you review the list of suggested rules and relaxations (learned rules) and mark each with one of the following designations:

  • Edit & Deploy. The rule is pulled into the Edit dialog box so that you can modify it, and the modified form is deployed.
  • Deploy. The unmodified learned rule is placed on the list of rules or relaxations for this security check.
  • Skip. The learned rule is placed on a list of rules or relaxations that are not deployed. The learned rule is removed when skipped. However, as they are not added to relaxations, they might get learned again.

Learning is not performed only when relaxations are in place, except for field format rules. When rules are skipped, they are only removed from learned database. As relaxations are not added, they might get learned again. When rules are deployed, they are removed from learned database and also relaxations are added for the rules. As relaxations are added, they would not be learned again. For fieldformat protection, learning is performed irrespective of relaxations.

Although you can use the command line interface for basic configuration of the learning feature, the feature is designed primarily for configuration through the Web App Firewall wizard or the GUI. You can perform only limited configuration of the learning feature by using the command line.

The wizard integrates configuration of learning features with configuration of the Web App Firewall as a whole, and is therefore the easiest method for configuring this feature on a new Citrix ADC appliance or when managing a simple Web App Firewall configuration. The GUI visualizer and manual interface both provide direct access to all learned rules for all security checks, and are therefore often preferable when you must review learned rules for a large number of security checks.

The learning database is limited to 20 MB in size, which is reached after approximately 2,000 learned rules or relaxations are generated per security check for which learning is enabled. If you do not regularly review and either approve or ignore learned rules and this limit is reached, an error is logged to the NetScaler log and no more learned rules are generated until you review the existing learned rules and relaxations.

If learning stops because the database has reached its size limit, you can restart learning either by reviewing the existing learned rules and relaxations or by resetting the learning data. After learned rules or relaxations are approved or ignored, they are removed from the database. After you reset the learning data, all existing learning data is removed from the database and it is reset to its minimum size. When the database falls below 20 MB in size, learning restarts automatically.

To configure the learning settings by using the command line interface

Specify the Web App Firewall profile to be configured and, for each security check that you want to include in that profile, specify the minimum threshold or the percent threshold. The minimum threshold is an integer representing the minimum number of user sessions that the Web App Firewall must process before it learns a rule or relaxation (default: 1). The percent threshold is an integer representing the percentage of user sessions in which the Web App Firewall must observe a particular pattern (URL, cookie, field, attachment, or rule violation) before it learns a rule or relaxation (default: 0). Use the following commands:

  • set appfw learningsettings <profileName> [-startURLMinThreshold <positive_integer>] [-startURLPercentThreshold <positive_integer>] [-cookieConsistencyMinThreshold <positive_integer>] [-cookieConsistencyPercentThreshold <positive_integer>] [-CSRFtagMinThreshold <positive_integer>] [-CSRFtagPercentThreshold <positive_integer>] [-fieldConsistencyMinThreshold <positive_integer>] [-fieldConsistencyPercentThreshold <positive_integer>] [-crossSiteScriptingMinThreshold <positive_integer>] [-crossSiteScriptingPercentThreshold <positive_integer>] [-SQLInjectionMinThreshold <positive_integer>] [-SQLInjectionPercentThreshold <positive_integer>] [-fieldFormatMinThreshold <positive_integer>] [-fieldFormatPercentThreshold <positive_integer>] [-XMLWSIMinThreshold <positive_integer>] [-XMLWSIPercentThreshold <positive_integer>] [-XMLAttachmentMinThreshold <positive_integer>] [-XMLAttachmentPercentThreshold <positive_integer>]
  • save ns config

Example

The following example enables and configures the learning settings in the profile pr-basic for the HTML SQL Injection security check. This is an appropriate initial test bed learning configuration, where you have complete control over the traffic that is sent to the Web App Firewall.

set appfw learningsettings pr-basic -SQLInjectionMinThreshold 10
set appfw learningsettings pr-basic -SQLInjectionPercentThreshold 70
save ns config

To reset learning settings to their defaults by using the command line interface

To remove any custom configuration of the learning settings for the specified profile and security check, and return the learning settings to their defaults, at the command prompt type the following commands:

  • unset appfw learningsettings <profileName> [-startURLMinThreshold ] [-startURLPercentThreshold] [-cookieConsistencyMinThreshold] [-cookieConsistencyPercentThreshold] [-CSRFtagMinThreshold ] [-CSRFtagPercentThreshold ] [-fieldConsistencyMinThreshold ] [-fieldConsistencyPercentThreshold ] [-crossSiteScriptingMinThreshold ] [-crossSiteScriptingPercentThreshold ] [-SQLInjectionMinThreshold ] [-SQLInjectionPercentThreshold ] [-fieldFormatMinThreshold] [-fieldFormatPercentThreshold ] [-XMLWSIMinThreshold ] [-XMLWSIPercentThreshold ] [-XMLAttachmentMinThreshold ] [-XMLAttachmentPercentThreshold]
  • save ns config

To display the learning settings for a profile by using the command line interface

At the command prompt, type the following command:

show appfw learningsettings <profileName>

To display unreviewed learned rules or relaxations for a profile by using the command line interface

At the command prompt, type the following command:

show appfw learningdata <profileName> <securityCheck>

To remove specific unreviewed learned rules or relaxations from the learning database by using the command line interface

At the command prompt, type the following command:

rm appfw learningdata <profileName> (-startURL <expression> | -cookieConsistency <string> | (-fieldConsistency <string> <formActionURL>) | (-crossSiteScripting <string> <formActionURL>) | (-SQLInjection <string> <formActionURL>) | (-fieldFormat <string><formActionURL>) | (-CSRFTag <expression> <CSRFFormOriginURL>) | -XMLDoSCheck <expression> | -XMLWSICheck <expression> | -XMLAttachmentCheck <expression>) [-TotalXMLRequests]

Example

The following example removes all unreviewed learned relaxations for the pr-basic profile, HTML SQL Injection security check, that apply to the LastName form field.

rm appfw learningdata pr-basic -SQLInjection LastName

To remove all unreviewed learned data by using the command line interface

At the command prompt, type the following command:

reset appfw learningdata

To export learning data by using the command line interface

At the command prompt, type the following command:

export appfw learningdata <profileName> <securitycheck>[-target <string>]

Example

The following example exports learned relaxations for the pr-basic profile and the HTML SQL Injection security check to a comma-separated values (CSV) format file in the /var/learnt_data/ directory under the filename specified in the -target parameter.

export appfw learningdata pr-basic SQLInjection -target sqli_ld

To configure the Learning feature by using the GUI

  1. Navigate to Security > Web App Firewall > Profiles.
  2. In the Profiles pane, select the profile, and then click Edit.
  3. Click the Learning tab. At the top of the Learning tab is list of the security checks that are available in the current profile and that support the learning feature.
  4. To configure the learning thresholds, select a security check, and then type the appropriate values in the following text boxes: Minimum number threshold. Depending on which security check’s learning settings you are configuring, the minimum number threshold might refer to the minimum number of total user sessions that must be observed, the minimum number of requests that must be observed, or the minimum number of times a specific form field must be observed, before a learned relaxation is generated. Default: 1

    • Percentage of times threshold. Depending on which security check’s learning settings you are configuring, the percentage of times threshold might refer to the percentage of total observed user sessions that violated the security check, the percentage of requests, or the percentage of times a form field matched a particular field type, before a learned relaxation is generated. Default: 0
  5. To remove all learned data and reset the learning feature, so that it must start its observations again from the beginning, click Remove All Learned Data. Note: This button removes only learned recommendations that have not been reviewed and either approved or skipped. It does not remove learned relaxations that have been accepted and deployed.
  6. To restrict the learning engine to traffic from a specific set of IPs, click Trusted Learning Clients, and add the IP addresses that you want to use to the list.
    1. To add an IP address or IP address range to the Trusted Learning Clients list, click Add.
    2. In the Add Trusted Learning Clients dialog box, Trusted Clients IP list box, type the IP address or an IP address range in CIDR format.
    3. In the Comments text area, type a comment that describes this IP address or range.
    4. Click Create to add your new IP address or range to the list.
    5. To modify an existing IP address or range, click the IP address or range, and then click Open. Except for the name, the dialog box that appears is identical to the Add Trusted Learning Clients dialog box.
    6. To disable or enable an IP address or range, but leave it on the list, click the IP address or range, and then click Disable or Enable, as appropriate.
    7. To remove an IP address or range completely, click the IP address or range, and then click Remove.
  7. Click Close to return to the Configure Web App Firewall Profile dialog box.
  8. Click Close to close the Configure Web App Firewall Profile dialog box, and return to the Web App Firewall Profile screen.

To review learned rules or relaxations by using the GUI

  1. Navigate to Security > Web App Firewall > Profiles.
  2. Select the security check for which you want to review learned rules or relaxations, and then click Manage Rules.
  3. In the Manage Learned Rules dialog box, choose how you want to review the learned rules.
    • To review the actual learned patterns as displayed in the window, do nothing and proceed to the next step.
    • To review the learned data hierarchically as a branching tree, enabling you to choose general patterns that match many of the learned patterns, click** Visualizer**.
  4. If you have chosen to review actual learned patterns, perform the following steps.
  5. Select the first learned relaxation and choose how to handle it. - To modify and then accept the relaxation, click Edit & Deploy, edit the relaxation regular expression, and then click OK. - To accept the relaxation without modifications, click Deploy. - To remove the relaxation from the list without deploying it, click Skip.

    1. Repeat the previous step to review each additional learned relaxation.
  6. If you have chosen to use the Learning Visualizer, perform the following steps.
    1. In the branching hierarchical display, select a node that contains a learned pattern, and choose how to handle it.

      The screen area beneath the tree structure, under Regex of Selected Node, displays a generalized expression that matches all of the patterns in that node. If you want to display an expression that matches just one of the branches or just one of the leaves, select that branch or leaf.

      • To modify and then accept the learned relaxation, click Edit & Deploy, edit the relaxation regular expression, and then click OK.

      • To accept the relaxation without modifications, click Deploy.

      • To remove the modification from the list without deploying it, click Skip.

    2. Repeat the previous step to review other portions of the display.

  7. Click Close to return to the Manage Learned Rules dialog box.
  8. Click Close to return to the Configure Web App Firewall Profile dialog box.
  9. Click Close to close the Configure Web App Firewall Profile dialog box, and return to the Web App Firewall Profile screen.