Correlation rules

Correlation rules are used to recognize specific sequences of processed events and to take certain actions after recognition, such as creating correlation events/alerts or interacting with an active list.

Correlation rules can be used in the following KUMA services and features:

• Correlator.
• Notification rule.
• Links of segmentation rules.
• Retroscan.

The available correlation rule settings depend on the selected type. Types of correlation rules:

• standard—used to find correlations between several events. Resources of this kind can create correlation events.

  This rule kind is used to determine complex correlation patterns. For simpler patterns you should use other correlation rule kinds that require less resources to operate.

• simple—used to create correlation events if a certain event is found.
• operational—used for operations with Active lists and context tables. This rule kind cannot create correlation events.

For these resources, you can enable the display of control characters in all input fields except the Description field.

If a correlation rule is used in the correlator and an alert was created based on it, any change to the correlation rule will not result in a change to the existing alert even if the correlator service is restarted. For example, if the name of a correlation rule is changed, the name of the alert will remain the same. If you close the existing alert, a new alert will be created and it will take into account the changes made to the correlation rule.

Correlation rules of the 'standard' type

Expand all | Collapse all

Correlation rules of the standard type are used for identifying complex patterns in processed events.

The search for patterns is conducted by using buckets

Settings for a correlation rule of the standard type are described in the following tables.

General tab

This tab lets you specify the general settings of the correlation rule.

Unique field mapping group of settings

If you need to pass values of fields listed under Unique fields to the correlation event, here you can configure the mapping of unique fields to correlation event fields. This group of settings is displayed on the General tab if the Use unique field mapping toggle switch is enabled. Values of unique fields are an array, therefore the field in the correlation event must have the appropriate type: SA, NA, FA.

You can add a mapping by clicking the Add button and selecting a field from the drop-down list in the Raw event field column. You can select fields specified in the Unique fields parameter. In the drop-down list in the Target event field column, select the correlation event field to which you want to write the array of values of the source field. You can select fields whose type matches the type of the array (SA, NA, or FA, depending on the type of the source field).

You can delete one or more mappings by selecting the check boxes next to the relevant mappings and clicking Delete.

Selectors tab

This tab is used to define the conditions that the processed events must fulfill to trigger the correlation rule. To add a selector, click the + Add selector button. You can add multiple selectors, reorder selectors, or remove selectors. To reorder selectors, use the reorder icons. To remove a selector, click the delete icon next to it.

Each selector has a Settings tab and a Local variables tab.

The settings available on the Settings tab are described in the table below.

On the Local variables tab, you can add variables that will be valid inside the correlation rule. To add a variable, click the + Add button, then specify the variable and its value. You can add multiple variables or delete variables. To delete a variable, select the check box next to it and click the Delete button.

In the selector of the correlation rule, you can use regular expressions conforming to the RE2 standard. Using regular expressions in correlation rules is computationally intensive compared to other operations. When designing correlation rules, we recommend limiting the use of regular expressions to the necessary minimum and using other available operations.

To use a regular expression, you must use the match operator. The regular expression must be placed in a constant. The use of capture groups in regular expressions is optional. For the correlation rule to trigger, the field text matched against the regexp must exactly match the regular expression.

For a primer on the syntax and examples of correlation rules that use regular expressions in their selectors, see the following rules that are provided with KUMA:

• R105_04_Suspicious PowerShell commands. Suspected obfuscation.
• R333_Suspicious creation of files in the autorun folder.

Actions tab

You can use this tab to configure the triggers of the correlation rule. You can configure triggers on the following tabs:

• On first threshold triggers when the Bucket registers the first triggering of the selector during the lifetime of the Bucket.
• On subsequent thresholds triggers when the Bucket registers the second and all subsequent triggering of the selector during the lifetime of the Bucket.
• On every threshold triggers every time the Bucket registers the triggering of the selector.
• On timeout triggers when the lifetime of the Bucket ends, and is used together with a selector that has the Recovery check box selected in its settings. Thus, this trigger activates if the situation detected by the correlation rule is not resolved within the specified lifetime.

Available trigger settings are listed in the table below.

Correlators tab

This tab is displayed only when you edit the settings of the created correlation rule; on this tab, you can link correlators to the correlation rule.

To add correlators, click the + Add button, specify one or more correlators in the displayed window, and click OK. The correlation rule is linked to the specified correlators and added to the end of the execution queue in the correlator settings. If you want to change the position of a correlation rule in the execution queue, go to the Resources → Correlator section, click the correlator, and in the displayed window, go to the Correlation section, select the check box next to the correlation rule, and change the position of the correlation rule by clicking the Move up and Move down buttons.

You can add multiple correlators or delete correlators. To delete a correlator, select the check box next to it and click Delete.

Correlation rules of the 'simple' type

Expand all | Collapse all

Correlation rules of the simple type are used to define simple sequences of events. Settings for a correlation rule of the simple type are described in the following tables.

General tab

This tab lets you specify the general settings of the correlation rule.

