Alerting: Step 2. Build a Rule Statement

Document created by RSA Information Design and Development on Jun 26, 2017•Last modified by RSA Information Design and Development on Sep 14, 2017
Version 2Show Document
  • Comment • 0
  • View in full screen mode
  

 

This topic provides instructions to define rule criteria in Rule Builder by adding statements. A statement is a logical grouping of rule criteria in the Rule Builder. You add statements to define what a rule detects. 

Example

The following graphic shows an example of a Rule Builder statement.

Every statement contains a key and value. Then, you build logic around the pair by selecting an option in each other field.

Prerequisites

To build a rule statement, you must know the meta key and the meta value.
For a complete list of meta keys, go to Alerts > Configure > Settings > Meta Key References.

Procedure

To build a rule statement:

  1. In the Security Analytics menu, select Alerts > Configure.

    The Rules tab is displayed by default.

  2. In the Rule Library, click  > Rule Builder or edit an existing Rule Builder rule.

    The Rule Builder view is displayed.

  3. In the Conditions section, click  .

    The Build Statement dialog is displayed.

  4. Name the statement. Be clear and specific. The statement name will appear in the Rule Builder.

  5. From the drop-down list, select which circumstances the rule requires:

    • if all conditions are met
    • if one of these conditions are met

  6. Specify the criteria for the statement:

    1. For Key, type the name of the Meta Key.
    2. For Operator specify the relationship between the meta key and the value you will provide for it.
      The choices are:  is, is not, is not null, is greater than (>), is greater than or equal to (>=), is less than (<), is less than or equal to (<=), contains, not contains, begins with, ends with
    3. Type the Value for the meta key.
      Do not add quotes around a value. Separate multiple values with a comma.
    4. The Ignore Case? field is designed for use with string  and string array values. By choosing the Ignore Case field, the query will treat all string text as a lowercase value.  This ensures that a rule that searches for the user named Johnson would trigger if the event contains "johnson," "JOHNSON," or "JoHnSoN."

    5. The Array?field indicates if the contents of the Value field represent one or more than one value.

      Select the Array checkbox if you entered multiple, comma-separated values in the Value field. For example, "ec_activity is Logon, Logoff" requires you to select the Array checkbox.

  7. To use another meta key in the statement, click , select Add Meta Condition and repeat step 6. 
  8. To add a whitelist,  click  and select Add Whitelist Condition. .
  9. To add a blacklist,  click  and select Add a Blacklist Condition.
  10. To save the statement, click Save. 

To Add a Whitelist

You use a whitelist to ensure that specified  events are excluded from triggering the rule.  Whitelists can be based on geographic location or by customer-defined enrichment CSV sources.  For example, if you want to create a rule that only triggers for IP addresses outside of the US, you can create a whitelist of US IP addresses.

  1. After you add a meta condition, click Add icon and select Add Whitelist Condition.
  2. In the EnterWhitelist Name field, select an enrichment source. Any enrichment source loaded from a  CSV or a named window in Esper can be used as source for a whitelist. 
  3. If you used a GeoIP source for the whitelist, ipv4 is automatically entered for the subcondition. Enter the meta value for the corresponding value field. For example, enter ipv4 is ip_src to ensure the GeoIP records are selected based upon the ip_src being found in the GeoIP lookup database. In addition, if you used a GeoIP source for the whitelist, you might want to add a subcondition to specify the geographic region to exclude from the rule results. For example, to specify that the country code must be USA, enter "CountryCode is US".

To Add a Blacklist

You use a blacklist to ensure that specified events trigger the rule. Blacklists can be based on geographic location or by customer-defined enrichment CSV sources. For example, you can specify that the rule only includes results from Germany. 

  1. After you add a meta condition, click Add icon and select Add Blacklist Condition.
  2. In the Enter Blacklist Namefield, select an enrichment source.  Any enrichment source loaded from a  CSV or a named window in Esper can be used as source for a blacklist. 
  3. If you used a GeoIP source for the blacklist, ipv4 is automatically entered for the subcondition. Enter the meta value for the corresponding value field. For example, enter ipv4 is ip_src to ensure the GeoIP records are selected based upon the ip_src being found in the GeoIP lookup database.  In addition, if you used a GeoIP source for the blacklist, you might want to add a subcondition to specify the geographic region to include in the rule results. For example,  to specify that the rule only includes results for Germany, enter "CountryCode is DE".

Example: Blacklist

The following statement shows a blacklist statement for a rule that monitors for non-SMTP traffic on TCP destination port 25 containing an executable from countries that are outside of the United States. 

Blacklist_example.png

                                 
 StatementDescription
service is not 25The traffic is not SMTP traffic. 
tcp_dstport is 25The traffic is running on TCP port 25. 
extension is exe, com,vb,vbs,vbe,cmd,bat,ws,wsf,src,shThe file extension is an executable.
GeoIpLookupThe blacklist is based on a GeoIPLookup source.
ipv4 is ip_srcThe GeoIP records are selected based upon the ip_src being found in the GeoIP lookup database. 
countryCode is not US When looking up the IP address Event.ip_src in the GeoIP database, the record it returns does not contain "US" in the countryCode field.

Example: Ignoring Case, Strict Pattern Matching, and Using The Is Not Null Operator

