This page includes examples of orchestration rules that you can use as a guide when you create your own orchestration rules. The examples use the allowed operators in USM Anywhere. See Operators in the Orchestration Rules and Orchestration Rules Best Practices for more information.
Rules processing is a Boolean query of rules operators. Processing is performed left to right until the rule is either validated (the stated rule action is taken) or invalidated (the processing terminates). The entire rule does not have to be processed, and any additional query operators after this point are discarded.
Example 1: Use the OR Boolean Operators
Match criteria sections in any rule are read and processed from left to right until they are either validated or invalidated. Use extreme care with the application of OR, OR NOT, and AND NOT operators. These can cause a value group to be validated true under all conditions if not properly handled. The outcome of any criteria match operation using the OR operator in the grouped items is not dependent on any other portion of the group to validate or invalidate the group. If any of the match criteria processed in the group validates TRUE, the entire group validates TRUE.
Conversely, the use of the AND operator creates conjoined operations where the group validates true or false based on the outcome of the entire match criteria in the group. All criteria in a group with an AND operator will be processed to determine a TRUE or FALSE outcome.
In the following example of a condition group using OR and OR NOT, the intent is to validate the statement as TRUE if the username is NOT Joe OR NOT Bill OR NOT Bob. This string looks like a correctly formatted rule for that intent:
packet_type == ‘log’ AND ….. AND (! source_username == ‘Joe” OR ! source_username == “Bill’ OR ! source_username == ‘Bob’)
This condition group will ALWAYS validate TRUE regardless of the source_username in the event. This is because if any of the three match criteria elements in the OR NOT condition group is true, the entire group validates true, so if the source_username value is “Bill", the condition group of the rule validates TRUE because the first rule section criteria is met. The second or third sections of the rule are never processed. The proper way to format the rule is to use the AND operator so that each element in the group requires individual validation. The proper formatting for this is the following:
packet_type == ‘log’ AND ….. AND source_username != ‘Joe” AND source_username != “Bill’ AND source_username != ‘Bob’)
Once the rules processor hits the OR operator, it validates the rule criteria and performs the rule action. Any match criteria that follows the OR is not seen.
You can get different results depending on the type of rule you create:
- If it is an alarm rule, every event creates an alarm.
- If it is a suppression rule, every event is suppressed. Keep in mind that suppressed events are not correlated for alarms. See
Suppression Rules from the Orchestration Rules Pagefor more information.
- If it is a notification rule, every event causes a notification action.
- If this is a filter rule, every event is filtered and discarded from your environment. You can't recover these events.
Example 2: Use the Same Criteria in Two Different Rules
When you create a rule, ensure that the rule doesn't match criteria with additional operators of a different rule. For example, look at these two rules:
(packet_type == 'log' AND event_severity == 'ERROR' AND event_category == 'System' AND event_subcategory == 'Microsoft-Windows-WindowsUpdateClient')
(packet_type == 'log' AND event_severity == 'ERROR' AND event_category == 'System' AND event_subcategory == 'Microsoft-Windows-WindowsUpdateClient' AND source_username == 'SYSTEM' AND source_ntdomain == 'NT AUTHORITY')
If the second rule is triggered, the first rule is also triggered, which causes duplicate rule actions. The second rule is essentially the first rule but with more operators.
Example 3: Merge Rules with the Same Format
When you have multiple rules with the same format, you can merge rules and match the difference. For example, instead of having two separate rules, such as this
(packet_type == 'log' AND access_control_outcome == 'Deny' AND source_username == 'VALUE_1')
(packet_type == 'log' AND access_control_outcome == 'Deny' AND source_username == 'VALUE_2')
Or you can merge these rules into this one:
(packet_type == 'log' AND access_control_outcome == 'Deny' AND (source_username == 'VALUE_1' OR source_username == 'VALUE_2'))
Or you can merge the rules into this one:
(packet_type == 'log' AND access_control_outcome == 'Deny' AND source_username in ('VALUE_1','VALUE_2'))
Example 4: Don't Use Rules Criteria of the Same Value Type
Don't use rules criteria of the same value type because they are essentially one and the same in the rule definition. Each "rule_attack_id" item in this format will have "rule_attack_tactic" and "rule_attack_technique" values that are unique to it. By specifying the single detail of "rule_attack_id == 'T####' ", the other match details can be safely removed for rules clarity and rules processing efficiency. Note that the creation of the three match criteria is a normal action of the rules generator.
For USM Anywhere, this rule
(packet_type == 'alarm' AND rule_id == 'Windows New service installed' AND source_ntdomain == 'FINICITY' AND rule_attack_id == 'T1050' AND rule_attack_tactic in ('Persistence', 'Privilege Escalation') AND rule_attack_technique == 'New Service')
is better to write as follows:
(packet_type == 'alarm' AND rule_id == 'Windows New service installed' AND source_ntdomain == 'FINICITY' AND rule_attack_id == 'T1050')
Example 5: Avoid the Use of the regex "match" (~) Criteria
Don't use the regex "match" (~) operator because it can cause a performance issue with the server using it.
Instead of this rule:
(packet_type == 'log' AND event_name == 'PowerShell: EventID 400' AND log ~ /C:\\Scripts\\script.ps1/)
You can use this rule:
(packet_type == 'log' AND event_name == 'PowerShell: EventID 400' AND packet_payload contains 'C:\\Scripts\\script.ps1')
Or you can use this rule:
(packet_type == 'log' AND event_name == 'PowerShell: EventID 400' AND log contains 'C:\\Scripts\\script.ps1')
For data ingestion from syslog sources, the "raw_log" is the entire syslog packet received for processing. This is the syslog format:
<PRI> date/timestamp device hostname/IP address event message/packet payload
The "event message/packet_payload" is the information with the headers stripped off.
For processing purposes, both rules are almost equivalent but packet_payload is the preferred detail to use. Network-based intrusion detection system (NIDS) traffic inspection does not use syslog.
Example 6: Simplify Your Rules
When you have a rule that uses the same operator multiple times, you can simplify it. Look at this example:
(packet_type == ‘log’ AND ( event_name == ‘Value1 OR event_name == ‘Value2’ OR event_name == ‘Value3’))
You can simplify the rule by removing the “OR” operator:
(packet_type == ‘log’ AND event_name in (‘Value1’, ‘Value2’,‘Value3’))
Additionally, USM Anywhere doesn't validate a rule in the case of matching the same event detail information against different match values.
(alarm_source_countries == 'US' AND alarm_source_countries == 'CA')
This event detail has a single set value in the normalized event. It can never validate against multiple values when using the AND operator.
You can instead use one of these two rules:
(alarm_source_countries == 'US' OR alarm_source_countries == 'CA')
Or this rule:
(alarm_source_countries in ('US', 'CA')
Example 7: Boolean Operators Read from Left to Right
Boolean operators in any rule are read and processed from left to right up to the point where the rule is validated (rule action is taken) or invalidated (rule processing terminates). Any additional conditions after the rule has been either validated or invalidated will not be processed.
... AND (match_field != value1 OR match_field != value2)
In the previous example, the use of the “!=” and “OR” operator sets the entire section to TRUE for all values of “match_field”. It will never be processed as FALSE, so any subsequent rule matching operators after this rule section will be processed.
Here's another example:
(packet_type == 'log' AND (event_action == 'Create User' AND (file_permission != 'shared_internally' OR file_permission != 'private'))
In this previous example, the rule portion of (file_permission != 'shared_internally' OR file_permission != 'private') gives the result of true if either of the operators are true. Therefore, if the detail “file_permission” has a value of ‘private’, the entire rule section is still validated as true because the match criteria “file_permission != 'shared_internally' “ is true. The correct implementation would be to use the AND operator at the end, so that the last section of the rule reads (file_permission != 'shared_internally' AND file_permission != 'private').
Example 8: Values Separated by a Comma
When there are two values separated by a comma in an alarm or an event detail, the match criteria will fail if it's matching against only a portion of the detail value. The rule will incorrectly auto-populate using the in operator and not the equals (==) operator. This is due to the comma found in the detail data field. The correct operator to use is the equals (==) operator.
See the RULE ATTACK TACTIC Persistence,Privilege Escalation example from the alarms detail page.
RULE ATTACK TACTIC Persistence,Privilege Escalation
This match criteria is incorrectly auto-populated with the in operator and will always fail:
rule_attack_tactic in ('Persistence','Privilege Escalation')
The comma has separated the match string into two unique values that can never validate. The actual match value is a single string, with the comma included.
It should read like this:
rule_attack_tactic == ('Persistence,Privilege Escalation')
Note that the single quotes establishes it as a single string value and are automatically added by the rules generator.
Example 9: Make Use of Correlation Lists to Simplify a Rule
If a rule has a match detail item value with the equals (==) operator that is used to match a large number of field values, the rule can be simplified and made easier to maintain and update by using a correlation list instead.
Note: The use of correlation lists is not supported for filter rules. This option is not visible in the user interface (UI) for filter rules creation.
(user == ‘name1’ OR user == ‘name2’ OR user == ‘name3’ OR user == ‘name4’ OR user == ‘name5’)
This can be simplified by first creating a correlation list populated with the values of ‘name1’, ‘name2’, ‘name3’, name4’, and ‘name5’. If this correlation list of values were named “Valid_Users”, you could substitute the example rule with a simpler one such the following:
(user -> [[Valid_Users]])
In the revised rule above, the “->” operator is for items in the list of "Valid_Users."
See Correlation Lists for more information.