Manual Chapter : Changing How a Security Policy is Built

Applies To:

Show Versions Show Versions

BIG-IP ASM

  • 13.1.5, 13.1.4, 13.1.3, 13.1.1, 13.1.0
Manual Chapter

Overview: Changing how a security policy is built

Application Security Manager™ (ASM) completely configures the policy building settings according to the selections you make when you create a security policy. These settings are used for both automatic and manual policy building. You can review the settings, and change them later if needed.

The policy building settings control:

  • Whether traffic is blocked if a violation occurs
  • Whether ASM automatically builds the security policy
  • How inclusive the security policy is
  • How new entities (file types, URLs, parameters, and so on) are learned: never learn new entities, learn if there are violations on an entity (selective mode), learn all entities that are discovered in the traffic.
  • Which violations to enforce and how to enforce them
  • Which IP addresses to trust traffic and data from
  • Whether learning is available for every particular attribute

There are two levels of policy building settings: basic and advanced. The basic settings are sufficient for most installations, and require less work. Selecting the policy template causes ASM to choose reasonable values for the advanced settings.

The advanced level allows you to view and change all of the configuration settings if you want further control over security policy details. However, in most cases, you do not need to change the default values of these settings. F5 recommends that you use the default settings unless you are technically familiar with the web application being protected, and with ASM.

Task summary

Changing how to build a security policy

If you are an advanced user, you can review or adjust the settings that the system uses to build or fine-tune a security policy. In most cases, you do not need to change the values of these settings.

  1. On the Main tab, click Security > Application Security > Policy Building > Learning and Blocking Settings .
    The Learning and Blocking Settings screen opens.
  2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
  3. Adjust the Enforcement Mode setting if needed.
    • To block traffic that causes violations, select Blocking.
    • To allow traffic even if it causes violations (allowing you to make sure that legitimate traffic would not be blocked), select Transparent.
    You can only configure the Block flag on violations if the enforcement mode is set to Blocking.
  4. For Learning Mode, select how you want the Policy Builder to build the security policy.
    • If you want the Policy Builder to automatically build the security policy, select Automatic.
    • If you want the Policy Builder to make suggestions and manually decide what to include, select Manual.
    • If you do not want the system to suggest policy changes, select Disabled.
    If you selected Automatic or Manual, the system examines traffic and makes suggestions about how to tighten the security policy. If you are using automatic learning, the system enforces the suggestions when it is reasonable to do so. If you are using manual learning, you need to examine the changes and accept, delete, or ignore them on the Traffic Learning screen. If you disabled this option, the system does not do any learning for this policy, it makes no suggestions, and the Learn flag for all violations becomes inactive.
  5. For Learning Speed, select how fast to build the security policy:
    Option Description
    Fast Builds a security policy using lower threshold values for the rules so they are likely to meet the thresholds more quickly; for example, this setting is useful for smaller web sites with less traffic. Selecting this value may create a less accurate security policy.
    Medium Builds a security policy based on greater threshold values for the rules. This is the default setting and is recommended for most sites.
    Slow Builds a security policy using even higher thresholds for the rules and takes longer to meet them; for example, this value is useful for large web sites with lots of traffic. Selecting this value may result in fewer false positives and create a more accurate security policy.
    A faster learning speed causes the system to make more learning suggestions for changes to the policy in a shorter time. A slower learning speed causes the system to examine more traffic before making learning suggestions.
    If you are using automatic learning and a faster learning speed, the system enforces the learning suggestions more quickly. If you are using automatic and slower learning, it takes longer to build and enforce the security policy. If you are using manual learning at any learning speed, you have to manually enforce the learning suggestions.
  6. On the right side of the Learning and Blocking Settings screen, select Advanced.
    The screen displays the advanced configuration details for policy building.
  7. Expand any setting by clicking it.
    The Policy Building Settings provide blocking settings for violations, learning settings for entities (file types, URLs, parameters, cookies, and redirection domains).
    The Policy Building Process settings let you adjust details about how the security policy is built, such as minimizing false positives, allowing trusted IP addresses, whether to learn from responses, and the advanced settings let you adjust rules for when to relax or tighten the security policy.
  8. Review the settings and modify them as needed. Refer to the online help for details on each of the settings.
  9. Click Save to save your settings.
  10. To put the security policy changes into effect immediately, click Apply Policy.