Selectors tab

This tab is used to define the conditions that the processed events must fulfill to trigger the correlation rule. A selector has a Settings tab and a Local variables tab.

The settings available on the Settings tab are described in the table below.

On the Local variables tab, you can add variables that will be valid inside the correlation rule. To add a variable, click the + Add button, then specify the variable and its value. You can add multiple variables or delete variables. To delete a variable, select the check box next to it and click the Delete button.

Actions tab

You can use this tab to configure the trigger of the correlation rule. A correlation rule of the simple type can have only one trigger, which is activated each time the bucket registers the selector triggering. Available trigger settings are listed in the table below.

Correlators tab

This tab is displayed only when you edit the settings of the created correlation rule; on this tab, you can link correlators to the correlation rule.

To add correlators, click the + Add button, specify one or more correlators in the displayed window, and click OK. The correlation rule is linked to the specified correlators and added to the end of the execution queue in the correlator settings. If you want to change the position of a correlation rule in the execution queue, go to the Resources → Correlator section, click the correlator, and in the displayed window, go to the Correlation section, select the check box next to the correlation rule, and change the position of the correlation rule by clicking the Move up and Move down buttons.

You can add multiple correlators or delete correlators. To delete a correlator, select the check box next to it and click Delete.

Correlation rules of the 'operational' type

Expand all | Collapse all

Correlation rules of the operational type are used for working with active lists. Settings for a correlation rule of the operational type are described in the following tables.

General tab

This tab lets you specify the general settings of the correlation rule.

Selectors tab

This tab is used to define the conditions that the processed events must fulfill to trigger the correlation rule. A selector has a Settings tab and a Local variables tab.

The settings available on the Settings tab are described in the table below.

On the Local variables tab, you can add variables that will be valid inside the correlation rule. To add a variable, click the + Add button, then specify the variable and its value. You can add multiple variables or delete variables. To delete a variable, select the check box next to it and click the Delete button.

Actions tab

You can use this tab to configure the trigger of the correlation rule. A correlation rule of the operational type can have only one trigger, which is activated each time the bucket registers the selector triggering. Available trigger settings are listed in the table below.

Correlators tab

This tab is displayed only when you edit the settings of the created correlation rule; on this tab, you can link correlators to the correlation rule.

To add correlators, click the + Add button, specify one or more correlators in the displayed window, and click OK. The correlation rule is linked to the specified correlators and added to the end of the execution queue in the correlator settings. If you want to change the position of a correlation rule in the execution queue, go to the Resources → Correlator section, click the correlator, and in the displayed window, go to the Correlation section, select the check box next to the correlation rule, and change the position of the correlation rule by clicking the Move up and Move down buttons.

You can add multiple correlators or delete correlators. To delete a correlator, select the check box next to it and click Delete.

Variables in correlators

If tracking values in event fields, active lists, or dictionaries is not enough to cover some specific security scenarios, you can use global and local variables. You can use them to take various actions on the values received by the correlators by implementing complex logic for threat detection. Variables can be declared in the correlator (global variables) or in the correlation rule (local variables) by assigning a function to them, then querying them from correlation rules as if they were ordinary event fields and receiving the triggered function result in response.

Usage scope of variables:

• When searching for identical or unique field values in correlation rules.
• In the correlation rule selectors, in the filters of the conditions under which the correlation rule must be triggered.
• When enriching correlation events. Select Event as the source type.
• When populating active lists with values.

Variables can be queried the same way as event fields by preceding their names with the $ character.

You can use extended event schema fields in correlation rules, local variables, and global variables.

Local variables in identical and unique fields

You can use local variables in the Identical fields and Unique fields sections of 'standard' type correlation rules. To use a local variable, its name must be preceded with the "$" character.

For an example of using local variables in the Identical fields and Unique fields sections, refer to the rule provided with KUMA: R403_Access to malicious resources from a host with disabled protection or an out-of-date anti-virus database.

Local variables in selector

To use a local variable in a selector:

1. Add a local variable to the rule.
2. In the Correlation rules window, go to the General tab and add the created local variable to the Identical fields section. Prefix the local variable name with a "$" character.
3. In Correlation rules window, go to the Selectors tab, select an existing filter or create a new filter and click Add condition.
4. Select the event field as the operand.
5. Select the local variable as the event field value and prefix the variable name with a "$" character.
6. Specify the remaining filter settings.
7. Click Save.

For an example of using local variables, refer to the rule provided with KUMA: R403_Access to malicious resources from a host with disabled protection or an out-of-date anti-virus database.

Local Variables in event enrichment

You can use 'standard' and 'simple' correlation rules to enrich events with local variables.

Enrichment with text and numbers

You can enrich events with text (strings). To do so, you can use functions that modify strings: to_lower, to_upper, str_join, append, prepend, substring, tr, replace, str_join.

You can enrich events with numbers. To do so, you can use the following functions: addition ("+"), subtraction ("-"), multiplication ("*"), division ("/"), round, ceil, floor, abs, pow.

