Configure Character Case for Advanced ESA Rules

Note: This procedure applies only to ESA Correlation Rules in NetWitness Platform 11.3.0.2 and later versions, however, it is not supported in version 11.3.1.0.

Advanced Event Processing Language (EPL) rules require correct character case, but in the Investigate Navigate view all characters are converted to lowercase. However, the meta keys may not be lowercase despite appearances in the Investigate Navigate view. To ensure you are using the correct case, you can use the toLowerCase() function. However, care should be taken to only add the case-insensitive toLowerCase() function on string and string array meta keys as needed. The toLowerCase() function can cause significant performance decreases. Consider checking the Investigate Events view or the Event Analysis view to see the real character case for meta fields and avoid unnecessary usage of the function. For more information, see "Event Process Language (EPL)" in the Alerting with ESA Correlation Rules User Guide.

You can optimize your rule performance by identifying the meta keys used most often in your environment. Instead of using the toLowerCase() function with the original meta key, replace the meta key throughout the rule with <meta.key>_lower. You can also use the special case-insensitive meta keys in your Rule Builder rules.
For example, you can configure ESA Correlation to use filename_lower (which is case insensitive) instead of using the original filename meta key. In your rule, replace filename with filename_lower.

To configure special case-insensitive meta keys to use in your ESA rules:

  1. Go to netwitness_configureicon_24x21.png (Configure) > ESA Rules > Rules tab. In your ESA rule deployments, identify any ESA rules using the toLowerCase() function more than ten times for a particular string or string array meta key. Keep track of these ESA rules and meta keys.
  2. Go to netwitness_adminicon_25x22.png (Admin) > Services, select an ESA Correlation service, and then select netwitness_ic-actns.png > View > Explore.
  3. In the Explore view node list, select correlation > stream.
    Notice that there is a lowercase parameter with empty values.
    netwitness_121_lowercaseparam_1122.png
  4. Update the lowercase parameter with the string or string array meta keys identified in step 1 using a comma separated list, for example: protocol,alias.host,action,alert

    Note: String and string array are the only data types supported for the ESA Correlation service lowercase parameter.

    Use NWDB format (decimal), NOT Esper format (underscore). Do not press Enter to commit or it will put in a return. Instead, click another parameter.


  5. After you add all of the meta keys, validate the meta keys on ESA.

    1. Go to netwitness_configureicon_24x21.png (Configure) > ESA Rules > Settings tab > Meta Key References and click the Meta Re-Sync (Refresh) icon (netwitness_ic-refresh.png).
    2. Search for _lower or <meta key>_lower, for example: protocol_lower.
      • The meta keys with a string array type should show a value of string[].
      • The meta keys with a string type should show a value of string (without the brackets).

  6. Update all of your ESA rules that use .toLowerCase meta keys and replace them with <meta key>_lower (Example: filename_lower IN ('svchost.exe'))

  7. Deploy the ESA rule deployment again.

Note: If you remove a meta key from the lowercase parameter list and re-sync the meta key references, you also need to update the rules that use the corresponding lowercase meta key (<meta.key>_lower).