The following example uses the ability to ignore case, exclude null values, and create a strict pattern match to ensure that it returns the expected rule results. The following conditions make up the rule:

                                 
Rule ConditionDescription
FailuresThis condition searches for five failed logins with a "followed by" connector, meaning that the condition (Failures) must be followed by the next condition (Success).
SuccessThis condition searches for one successful login. 
ModifyPasswordThis condition searches for an instance where the password is modified.
GroupBy: user_dst, device classThe GroupBy field ensures that all the previous conditions are grouped by the user_dst meta (the user destination account) and device class. This is important to the construction of the rule because the rule attempts to find a case where a user has attempted to log into the same destination account multiple times, finally logged in successfully, and then changed the password. Grouping by device class ensures that the user logged in from the same machine attempted to log into an account multiple times. The rule may give unexpected results if you do not group the results.
Occurs within 5 minutesThe time window for the events to occur is five minutes. If the events occur outside of this time window, the rule does not trigger. 
Event Sequence: StrictThe event sequence is configured for a strict pattern match. This means that the pattern must match exactly as it is specifiedwith no intervening events. 

Strict pattern matching allows you to ensure that the Esper engine only generates alerts for rules that exactly match the pattern you want to find. For example, a common rule might be to search for five failed logins followed by a successful login. If you select a loose pattern match, this rule will trigger if there are any number of successful logins between the failed logins. Since the point of the rule is to find frequent and sequential login attempts, a strict match is required to ensure that you get the results you expect. 

Note: Each of these conditions is explained in further detail in the sections below. 

For each condition, a statement is built in the Rule Builder. The following statement makes up the Failures condition:

RB_Failure_Stmnt.png

                     
Rule StatementDescription
ec-activity is Logon (ignore case)Identifies activity that attempts to log on to a system.

The Ignore Case field is designed for use with string and string array values. By choosing the Ignore Case field, the query will treat all string text as a lowercase value.  You may want to use this field if you are unsure what case may be used when logging a particular event. Because the case is ignored, the rule can trigger if the activity is logged as Logon, logon, or LoGoN.

ec_outcome is Failure (ignore case)Identifies activity outcome logged as "failure." Because the case is ignored, the rule can trigger if the activity is logged as "failure", "Failure," or "FaiLuRe."
user_dst is not nullEnsures that the condition is only true if user_dst is populated.

The is not null operator allows you to ensure that a field returns a value. You may want to use this field when a rule depends on a particular field returning a value. For example, you want to create a rule that identifies the same user attempting to log into the same destination account multiple times (potentially a password-guessing attack). If the field that represents the user destination account is empty, you don't want the rule to trigger. To ensure the field contains a value, you use the is not null operator. 

 

The following statement makes up the Success condition:

RB_Success_Stmnt.png

                     
Rule StatementDescription
ec_activity is LogonIdentifies logon activity. 
ec_outcome is SuccessIdentifies a logon that is successful.
user_dst is not nullEnsures that user destination account field must be populated for the condition to be true. 

 

The following statement makes up the ModifyPassword condition:

RB_Modify_Stmnt.png

 
Rule StatementDescription
user_dst is not nullEnsures the user destination account field must be populated for the condition to be true. 
ec_subject is PasswordIdentifies a subject of Password. 
ec_activity is ModifyIdentifies activity where the password was modified. 

Example Results

When the alert fires for the example rule, you can see that the rule triggered for seven events, and that each event contains a user. You can also see that the events follow a strict pattern: five failed login events, followed by a successful login event, followed by a modification to the account. 

5f_1s_PaswrdChngeAlert.png

Drilling down into the Investigation module by clicking on the source for one of the events, you can see the case for each of the string values. Because you used Ignore Case, the rule would trigger if the string values were upper or lower case. 

5f_1s_PaswrdChngeDetail.png

Example: Grouping the Rule Results

The Group By field allows you to group and filter rule results. For example, suppose that there are three user accounts; Joe, Jane, and John and you use the Group By meta, user_dst. The result will show events grouped under the accounts for Joe, Jane, and John.

You can also group by multiple keys, which can further filter rule results. For example, you might want to group by user destination account and machine to see if a user logged into the same destination account from the same machine attempts to log into an account multiple times.  To do this, you might group by device_class and user_dst.

The following example shows a rule grouped by device_class and user_dst. 

5f_1s_MultiGrpByRule.png

Rule ConditionDescription
Failed LoginsIdentifies five failed login attempts (must be followed by the next condition; i.e., the five failed logins must be followed by a successful login).
Successful LoginIdentifies one successful login. 
Group By: user_dst and device_classGroups the rule results by user_dst (user destination account) and device_class (type of machine the user is logging in from). This allows the rule to look for a user logged in from the same machine to the same destination account, resulting in a much more targeted rule result. 
Occurs within 5 minutes with a strict pattern matchThe events must occur within five minutes, and the pattern matching is strict, meaning it must follow the pattern exactly for the rule to trigger. 

Example: Working with Numeric Operators

Numeric operators allow you to write rules against numeric values, such as specifying that a value is greater than, less than, or equal to a specific value. This is useful particularly for cases where you might want to specify a numeric threshold, i.e., payload is greater than 7000. 

The following example attempts to identify a data transfer to a particular destination through the common ports where the transfer size is high and the payload is in a suspicious range.

BldStmnt_SuspTrans.png

Rule StatementDescription
ip_dst is 10.10.10.1The destination port is 10.10.10.1.
ip_dstport is greater than or equal to 1024The destination port is in a commonly used port range, 1024 or greater.
size is greater than or equal to 10000The size of the transfer is 10000 or greater, which is a suspiciously large transfer. 
payload is greater than 7000The payload is between 7000 and 8000, which is a suspiciously large payload. 
payload is less than 8000The payload is between 7000 and 8000, which is a suspiciously large payload. 
You are here
Table of Contents > Add Rules to the Rules Library > Add a Rule Builder Rule > Step 2. Build a Rule Statement

Attachments

    Outcomes