By adjusting the policy building settings, you change the way that Application Security Manager™ creates the security policy.

Adding trusted IP addresses to a security policy

In a security policy, you can include a list of IP addresses that you want the system to consider safe or trusted. Take care when specifying trusted IP addresses. Trusted IP addresses are typically internal IP addresses to which only trusted users have access. You configure all trusted IP addresses as IP address exceptions.

  1. On the Main tab, click Security > Application Security > Policy Building > Learning and Blocking Settings .
    The Learning and Blocking Settings screen opens.
  2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
  3. On the right side of the Learning and Blocking Settings screen, select Advanced.
    The screen displays the advanced configuration details for policy building.
  4. To use a global list of trusted IP addresses, in the Policy Building Process area, select Advanced (on the right), then expand Trusted IP Addresses.
    1. Select Address List and click Save.
    2. If the list is empty or you want to add trusted IP addresses, click the arrow next to Trusted IP Addresses to jump to the IP Address Exceptions list where you can specify which IP addresses to consider safe.
  5. To trust all IP addresses (for internal or test environments), in the Policy Building Process area, expand Trusted IP Addresses, and select All IP Addresses.
    Warning: Use this option only in test environments where all clients are known to be legitimate, and the goal is to quickly build a security policy for the production environment. If you are not using it in the proper environment, the policy could be compromised as each request will be considered legitimate, and all violations will be considered false positives and disabled in the policy.
  6. Click Save to save your settings.
  7. To put the security policy changes into effect immediately, click Apply Policy.

Application Security Manager™ (ASM) processes traffic from trusted clients differently than traffic from untrusted clients. For clients with trusted IP addresses, the rules are configured so that ASM™ requires less traffic (by default, only 1 user session) to update the security policy or make suggestions about adding an entity or making other changes. It takes more traffic from untrusted clients to change or suggest changes to the security policy (for example, if using the default values).

Learning host names automatically

The security policy maintains a list of the host names that can access the web application. Your security policy can automatically learn host names from requests if you use certain options.
Note: If you are creating a security policy with automatic learning, the default option for all policy templates is already set to learn host names automatically. The steps here explain the options to configure ASM™ to automatically detect and learn host names for your application if the option has been disabled.
  1. On the Main tab, click Security > Application Security > Policy Building > Learning and Blocking Settings .
    The Learning and Blocking Settings screen opens.
  2. Ensure that the Learning Mode is set to Automatic.
    The system examines the traffic to the web application, and after processing sufficient legitimate traffic, the system builds the security policy automatically by adding and enforcing elements with minimal manual intervention. A few learning suggestions require your review before they are added.
  3. On the right side of the Learning and Blocking Settings screen, select Advanced.
    The screen displays the advanced configuration details for policy building.
  4. In the Policy Building Settings area, expand Headers and ensure that Learn Host Names is selected.
    Tip: Click the arrow next to the setting to jump to the list of host names already recognized by the security policy.
  5. Click Save to save your settings.
  6. In the editing context area, click Apply Policy to put the changes into effect.
The security policy searches headers for valid host names. When a host name is found, ASM creates a suggestion to add the host name to the policy. When the learning score reaches 100%, the suggestion is automatically accepted, or you can accept the suggestion manually on the Traffic Learning screen. The host names in the security policy (also called the host headers) are included in the Host Names list.

Classifying the content of learned parameters

