Correlation condition

A correlation condition matches multiple items that share the same groupby value. These items can be field match expressions, nested correlations, deviations, or cardinalities. If you use a correlation, you must also use the require parameter. This is the number of events that must match for the condition to trigger.

The following table describes the parameters you can use in a correlation condition.

Name	Type	Required	Default	Description
`groupby`	String	No	Inherited from the parent	A comma-separated list of match expressions. It returns a string key to group items by. If it is specified, it overrides the `groupby` parameter defined in the parent item.
`require`	Number	Yes	Not applicable	The number of events that must match to trigger the rule. The value must be a positive integer.
`within`	Duration	Yes	Not applicable	The time window within which all the items must be found. The value must be a positive integer, followed by s (second), m (minute), or h (hour).
`ordered`	Boolean	No	False	If set to `true` a match will only occur if the items occur in the order listed.
`minOrderDistance`	Number	No	1	How far apart items must be in milliseconds. If set to zero, then items with same timestamp will be considered to be in order. If set to five, then each item must happen at least five milliseconds after the previous one.
`threshold`	Number	No	1	How many times the condition's criteria must be met for the correlation to trigger.
`items`	List	Yes	Not applicable	A field, correlation, deviation, cardinality, or pivot.

In the following example, the rule requires two events to be seen with the same username: one with a type field of login success and one with login failure:

id: 123789
version: 45678901
name: User login anomaly - Login success and login failure within a minute
groupby: username
require: 2
within: 60s
items:
    - type: fields
      match: class== "ms_windows_event" && eventid=="4624" && event_type == "audit_success"
    - type: fields
      match: class== "ms_windows_event" && eventid=="4625" && event_type == "audit_failure"

You can also use the threshold parameter to specify how many times the requirement must be met. In the following example, the rule requires ten login failures to happen within 60 seconds before it triggers:

id: 99872
version: 3456789
name: Multiple login failures within a minute
groupby: username
require: 1
threshold: 10
within: 60s
items:
    - type: fields
      match: class == "ms_windows_event" && eventid == "4625" && event_type == "audit_failure"

Finally, you can use the ordered parameter to nest correlations. This requires the items to match in the order you list them for the correlation to trigger. In the following example, the rule looks for ten failed log in attempts followed by a successful log in attempt.

id: 123456
version: 1678882534
name: Multiple login failures followed by successful login
groupby: username
require: 2
ordered: true
within: 5m
items:
    - type: correlation
      require: 1
      threshold: 10
      items:
        - type: fields
          match: metaclass == "windows" && eventid == "4625" && event_type == "audit_failure"
    - type: fields
      match: metaclass == "windows" && eventid == "4624" && event_type == "audit_success"