You can also use regular expressions to manage data in local variables.

Using regular expressions in correlation rules is computationally intensive compared to other operations. Therefore, when designing correlation rules, we recommend limiting the use of regular expressions to the necessary minimum and using other available operations.

Timestamp enrichment

You can enrich events with timestamps (date and time). To do so, you can use functions that let you get or modify timestamps: now, extract_from_timestamp, parse_timestamp, format_timestamp, truncate_timestamp, time_diff.

Operations with active lists and tables

You can enrich events with local variables and data from active lists and tables.

To enrich events with data from an active list, use the active_list, active_list_dyn functions.

To enrich events with data from a table, use the table_dict, dict functions.

You can create conditional statements by using the 'conditional' function in local variables. In this way, the variable can return one of the values depending on what data was received for processing.

Enriching events with a local variable

To use a local variable to enrich events:

1. Add a local variable to the rule.
2. In the Correlation rules window, go to the General tab and add the created local variable to the Identical fields section. Prefix the local variable name with a "$" character.
3. In the Correlation rules window, go to the Actions tab, and under Enrichment, in the Source kind drop-down list, select Event.
4. From the Target field drop-down list, select the KUMA event field to which you want to pass the value of the local variable.
5. From the Source field drop-down list, select a local variable. Prefix the local variable name with a "$" character.
6. Specify the remaining rule settings.
7. Click Save.

Local variables in active list enrichment

You can use local variables to enrich active lists.

To enrich the active list with a local variable:

1. Add a local variable to the rule.
2. In the Correlation rules window, go to the General tab and add the created local variable to the Identical fields section. Prefix the local variable name with a "$" character.
3. In the Correlation rules window, go to the Actions tab and under Active lists update, add the local variable to the Key fields field. Prefix the local variable name with a "$" character.
4. Under Mapping, specify the correspondence between the event fields and the active list fields.
5. Click the Save button.

Properties of variables

Local and global variables

The properties of global variables differ from the properties of local variables.

Global variables:

• Global variables are declared at the correlator level and are applied only within the scope of this correlator.
• The global variables of the correlator can be queried from all correlation rules that are specified in it.
• In standard correlation rules, the same global variable can take different values in each selector.
• It is not possible to transfer global variables between different correlators.

Local variables:

• Local variables are declared at the correlation rule level and are applied only within the limits of this rule.
• In standard correlation rules, the scope of a local variable consists of only the selector in which the variable was declared.
• Local variables can be declared in any type of correlation rule.
• Local variables cannot be transferred between rules or selectors.
• A local variable cannot be used as a global variable.

Variables used in various types of correlation rules

• In operational correlation rules, on the Actions tab, you can specify all variables available or declared in this rule.
• In standard correlation rules, on the Actions tab, you can provide only those variables specified in these rules on the General tab, in the Identical fields field.
• In simple correlation rules, on the Actions tab, you can provide only those variables specified in these rules on the General tab, in the Inherited Fields field.

Requirements for variables

When adding a variable function, you must first specify the name of the function, and then list its parameters in parentheses. Basic mathematical operations (addition, subtraction, multiplication, division) are an exception to this requirement. When these operations are used, parentheses are used to designate the severity of the operations.

Requirements for function names:

• Must be unique within the correlator.
• Must contain 1 to 128 Unicode characters.
• Must not begin with the character $.
• Must be written in camelCase or CamelCase.

Special considerations when specifying functions of variables:

• The sequence of parameters is important.
• Parameters are separated by a comma: ,.
• String parameters are passed in single quotes: '.
• Event field names and variables are specified without quotation marks.
• When querying a variable as a parameter, add the $ character before its name.
• You do not need to add a space between parameters.
• In all functions in which a variable can be used as parameters, nested functions can be created.

Functions of variables

Operations with active lists and dictionaries

"active_list" and "active_list_dyn" functions

These functions allow you to receive information from an active list and dynamically generate a field name for an active list and key.

You must specify the parameters in the following sequence:

1. Name of the active list.
2. Expression that returns the field name of the active list.
3. One or more expressions whose results are used to generate the key.

   Usage example	Result
   active_list('Test', to_lower('DeviceHostName'), to_lower(DeviceCustomString2), to_lower(DeviceCustomString1))	Gets the field value of the active list.

Use these functions to query the active list of the shared tenant from a variable. To do so, add the @Shared suffix after the name of the active list (case sensitive). For example, active_list('exampleActiveList@Shared', 'score', SourceAddress, SourceUserName).

"table_dict" function

Gets information about the value in the specified column of a dictionary of the table type.

You must specify the parameters in the following sequence:

1. Dictionary name
2. Dictionary column name
3. One or more expressions whose results are used to generate the dictionary row key.

   Usage example	Result
   table_dict('exampleTableDict', 'office', SourceUserName)	Gets data from the exampleTableDict dictionary from the row with the SourceUserName key in the office column.
   table_dict('exampleTableDict', 'office', SourceAddress, to_lower(SourceUserName))	Gets data from the exampleTableDict dictionary from a composite key string from the SourceAddress field value and the lowercase value of the SourceUserName field from the office column.