When using automatic learning, you can instruct the system to examine and classify the content of learned parameters. If the system detects legitimate XML or JSON data in parameters, the system adds (or suggests adding) XML or JSON content profiles to the security policy and configures them using the data found.

  1. On the Main tab, click Security > Application Security > Policy Building > Learning and Blocking Settings .
    The Learning and Blocking Settings screen opens.
  2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
  3. In the General Settings, for Learning Mode, ensure that it is set to Automatic.
  4. On the right side of the Learning and Blocking Settings screen, select Advanced.
    The screen displays the advanced configuration details for policy building.
  5. In the Policy Building Settings area, expand Parameters.
  6. Select Classify Value Content of Learned Parameters.
  7. Click Save to save your settings.
  8. To put the security policy changes into effect immediately, click Apply Policy.
If XML or JSON data is discovered in parameters, the system creates the appropriate content profile and add it (or suggests adding it) to the security policy.

Specifying whether to learn integer parameters

Integer parameters are parameters with a data type that is numeric and can include only whole numbers. If a security policy is learning parameters (when Learn New Parameters is set to Selective or Add All Entities), you can specify whether the Policy Builder suggests adding integer parameters to the security policy. This option is available only when the learning mode is set to automatic.

  1. On the Main tab, click Security > Application Security > Policy Building > Learning and Blocking Settings .
    The Learning and Blocking Settings screen opens.
  2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
  3. On the right side of the Learning and Blocking Settings screen, select Advanced.
    The screen displays the advanced configuration details for policy building.
  4. In the Policy Building Settings area, expand Parameters.
  5. Set Learn New Parameters to either Always or Selective.
  6. Select Learn Integer Parameters.
  7. Click Save to save your settings.
  8. To put the security policy changes into effect immediately, click Apply Policy.

When the Application Security Manager™ receives a request that includes an entity (for example, a URL) containing an integer parameter, the system collects the parameter value from the web application’s response to the request and suggests adding it to the security policy.

Specifying when to learn dynamic parameters

Dynamic parameters are those whose values are regenerated when the user accesses an application. For example, a session ID is a dynamic parameter, and it is linked to a user session. The system can extract dynamic parameters from parameters, URLs, and file types. You can specify the conditions under which the Policy Builder suggests adding dynamic parameters to the security policy. This option is available only when the learning mode is set to automatic.

  1. On the Main tab, click Security > Application Security > Policy Building > Learning and Blocking Settings .
    The Learning and Blocking Settings screen opens.
  2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
  3. Ensure that the Learning Mode is set to Automatic.
  4. On the right side of the Learning and Blocking Settings screen, select Advanced.
    The screen displays the advanced configuration details for policy building.
  5. In the Policy Building Settings area, expand Parameters.
  6. Set Learn New Parameters to either Always or Selective.
  7. For Learn Dynamic Parameters, select one or more of the check boxes to specify the conditions under which the Policy Builder adds dynamic parameters to the security policy.
    Option Description
    All HIDDEN Fields Adds to the security policy all hidden form input parameters, seen in responses, as dynamic content value parameters.
    Using statistics - FORM parameters Adds parameters from forms as dynamic content value parameters.
    Using statistics - link parameters Adds parameters from links as dynamic content value parameters.
    Statistics: Configure parameters as dynamic if <num>... Specifies the number (<num>) of unique value sets that must be seen for a parameter before the system considers it a dynamic content value. The default value is 10.
  8. In the Policy Building Process area, expand Options and ensure that Learn from responses is selected.
  9. Click Save to save your settings.
  10. To put the security policy changes into effect immediately, click Apply Policy.

When the Application Security Manager™ receives a request that includes an entity (for example, a file extension or URL) containing a dynamic parameter, the system collects the parameter value or name from web application’s response to the request and suggests adding it to the security policy.

Collapsing entities in a security policy

