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 CONFIGURE > ESA Rules > Settings > Meta Key References.

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 operator that you use depends on the metadata type.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 (<=), is one of (For array type meta), is not one of (For array type meta), 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 entities are excluded from triggering the rule. Whitelists can be based on geographic location, in-memory enrichment, or Context Hub list 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 in-memory enrichment, Context Hub list, or a named window in Esper can be used as the source for a whitelist.

For the subcondition:

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".

If you used a Context Hub list for the whitelist, select a column name from the list, then select an operator and enter the meta value for the corresponding value field.

Note: An Entity is a specified piece of meta, such as IP address, MAC address, user, host, domain, file name, or file hash.

To Add a Blacklist

You use a blacklist to ensure that specified entities trigger the rule. Blacklists can be based on geographic location, in-memory enrichment, or Context Hub list 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 Name field, select an enrichment source. Any in-memory enrichment, Context Hub list, or a named window in Esper can be used as the source for a blacklist.

For the subcondition:

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".

If you used a Context Hub list for the blacklist, select a column name from the list, then select an operator and enter the meta value for the corresponding value field.

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.

Statement

Description

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:

Rule Condition

Description

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, device class

The 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 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:

Rule Statement

Description

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:

Rule Statement

Description

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:

Rule Statement

Description

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.

Example Results

When the alert fires for the above 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.

The following figure shows the alert in the Respond Alerts List view.

The next figure shows the events in the alert in the Respond Alert Details view.

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.

Rule Condition

Description

Failed Logins

Identifies five failed login attempts (must be followed by the next condition; that is, 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, that is, 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.

Rule Statement

Description

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.