Use this function to access the dictionary of the shared tenant from a variable. To do so, add the @Shared suffix after the name of the active list (case sensitive). For example, table_dict('exampleTableDict@Shared', 'office', SourceUserName).

"dict" function

Gets information about the value in the specified column of a dictionary of the dictionary type.

You must specify the parameters in the following sequence:

1. Dictionary name
2. One or more expressions whose results are used to generate the dictionary row key.

   Usage example	Result
   dict('exampleDictionary', SourceAddress)	Gets data from exampleDictionary from the row with the SourceAddress key.
   dict('exampleDictionary', SourceAddress, to_lower(SourceUserName))	Gets data from the exampleDictionary from a composite key string from the SourceAddress field value and the lowercase value of the SourceUserName field.

Use this function to access the dictionary of the shared tenant from a variable. To do so, add the @Shared suffix after the name of the active list (case sensitive). For example, dict('exampleDictionary@Shared', SourceAddress).

Operations with context tables

"context_table" function

Returns the value of the specified field in the base type (for example, integer, array of integers).

You must specify the parameters in the following sequence:

1. Name of the context table. The name must be specified.
2. Expression that returns the field name of context table.
3. Expression that returns the name of key field 1 of the context table.
4. Expression that returns the value of key field 1 of the context table.

The function must contain at least 4 parameters.

"len" function

Returns the length of a string or array.

The function returns the length of the array if the passed array is of one of the following types:

• array of integers
• array of floats
• array of strings
• array of booleans

If an array of a different type is passed, the data of the array is cast to the string type, and the function returns the length of the resulting string.

"distinct_items" function

Returns a list of unique elements in an array.

The function returns the list of unique elements of the array if the passed array is of one of the following types:

• array of integers
• array of floats
• array of strings
• array of booleans

If an array of a different type is passed, the data of the array is cast to the string type, and the function returns a string consisting of the unique characters from the original string.

"sort_items" function

Returns a sorted list of array elements.

You must specify the parameters in the following sequence:

1. Expression that returns the object of the sorting.
2. Sorting order Possible values: asc, desc. If the parameter is not specified, the default value is asc.

The function returns the list of sorted elements of the array if the passed array is of one of the following types:

• array of integers
• array of floats
• array of strings

For a boolean array, the function returns the list of array elements in the original order.

If an array of a different type is passed, the data of the array is cast to the string type, and the function returns a string of sorted characters.

"item" function

Returns the array element with the specified index or the character of a string with the specified index if an array of integers, floats, strings, or boolean values is passed.

You must specify the parameters in the following sequence:

1. Expression that returns the object of the indexing.
2. Expression that returns the index of the element or character.

The function must contain at least 2 parameters.

The function returns the array element with the specified index or the string character with the specified index if the index falls within the range of the array and the passed array is of one of the following types:

• array of integers
• array of floats
• array of strings
• array of booleans

If an array of a different type is passed and the index falls within the range of the array, the data is cast to the string type, and the function returns the string character with the specified index. If an array of a different type is passed and the index is outside the range of the array, the function returns an empty string.

Operations with strings

"to_lower" function

Converts characters in a string to lowercase. Supported for standard fields and extended event schema fields of the "string" type.

A string can be passed as a string, field name or variable.

"to_upper" function

Converts characters in a string to uppercase. Supported for standard fields and extended event schema fields of the "string" type. A string can be passed as a string, field name or variable.

"append" function

Adds characters to the end of a string. Supported for standard fields and extended event schema fields of the "string" type.

You must specify the parameters in the following sequence:

1. Original string.
2. Added string.

Strings can be passed as a string, field name or variable.

"prepend" function

Adds characters to the beginning of a string. Supported for standard fields and extended event schema fields of the "string" type.

You must specify the parameters in the following sequence:

1. Original string.
2. Added string.

Strings can be passed as a string, field name or variable.

"substring" function

Returns a substring from a string. Supported for standard fields and extended event schema fields of the "string" type.

You must specify the parameters in the following sequence:

1. Original string.
2. Substring start position (natural number or 0).
3. (Optional) substring end position.

Strings can be passed as a string, field name or variable. If the position number is greater than the original data string length, an empty string is returned.

"index_of" function

The "index_of" function returns the position of the first occurrence of a character or substring in a string; the first character in the string has index 0. If the function does not find the substring, the function returns -922337203685477580.

The function accepts the following parameters:

• As source data, an event field, another variable, or constant.
• Any expression out of those that are available in local variables.

To use this function, you must specify the parameters in the following order:

1. Character or substring whose position you want to find.
2. String to be searched.

"last_index_of" function

The "last_index_of" function returns the position of the last occurrence of a character or substring in a string; the first character in the string has index 0. If the function does not find the substring, the function returns -922337203685477580.

The function accepts the following parameters:

• As source data, an event field, another variable, or constant.
• Any expression out of those that are available in local variables.

To use this function, you must specify the parameters in the following order:

1. Character or substring whose position you want to find.
2. String to be searched.

"tr" function

Removes the specified characters from the beginning and end of a string. Supported for standard fields and extended event schema fields of the "string" type.

You must specify the parameters in the following sequence:

1. Original string.
2. (Optional) string that should be removed from the beginning and end of the original string.

Strings can be passed as a string, field name or variable. If you do not specify a string to be deleted, spaces will be removed from the beginning and end of the original string.

"replace" function

Replaces all occurrences of character sequence A in a string with character sequence B. Supported for standard fields and extended event schema fields of the "string" type.

You must specify the parameters in the following sequence:

1. Original string.
2. Search string: sequence of characters to be replaced.
3. Replacement string: sequence of characters to replace the search string.

Strings can be passed as an expression.

"regexp_replace" function

Replaces a sequence of characters that match a regular expression with a sequence of characters and regular expression capturing groups. Supported for standard fields and extended event schema fields of the "string" type.

You must specify the parameters in the following sequence:

1. Original string.
2. Search string: regular expression.
3. Replacement string: sequence of characters to replace the search string, and IDs of the regular expression capturing groups. A string can be passed as an expression.

Strings can be passed as a string, field name or variable. Unnamed capturing groups can be used.

In regular expressions used in variable functions, each backslash character must be additionally escaped. For example, ^example\\\\ must be used instead of the regular expression ^example\\.

"regexp_capture" function

Gets the result matching the regular expression condition from the original string. Supported for standard fields and extended event schema fields of the "string" type.

You must specify the parameters in the following sequence:

1. Original string.
2. Search string: regular expression.

Strings can be passed as a string, field name or variable. Unnamed capturing groups can be used.

In regular expressions used in variable functions, each backslash character must be additionally escaped. For example, ^example\\\\ must be used instead of the regular expression ^example\\.

"template" function

Returns the string specified in the function, with variables replaced with their values. Variables for substitution can be passed in the following ways:

• Inside the string.
• After the string. In this case, inside the string, you must specify variables in the {{index.<n>}} notation, where <n> is the index of the variable passed after the string. The index is 0-based.

  Usage examples

  template('Very long text with values of rule={{.DeviceCustomString1}} and {{.Name}} event fields, as well as values of {{index.0}} and {{index.1}} local variables and then {{index.2}}', $var1, $var2, $var10)

Operations with timestamps

now function

Gets a timestamp in epoch format. Runs with no arguments.

"extract_from_timestamp" function

Gets atomic time representations (year, month, day, hour, minute, second, day of the week) from fields and variables with time in the epoch format.

The parameters must be specified in the following sequence:

1. Event field of the timestamp type, or variable.
2. Notation of the atomic time representation. This parameter is case sensitive.

   Possible variants of atomic time notation:

   • y refers to the year in number format.
   • M refers to the month in number notation.
   • d refers to the number of the month.
   • wd refers to the day of the week: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday.
   • h refers to the hour in 24-hour format.
   • m refers to the minutes.
   • s refers to the seconds.
3. (optional) Time zone notation. If this parameter is not specified, the time is calculated in UTC format.

   Usage examples

   extract_from_timestamp(Timestamp, 'wd')

   extract_from_timestamp(Timestamp, 'h')

   extract_from_timestamp($otherVariable, 'h')

   extract_from_timestamp(Timestamp, 'h', 'Europe/Moscow')

"parse_timestamp" function