When using automatic policy building, the system automatically simplifies your security policy by combining several similarly named explicit entities into wildcard entities. For example, multiple parameters beginning with param are combined into param*. You can specify which entities should be collapsed and after how many occurrences.

  1. On the Main tab, click Security > Application Security > Policy Building > Learning and Blocking Settings .
    The Learning and Blocking Settings screen opens.
  2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
  3. On the right side of the Learning and Blocking Settings screen, select Advanced.
    The screen displays the advanced configuration details for policy building.
  4. To collapse URLs, in the Policy Building Settings area, expand URLs.
    1. Select Collapse many common URLs into one wildcard URL.
      The system collapses URLs only in the same directory (with the same prefix path), and if they have the same file extension. For example, the system collapses the URLs /aaa/x.php, /aaa/y.php, and /aaa/z.php into /aaa/*.php.
    2. In the adjacent occurrences field, type the number of occurrences (2 or more) the system must detect before collapsing URLs into one entity. The default value is 500.
    3. In the following depth field, type the minimum depth for collapsing path segments (for example, /aa/bb/x.php has a depth of 3). The default value is 2.
  5. To collapse parameters, in the Policy Building Settings area, expand Parameters.
    1. Select Collapse many common Parameters into one wildcard Parameter.
    2. In the adjacent occurrences field, type the number of occurrences (2 or more) the system must detect before collapsing them to one entity. The default value is 10.
  6. To collapse cookies, in the Policy Building Settings area, expand Cookies.
    1. Select Collapse many common Cookies into one wildcard Cookie.
    2. In the adjacent occurrences field, type the number of occurrences (2 or more) the system must detect before collapsing them to one entity. The default value is 10.
  7. Click Save to save your settings.
  8. To put the security policy changes into effect immediately, click Apply Policy.
When the traffic includes sufficient occurrences of the URLs, parameters, cookies, and/or content profiles, the system collapses multiple similar entities into a wildcard entity in the appropriate list unless the collapse would lead to a loss of security policy information.

Changing how cookies are enforced

You can change the way cookies are enforced in the security policy. To make these changes, you need to understand how your application uses cookies. Does the application server set most or all of the cookies, and are they not modified on the client? Or does your application allow cookies to be modified?
  1. On the Main tab, click Security > Application Security > Policy Building > Learning and Blocking Settings .
    The Learning and Blocking Settings screen opens.
  2. On the right side of the Learning and Blocking Settings screen, select Advanced.
    The screen displays the advanced configuration details for policy building.
  3. In the Policy Building Settings area, expand Cookies and ensure that Learn New Cookies is set to Selective.
  4. In the cookies settings, consider how to set the Learn and enforce new unmodified cookies check box. Are cookies set by the application server and not modified on the client side?
    • If yes, clear this check box and make sure the * cookie wildcard is an enforced cookie. Only the cookies that are modified or created on the client side are learned as allowed cookies.
    • If no, select this check box and make sure the * cookie wildcard is an allowed cookie.
    Check the * cookie wildcard by viewing Security > Application Security > Headers > Cookies List .
    Note: Security policies created using the comprehensive template are set to learn and enforce new unmodified cookies by default.
  5. Click Save to save your settings.
  6. In the editing context area, click Apply Policy to put the changes into effect.
If Learn and enforce new unmodified cookies is selected, the system creates new enforced cookies if these two conditions are met:
  • The * cookie wildcard is an allowed cookie
  • Learn New Cookies is set to Selective
If you clear the Learn and enforce new unmodified cookies check box, the system learns the modified cookies when:
  • The * cookie wildcard is an enforced cookie
  • Learn New Cookies is set to Selective
  • The Learn flag of the Modified domain cookie(s) violation is selected

If a request causes the Modified domain cookie(s) violation, the system changes their type from “enforced” to “allowed” (in the GUI they are moved between the tabs).

In cases where you want all cookies to be enforced, the * cookie wildcard must be an allowed cookie. If you do not want all cookies to be enforced, the * cookie wildcard must be an enforced cookie. In either case, set Learn New Cookies to Never (wildcard only) and clear the Learn and enforce new unmodified cookies check box.

Limiting the maximum number of policy elements

When building a security policy using automatic or manual learning, the system has reasonable limits for the maximum number of file types, URLs, parameters, cookies, and redirection domains that the system can learn and add to the security policy. These limits work fine for most situations. You can adjust the limits, if needed. Note that you can always add an entity manually even after the limits are reached.

  1. On the Main tab, click Security > Application Security > Policy Building > Learning and Blocking Settings .
    The Learning and Blocking Settings screen opens.
  2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
  3. On the right side of the Learning and Blocking Settings screen, select Advanced.
    The screen displays the advanced configuration details for policy building.
  4. In the Policy Building Settings area, expand the type of entity for which you want to adjust the limit (File Types, URLs, Parameters, Cookies, or Redirection Protection), and in the appropriate Maximum Learned setting, adjust the maximum number of elements that the Policy Builder can add to the security policy.
    • Maximum Learned File Types
    • Maximum Learned HTTP URLs
    • Maximum Learned WebSocket URLs
    • Maximum Learned Parameters
    • Maximum Learned Cookies
    • Maximum Learned Redirection Domains
    Default values differ depending on the Learn New setting.
  5. Click Save to save your settings.
  6. To put the security policy changes into effect immediately, click Apply Policy.
If the Policy Builder reaches the specified limit, it stops adding that type of security policy element. If this happens, you may need to intervene.
  • If the web site requires more than the maximum number of elements, you can increase the limits, or reconsider the type of the policy (you may not need to include all the elements explicitly).
  • If the site includes a dynamic element that the Policy Builder cannot learn (such as dynamic sessions in URL or dynamically generated parameter names), either configure the security policy to include the element (for example, dynamic sessions in URL), or clear the element type. The Policy Builder should not be configured to learn that element type in such an environment.
  • If you want to maintain the limits, you can add the required entities manually.

Classifying the content of requests to URLs

When using automatic learning, you can instruct the system to examine and classify the content of requests to URLs. If the system detects legitimate XML, JSON, or Google Web Toolkit (GWT) data in requests to URLs configured in the security policy, the system adds XML, JSON, or GWT content profiles to the security policy and configures them using the data found.

  1. On the Main tab, click Security > Application Security > Policy Building > Learning and Blocking Settings .
    The Learning and Blocking Settings screen opens.
  2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
  3. In the General Settings, for Learning Mode, ensure that it is set to Automatic.
  4. On the right side of the Learning and Blocking Settings screen, select Advanced.
    The screen displays the advanced configuration details for policy building.
  5. In the Policy Building Settings area, expand URLs.
  6. For Learn New HTTP URLs or Learn New WebSocket URLs, specify Selective or Always to determine when to add explicit URLs to the security policy.
    • Choose Selective to add explicit URLs that do not match the * wildcard.
    • Choose Always to create a comprehensive whitelist of all the website URLs.
    Using these options activates the Classify Request Content of Learned URLs check box.
  7. Select Classify Request Content of Learned URLs.
  8. Click Save to save your settings.
  9. To put the security policy changes into effect immediately, click Apply Policy.
If XML, JSON, or GWT data is discovered in requests to URLs in the security policy, the system creates the appropriate content profiles and adds them to the policy.

Specifying the file types for wildcard URLs

For security policies that are tracking URLs (policies that use the comprehensive template), the system adds a wildcard URL instead of explicit URLs for commonly used file types. You can adjust the list of file types that are changed to wildcard URLs.

  1. On the Main tab, click Security > Application Security > Policy Building > Learning and Blocking Settings .
    The Learning and Blocking Settings screen opens.
  2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
  3. On the right side of the Learning and Blocking Settings screen, select Advanced.
    The screen displays the advanced configuration details for policy building.
  4. In the Policy Building Settings area, expand URLs.
  5. In the File types for which wildcard HTTP URLs will be configured setting, add or delete the file types for which the Policy Builder creates a wildcard URL instead of adding an explicit URL.
    Common file types are included by default. Note that the setting is unavailable in policies that do not include URLs (such as if Learn New HTTP URLs is set to Never).
    • To add file types, in the File types field adjacent to the Add button, type the file extension and click Add.
    • To remove file types, select the file type and click Delete.
  6. Click Save to save your settings.
  7. To put the security policy changes into effect immediately, click Apply Policy.
For the file types listed, the Policy Builder adds wildcards instead of explicit URLs when encountering them in web application traffic. Also, the wildcards are added to the policy as non-case sensitive; for example, .jpg URLs are added as *.[Jj][Pp][Gg] instead of image1.jpg, IMAGE2.JPG, and image3.jpg.

Disabling full policy inspection

Application Security Manager™ provides full functionality, and performs full policy inspection, and holds in memory information about the configuration of entities that are included in a security policy. In rare cases, such as on systems with limited memory or when instructed to do so by F5 Support, you might need to disable full policy inspection.

Note: F5 does not recommend disabling full policy inspection.
  1. On the Main tab, click Security > Application Security > Policy Building > Learning and Blocking Settings .
    The Learning and Blocking Settings screen opens.
  2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
  3. On the right side of the Learning and Blocking Settings screen, select Advanced.
    The screen displays the advanced configuration details for policy building.
  4. To turn on memory optimization and limit the elements that the security policy stores in memory, in the Policy Building Process area, expand Options and clear the Full Policy Inspection check box.
  5. Click Save to save your settings.
  6. To put the security policy changes into effect immediately, click Apply Policy.

If you disable the Full Policy Inspection check box, the system does not store all the information about the policy elements in memory, thus it enables memory optimization. However, you lose some functionality. When the setting is disabled, the system cannot collapse URLs, WebSocket URLs, parameters, or content profiles (the collapse settings are cleared, become unavailable, and cannot be changed). The system no longer performs classification for parameters, URLs, or WebSocket URLs.

Disabling full policy inspection causes pabnagd (policy building daemon) to restart in 5 minutes. The delay allows time to disable the check box on more than one policy. The restart does not affect traffic throughput.

Stopping and starting automatic policy building

You can use the Real Traffic Policy Builder® to automatically build a security policy in two ways: with automatic learning or manual learning. When you set Learning Mode to automatic, the Policy Builder makes suggestions on how to update the security policy and updates the security policy when the policy building rules are met. It does this by automatically enforcing the suggested changes, adding file types, URLs, parameters, and so on for the web application. The Policy Builder also operates when you set Learning Mode to manual. In this case, the Policy Builder examines traffic, and makes suggestions on what to add to the security policy or what to change in the policy settings but you have to implement them.

  1. On the Main tab, click Security > Application Security > Policy Building > Learning and Blocking Settings .
    The Learning and Blocking Settings screen opens.
  2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
  3. In the General Settings, for Learning Mode, select how you want to build the security policy:
    Option Who builds the security policy?
    Automatic The Policy Builder. It examines traffic, makes suggestions, and enforces most suggestions after sufficient traffic over a period of time from various users makes it reasonable to add them. You may have to enforce a few suggestions manually, and you have the option of enhancing the policy manually.
    Manual The Policy Builder and you together. The Policy Builder examines traffic and makes suggestions on what to add to the security policy. You need to manually handle the suggestions on the Traffic Learning screen, and optionally adjust the security policy.
    Disabled You. The Policy Builder does not do any learning for the security policy, and makes no suggestions. Based on your knowledge of the web application, you can manually add entities to the security policy and adjust the policy building settings.
  4. Click Save to save your settings.
  5. To put the security policy changes into effect immediately, click Apply Policy.

If you set learning mode to automatic, the Policy Builder automatically discovers and populates the security policy with the policy elements (such as file types, URLs, parameters, and cookies). If you are using manual learning, the Policy Builder examines traffic and makes suggestions on ways to adjust the security policy; changes are implemented only when you approve them. You can manually accept, delete, or ignore the suggestions on the Traffic Learning screen.

If you disable the learning mode, all learning suggestions are deleted and no more learning takes place; the security policy remains the same unless you manually change it. If you enable manual or automatic learning later, the learning process starts over. Regardless of the learning mode, you can always monitor the policy and manually change it.