Step 2. Build a Rule Statement

[#1]

Step 2. Build a Rule StatementStep 2. Build a Rule Statement

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.

ExampleExample

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.

PrerequisitesPrerequisites

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.

Meta entities are not currently supported, such as:

fullname.all

eth.all

ip.all

ipv6.all

port.src.all

port.dst.all

dir.path.all

org.all

geoip.all

port.all

domain.all

email.all

filename.all

directory.all

checksum.all

param.all

context.all

attack.all

analysis.all

compromise.all

inv.all

outcome.all

ec.all

user.all

host.all

client.all

Caution: If you add meta entities to your rule, they cannot get data from the data sources, so they do not trigger alerts.

Build a Rule StatementBuild a Rule Statement

1. Go to (Configure) > ESA Rules.

   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 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​
   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." (For best rule performance, only use the Ignore Case option when necessary.)

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

1. After you add a meta condition, click and select Add Whitelist Condition.
2. 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.

3. For the subcondition:

   1. 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".
   2. 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 BlacklistTo 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.

1. After you add a meta condition, click and select Add Blacklist Condition.
2. 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.

3. For the subcondition:

   1. 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".
   2. 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: BlacklistExample: 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: Strict Pattern Matching and Using the Is Not Null OperatorExample: Strict Pattern Matching and Using the Is Not Null Operator

The following example uses the ability to 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, ip_src	The GroupBy field ensures that all the previous conditions are grouped by the user_dst meta (the user destination account) and ip_src. 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 ip_src 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 specified with 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	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. For best rule performance, only use the Ignore Case option when necessary.
ec_outcome is Failure	Identifies activity outcome logged as "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 ResultsExample 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 view by clicking on the source for one of the events, you can see the case for each of the string values.

Example: Grouping the Rule ResultsExample: 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 user_dst and ip_src.

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

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 ip_src	Groups the rule results by user_dst (user destination account) and ip_src (IP address of the machine that 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 OperatorsExample: 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.

Previous Page	Next Page