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.
The following graphic shows an example of a Rule Builder statement.
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.
To build a rule statement:
In the Security Analytics menu, select Alerts > Configure.
The Rules tab is displayed by default.
The Rule Builder view is displayed.
The Build Statement dialog is displayed.
- Name the statement. Be clear and specific. The statement name will appear in the Rule Builder.
From the drop-down list, select which circumstances the rule requires:
- if all conditions are met
- if one of these conditions are met
Specify the criteria for the statement:
- For Key, type the name of the Meta Key.
- 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
- Type the Value for the meta key.
Do not add quotes around a value. Separate multiple values with a comma.
- 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."
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.
- To use another meta key in the statement, click , select Add Meta Condition and repeat step 6.
- To add a whitelist, click and select Add Whitelist Condition. .
- To add a blacklist, click and select Add a Blacklist Condition.
- 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.
- After you add a meta condition, click and select Add Whitelist Condition.
- 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.
- 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.
- After you add a meta condition, click and select Add Blacklist Condition.
- 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.
- 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".
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.
|service is not 25||The traffic is not SMTP traffic.|
|tcp_dstport is 25||The traffic is running on TCP port 25.|
|extension is exe, com,vb,vbs,vbe,cmd,bat,ws,wsf,src,sh||The file extension is an executable.|
|GeoIpLookup||The blacklist is based on a GeoIPLookup source.|
|ipv4 is ip_src||The 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:
|Failures||This condition searches for five failed logins with a "followed by" connector, meaning that the condition (Failures) must be followed by the next condition (Success).|
|Success||This condition searches for one successful login.|
|ModifyPassword||This condition searches for an instance where the password is modified.|
|GroupBy: user_dst||The GroupBy field ensures that all the previous conditions are grouped by the user_dst meta (the user destination account). 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. The rule may give unexpected results if you do not group it by the user destination account.|
|Occurs within 5 minutes||The 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: Strict||The 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:
|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 null||Ensures 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:
|ec_activity is Logon||Identifies logon activity.|
|ec_outcome is Success||Identifies a logon that is successful.|
|user_dst is not null||Ensures that user destination account field must be populated for the condition to be true.|
The following statement makes up the ModifyPassword condition:
|user_dst is not null||Ensures the user destination account field must be populated for the condition to be true.|
|ec_subject is Password||Identifies a subject of Password.|
|ec_activity is Modify||Identifies activity where the password was modified.|
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.
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.
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.
|Failed Logins||Identifies 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 Login||Identifies one successful login.|
|Group By: user_dst and device_class||Groups 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 match||The 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.
|ip_dst is 10.10.10.1||The destination port is 10.10.10.1.|
|ip_dstport is greater than or equal to 1024||The destination port is in a commonly used port range, 1024 or greater.|
|size is greater than or equal to 10000||The size of the transfer is 10000 or greater, which is a suspiciously large transfer.|
|payload is greater than 7000||The payload is between 7000 and 8000, which is a suspiciously large payload.|
|payload is less than 8000||The payload is between 7000 and 8000, which is a suspiciously large payload.|