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:
-
In the Security Analytics menu, select Alerts > Configure.
The Rules tab is displayed by default.
-
In the Rule Library, click
> Rule Builder or edit an existing Rule Builder rule.The Rule Builder view is displayed.
-
In the Conditions section, click
.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".
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.
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:
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:
The following statement makes up the Success condition:
The following statement makes up the ModifyPassword condition:
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.
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.
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.