Converts the time from RFC3339 format (for example, "2022-05-24 00:00:00", "2022-05-24 00:00:00+0300) to epoch format.

"format_timestamp" function

Converts the time from epoch format to RFC3339 format.

The parameters must be specified in the following sequence:

1. Event field of the timestamp type, or variable.
2. Time format notation: RFC3339.
3. (optional) Time zone notation. If this parameter is not specified, the time is calculated in UTC format.

   Usage examples

   format_timestamp(Timestamp, 'RFC3339')

   format_timestamp($otherVariable, 'RFC3339')

   format_timestamp(Timestamp, 'RFC3339', 'Europe/Moscow')

"truncate_timestamp" function

Rounds the time in epoch format. After rounding, the time is returned in epoch format. Time is rounded down.

The parameters must be specified in the following sequence:

1. Event field of the timestamp type, or variable.
2. Rounding parameter:
   • 1s rounds to the nearest second.
   • 1m rounds to the nearest minute.
   • 1h rounds to the nearest hour.
   • 24h rounds to the nearest day.
3. (optional) Time zone notation. If this parameter is not specified, the time is calculated in UTC format.

   Usage examples	Examples of rounded values	Usage result
   truncate_timestamp(Timestamp, '1m')	1654631774175 (7 June 2022, 19:56:14.175)	1654631760000 (7 June 2022, 19:56:00)
   truncate_timestamp($otherVariable, '1h')	1654631774175 (7 June 2022, 19:56:14.175)	1654628400000 (7 June 2022, 19:00:00)
   truncate_timestamp(Timestamp, '24h', 'Europe/Moscow')	1654631774175 (7 June 2022, 19:56:14.175)	1654560000000 (7 June 2022, 0:00:00)

"time_diff" function

Gets the time interval between two timestamps in epoch format.

The parameters must be specified in the following sequence:

1. Interval end time. Event field of the timestamp type, or variable.
2. Interval start time. Event field of the timestamp type, or variable.
3. Time interval notation:
   • ms refers to milliseconds.
   • s refers to seconds.
   • m refers to minutes.
   • h refers to hours.
   • d refers to days.

   Usage examples

   time_diff(EndTime, StartTime, 's')

   time_diff($otherVariable, Timestamp, 'h')

   time_diff(Timestamp, DeviceReceiptTime, 'd')

Mathematical operations

These are comprised of basic mathematical operations and functions.

Basic mathematical operations

Supported for integer and float fields of the extended event schema.

Operations:

• Addition
• Subtraction
• Multiplication
• Division
• Modulo division

Parentheses determine the sequence of actions

Available arguments:

• Numeric event fields
• Numeric variables
• Real numbers

  When modulo dividing, only natural numbers can be used as arguments.

Usage constraints:

• Division by zero returns zero.
• Mathematical operations on a number and a strings return the number unchanged. For example, 1 + abc returns 1.
• Integers resulting from operations are returned without a dot.

  Usage examples (Type=3; otherVariable=2; Message=text)	Usage result
  Type + 1	4
  $otherVariable - Type	-1
  2 * 2.5	5
  2 / 0	0
  Type * Message	0
  (Type + 2) * 2	10
  Type % $otherVariable	1

"round" function

Rounds numbers. Supported for integer and float fields of the extended event schema.

Available arguments:

• Numeric event fields
• Numeric variables
• Numeric constants

  Usage examples (DeviceCustomFloatingPoint1=7.75; DeviceCustomFloatingPoint2=7.5 otherVariable=7.2)	Usage result
  round(DeviceCustomFloatingPoint1)	8
  round(DeviceCustomFloatingPoint2)	8
  round($otherVariable)	7

"ceil" function

Rounds up numbers. Supported for integer and float fields of the extended event schema.

Available arguments:

• Numeric event fields
• Numeric variables
• Numeric constants

  Usage examples (DeviceCustomFloatingPoint1=7.15; otherVariable=8.2)	Usage result
  ceil(DeviceCustomFloatingPoint1)	8
  ceil($otherVariable)	9

"floor" function

Rounds down numbers. Supported for integer and float fields of the extended event schema.

Available arguments:

• Numeric event fields
• Numeric variables
• Numeric constants

  Usage examples (DeviceCustomFloatingPoint1=7.15; otherVariable=8.2)	Usage result
  floor(DeviceCustomFloatingPoint1)	7
  floor($otherVariable)	8

"abs" function

Gets the modulus of a number. Supported for integer and float fields of the extended event schema.

Available arguments:

• Numeric event fields
• Numeric variables
• Numeric constants

  Usage examples (DeviceCustomNumber1=-7; otherVariable=-2)	Usage result
  abs(DeviceCustomFloatingPoint1)	7
  abs($otherVariable)	2

"pow" function

Exponentiates a number. Supported for integer and float fields of the extended event schema.

The parameters must be specified in the following sequence:

1. Base — real numbers.
2. Power — natural numbers.

Available arguments:

• Numeric event fields
• Numeric variables
• Numeric constants

  Usage examples

  pow(DeviceCustomNumber1, DeviceCustomNumber2)

  pow($otherVariable, DeviceCustomNumber1)

"str_join" function

Join multiple strings into one using a separator. Supported for integer and float fields of the extended event schema.

The parameters must be specified in the following sequence:

1. Separator. String.
2. String1, string2, stringN. At least 2 expressions.

   Usage examples	Usage result
   str_join('|', to_lower(Name), to_upper(Name), Name)	String.

"conditional" function

Get one value if a condition is met and another value if the condition is not met. Supported for integer and float fields of the extended event schema.

The parameters must be specified in the following sequence:

1. Condition. String. The syntax is similar to the conditions of the Where statement in SQL. You can use the functions of the KUMA variables and references to other variables in a condition.
2. The value if the condition is met. Expression.
3. The value if the condition is not met. Expression.

Supported operators:

• AND
• OR
• NOT
• =
• !=
• <
• <=
• >
• >=
• LIKE (RE2 regular expression is used, rather than an SQL expression)
• ILIKE (RE2 regular expression is used, rather than an SQL expression)
• BETWEEN
• IN
• IS NULL (check for an empty value, such as 0 or an empty string)

  Usage examples (the value depends on arguments 2 and 3)

  conditional('SourceUserName = \\'root\\' AND DestinationUserName = SourceUserName', 'match', 'no match')

  conditional(`DestinationUserName ILIKE 'svc_.*'`, 'match', 'no match')

  conditional(`DestinationUserName NOT LIKE 'svc_.*'`, 'match', 'no match')

Operations for extended event schema fields

For extended event schema fields of the "string" type, the following kinds of operations are supported:

• "len" function
• "to_lower" function
• "to_upper" function
• "append" function
• "prepend" function
• "substring" function
• "tr" function
• "replace" function
• "regexp_replace" function
• "regexp_capture" function

For extended event schema fields of the integer or float type, the following kinds of operations are supported:

• Basic mathematical operations:
• "round" function
• "ceil" function
• "floor" function
• "abs" function
• "pow" function
• "str_join" function
• "conditional" function

For extended event schema fields of the "array of integers", "array of floats", and "array of strings" types, KUMA supports the following functions:

• Get the i-th element of the array. Example: item(<type>.someStringArray).
• Get an array of values. Example: <type>.someStringArray. Returns ["string1", "string2", "string3"].
• Get the count of elements in an array. Example: len(<type>.someStringArray). Returns ["string1", "string2"].
• Gett unique elements from an array. Example: distinct_items(<type>.someStringArray).
• Generate a TSV string of array elements. Example: to_string(<type>.someStringArray).
• Sort the elements of the array. Example: sort_items(<type>.someStringArray).

  In the examples, instead of <type>, you must specify the array type: NA for an array of integers, FA for an array of floats, SA for an array of strings.

For fields of the "array of integers" and "array of floats" types, the following functions are supported:

• math_min — returns the minimum element of an array. Example: math_min(NA.NumberArray), math_min(FA.FloatArray)

• math_max — returns the maximum element of an array Example: math_max(NA.NumberArray), math_max(FA.FloatArray)

• math_avg — returns the average value of an array. Example: math_avg(NA.NumberArray), math_avg(FA.FloatArray)

Declaring variables

Expand all | Collapse all

To declare variables, they must be added to a correlator or correlation rule.

To add a global variable to an existing correlator:

1. In the KUMA Console, under Resources → Correlators, select the resource set of the relevant correlator.

   The Correlator Installation Wizard opens.

2. Select the Global variables step of the Installation Wizard.
3. click the Add variable button and specify the following parameters:
   • In the Variable window, enter the name of the variable.

     Variable naming requirements

     • Must be unique within the correlator.
     • Must contain 1 to 128 Unicode characters.
     • Must not begin with the character $.
     • Must be written in camelCase or CamelCase.
   • In the Value window, enter the variable function.

     When entering functions, you can use autocomplete as a list of hints with possible function names, their brief description and usage examples. You can select a function from the list and insert it together with its list of arguments into the input field.

     To display the list of all hints in the field, press Ctrl+Space. Press Enter to select a function from the list. Press Tab to go to the next argument in the list of arguments of the selected function.

     Description of variable functions.

   Multiple variables can be added. Added variables can be edited or deleted by using the icon.

4. Select the Setup validation step of the Installation Wizard and click Save.

A global variable is added to the correlator. It can be queried like an event field by inserting the $ character in front of the variable name. The variable will be used for correlation after restarting the correlator service.

To add a local variable to an existing correlation rule:

1. In the KUMA Console, under Resources → Correlation rules, select the relevant correlation rule.

   The correlation rule settings window opens. The parameters of a correlation rule can also be opened from the correlator to which it was added by proceeding to the Correlation step of the Installation Wizard.

2. Click the Selectors tab.
3. In the selector, open the Local variables tab, click the Add variable button and specify the following parameters:
   • In the Variable window, enter the name of the variable.

     Variable naming requirements

     • Must be unique within the correlator.
     • Must contain 1 to 128 Unicode characters.
     • Must not begin with the character $.
     • Must be written in camelCase or CamelCase.
   • In the Value window, enter the variable function.

     When entering functions, you can use autocomplete as a list of hints with possible function names, their brief description and usage examples. You can select a function from the list and insert it together with its list of arguments into the input field.

     To display the list of all hints in the field, press Ctrl+Space. Press Enter to select a function from the list. Press Tab to go to the next argument in the list of arguments of the selected function.

     Description of variable functions.

   Multiple variables can be added. Added variables can be edited or deleted by using the icon.

   For standard correlation rules, repeat this step for each selector in which you want to declare variables.

4. Click Save.

The local variable is added to the correlation rule. It can be queried like an event field by inserting the $ character in front of the variable name. The variable will be used for correlation after restarting the correlator service.

Added variables can be edited or deleted. If the correlation rule queries an undeclared variable (for example, if its name has been changed), an empty string is returned.

If you change the name of a variable, you will need to manually change the name of this variable in all correlation rules where you have used it.

Adding a temporary exclusion list for a correlation rule

Users that do not have the rights to edit correlation rules in the KUMA Console, can create a temporary list of exclusions (for example, create exclusions for false positives when managing alerts). A user with the rights to edit correlation rules can then add the exclusions to the rule and remove them from the temporary list.

To add exclusions to a correlation rule when managing alerts:

1. Go to the Alerts section and select an alert.
2. Click the Find in events button.

   Events of the alert are displayed on the events page.

3. Open the correlation event.

   This opens the event card in which each field has a (arrow) button that lets you add an exclusion.

4. Click the button and select Add to exclusions.

   A sidebar is displayed, containing the following fields: Correlation rule, Exclusion, Alert, Comment.

5. Click the Create button.

The exclusion rule is added.

The exclusion is added to the temporary list. This list is available to anyone with rights to read correlation rules: in the Resources → Correlation rules section, in the toolbar of the rule list, click the List of exclusions button. If you want to view the exclusions of a specific rule, open the card of the rule and select the Exclusions tab.

The exclusion list contains entries with the following parameters:

• Exclusion

  Exclusion condition.

• Correlation rule

  Name of the correlation rule.

• Alert

  Name of the alert from which the exclusion was added.

• Tenant

  The tenant to which the rule and the exclusion apply.

• Condition

  Generated automatically based on the selected field of the correlation event.

• Сreation date

  Date and time when the exclusion was added.

• Expires

Date and time when the exclusion will be automatically removed from the list.

• Created

  Name of the user that added the exclusion.

• Comment

After the exclusion is added, by default, the correlation rule takes the exclusion into account for 7 days. In the Options → General section, you can configure the duration of exclusions by editing the corr_rule_exclusion_ttl_hours parameter in the Core properties section. You can configure the lifetime of exclusions in hours and days. The minimum value is 1 hour, the maximum is 365 days. This setting is available only for users with the General administrator role.

For fields from base events to be propagated to correlation events, these fields must be specified in the card of the correlation rule on the General tab, in the Propagated fields field. If the fields of base events are not mapped to the correlation event, these fields cannot be added to exclusions.

To remove exclusions from a correlation rule:

1. Go to the Resources → Correlation rules section.
2. In the toolbar of the rule list, click List of exclusions button.

   This opens the window with the list of exclusions.

3. Select the exclusions that you want to delete and click the Delete button.

Exceptions are deleted from the correlation rule.

KUMA generates an audit event whenever an exception is created or deleted. You can view the changes of event settings in the Event details window.

Predefined correlation rules

The KUMA distribution kit includes correlation rules listed in the table below.

Predefined correlation rules

MITRE ATT&CK matrix coverage

If you want to assess the coverage of the MITRE ATT&CK matrix by your correlation rules:

1. Download the list of MITRE techniques from the official MITRE ATT&CK repository and import it into KUMA.
2. Map MITRE techniques to correlation rules.
3. Export correlation rules to MITRE ATT&CK Navigator.

As a result, you can visually assess the coverage of the MITRE ATT&CK matrix.

Importing the list of MITRE techniques

Only a user with the General Administrator role can import the list of MITRE techniques.

To import the list of MITRE ATT&CK techniques:

1. Download the list of MITRE ATT&CK techniques from the GitHub portal.

   KUMA 3.2 supports only the MITRE ATT&CK technique list version 14.1.

2. In the KUMA Console, go to the Settings → Other.
3. In the MITRE technique list settings, click Import from file.

   This opens the file selection window.

4. Select the downloaded MITRE ATT&CK technique list and click Open.

   This closes the file selection window.

The list of MITRE ATT&CK techniques is imported into KUMA. You can see the list of imported techniques and the version of the MITRE ATT&CK technique list by clicking View list.

Mapping MITRE techniques to correlation rules

To map MITRE ATT&CK techniques to correlation rules:

1. In the KUMA Console, go to the Resources → Correlation rules section.
2. Click the name of the correlation rule to open the correlation rule editing window.

   This opens the correlation rule editing window.

3. On the General tab, clicking the MITRE techniques field opens a list of available techniques. For the convenience of searching, a filter is provided, in which you can enter the name of a technique or the ID of a technique or tactic. One or more MITRE ATT&CK techniques are available for linking to a correlation rule.
4. Click the Save button.

The MITRE ATT&CK techniques are mapped to the correlation rule. In the web interface, in the Resources → Correlation rules section, the MITRE techniques column of the edited rule displays the ID of the selected technique, and when you hover over the item, the full name of the technique is displayed, including the ID of the technique and tactic.

Exporting correlation rules to MITRE ATT&CK Navigator

To export correlation rules with mapped MITRE techniques to MITRE ATT&CK Navigator:

1. In the KUMA Console, go to the Resources → Correlation rules section.
2. Click the button in the upper-right corner.
3. In the drop-down list, click Export to MITRE ATT&CK Navigator.
4. This opens a window; in that window, select the correlation rules that you want to export.
5. Click OK.

   A file with exported rules is downloaded to your computer.

6. Upload the file from your computer to MITRE ATT&CK Navigator to assess the coverage of the MITRE ATT&CK matrix.

You can assess the coverage of the MITRE ATT&CK matrix.