--- title: "Correlation condition" slug: "correlation-condition-1" updated: 2026-09-12T15:51:52Z published: 2026-09-12T15:51:52Z canonical: "docs.trellix.com/correlation-condition-1" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.trellix.com/llms.txt > Use this file to discover all available pages before exploring further. # 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: ```plaintext 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: ```plaintext 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. ```plaintext 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" ```