Correlate Events

LAST UPDATED: SEPT 04, 2024

Searches for events using two distinct criteria: 1) Constraint conditions, which are specific rules for identifying events, and 2) Correlation conditions, which rely on the values from Source Event fields to discover related events. Furthermore, it offers the ability to directly associate identified events with the ongoing incident, and to connect any related incidents to the same ongoing incident.

Implementation	System
Command Category	Cyber Utility
Tags	EVENT EVENT SEARCH

READER NOTE

Execute this command in an Incident Playbook to establish event-incident correlations.

Inputs

Parameter Name	Required/Optional	Description	Sample Data
Source Event IDs	Required	The list of event IDs used as the basis for correlation or analysis.	CODE `[ 100, 101 ]`
Time Range	Optional	The time range of consideration for correlating events. The options are: Past hour Past 24 Past week Past month Custom range Select the Custom range option to enable the date-time selectors.	CODE `{ "timeRangeType": 4, "startTime": "2020-06-04 23:02:11", "endTime": "2020-07-04 23:02:11" }`
Top Recent Event Number	Optional	The maximum number of recent events to display.	20
Constraint Condition	Optional	A JSON structure specifying specific constraints or conditions for filtering events. This might include logical operations, command executions, and parameter specifications.	JSON [ { "Index": 1, "LogicOp": "", "LeftParen": 1, "RightParen": 1, "Command": { "CommandId": 204, "CommandName": null, "CommandDisplayName": null, "Operator": null, "CommandParams": [ { "ParamName": "selectedField", "ParamDisplayName": null, "ParamIndex": 0, "ParamType": 0, "ParamTypeName": null, "ParamInputId": 0, "ParamValue": "Target.Events.DvcHostName", "DisplayValue": null, "InputId": 27754, "InputOption": null, "TemplateContent": null }, { "ParamName": "filterValue", "ParamDisplayName": null, "ParamIndex": 0, "ParamType": 0, "ParamTypeName": null, "ParamInputId": 0, "ParamValue": "pc1", "DisplayValue": null, "InputId": 27755, "InputOption": null, "TemplateContent": null } ], "ExecOrder": 0, "ReturnType": 0, "PlaybookId": 0, "IsPython": false, "IsCustom": false, "Script": null, "CommandImplMode": 0 } } ]
Correlation Condition	Optional	A JSON array that defines the conditions for correlating different events. This typically involves comparing fields between source and target events.	CODE `[ { "Index": 1, "LogicOp": "", "LeftParen": 1, "RightParen": 1, "Command": { "CommandId": 204, "CommandParams": [ { "ParamName": "selectedField", "ParamValue": "Target.Events.Process.ProcessGUID" }, { "ParamName": "filterValue", "ParamValue": "Source.Events.ParentProcessGuid" } ] } } ]`
Incident Linkage	Optional	The number of incidents to link to based on relevant criteria. The options are: No Link (1) Linked as Trigger Events (2) Linked as Related Events (3)	1
Link Relevant Incidents	Optional	A flag indicating whether incidents relevant to the defined conditions should be linked.	Yes

READER NOTE

Both the Constraint Condition and Correlation Condition parameters are optional. However, if neither is provided, the search will include all events, potentially yielding a large volume of results.

Output

Return Data

The returned result of this command. If some required parameters are not defined, this returned data could be empty. The returned result can be passed down directly to a subsequent command in playbooks.

SAMPLE DATA

JSON

True

Context Data

The context data from the utility command.

SAMPLE DATA

JSON

{
    "eventCount": 5,
    "events": [
        {
            "ID": 15,
            "eventType": "Email Alerts",
            "eventTime": "2020-06-16 00:54:47",
            "intakeTime": "2020-06-16 00:54:47"
        },
        {
            "ID": 14,
            "eventType": "Email Alerts",
            "eventTime": "2020-06-16 00:54:47",
            "intakeTime": "2020-06-16 00:54:47"
        },
        {
            "ID": 13,
            "eventType": "Email Alerts",
            "eventTime": "2020-06-16 00:54:33",
            "intakeTime": "2020-06-16 00:54:33"
        },
        {
            "ID": 12,
            "eventType": "Email Alerts",
            "eventTime": "2020-06-16 00:54:03",
            "intakeTime": "2020-06-16 00:54:03"
        },
        {
            "ID": 11,
            "eventType": "Suspicious Email",
            "eventTime": "2020-06-16 00:52:03",
            "intakeTime": "2020-06-16 00:52:03",
            "linkedIncidentNumbers": [
                "20211015-3"
            ]
        }
    ]
  }

Remote Command API

The D3 command API allows you to send requests to D3 SOAR to execute this utility command via REST API.

Request

POST

CODE

https:/{base_url}/{api_namespace}/api/Command/CorrelateEvents

Headers

Please refer to the page Webhook Configuration Guide - Authentication Method: API Keys for more details.

Request Body

JSON

{
  "Username": <Username here>,
  "Site": <Site here>,
  "CommandParams": {
    "Source Event IDs": [
      <Source Event ID 1 here>,
      <Source Event ID 2 here>
    ],
    "Time Range": {
      "timeRangeType": <Time Range Type here>,
      "startTime": <Start Time here>,
      "endTime": <End Time here>
    },
    "Top Recent Event Number": <Top Recent Event Number here>,
    "Constraint Condition": [
      {
        "Index": <Index here>,
        "LogicOp": <Logic Operation here>,
        "LeftParen": <Left Parenthesis here>,
        "RightParen": <Right Parenthesis here>,
        "Command": {
          "CommandId": <Command ID here>,
          "CommandName": <Command Name here>,
          "CommandDisplayName": <Command Display Name here>,
          "Operator": <Operator here>,
          "CommandParams": [
            {
              "ParamName": "selectedField",
              "ParamDisplayName": <Param Display Name here>,
              "ParamIndex": <Param Index here>,
              "ParamType": <Param Type here>,
              "ParamTypeName": <Param Type Name here>,
              "ParamInputId": <Param Input ID here>,
              "ParamValue": <Param Value for selectedField here>,
              "DisplayValue": <Display Value here>,
              "InputId": <Input ID for selectedField here>,
              "InputOption": <Input Option here>,
              "TemplateContent": <Template Content here>
            },
            {
              "ParamName": "filterValue",
              "ParamDisplayName": <Param Display Name here>,
              "ParamIndex": <Param Index here>,
              "ParamType": <Param Type here>,
              "ParamTypeName": <Param Type Name here>,
              "ParamInputId": <Param Input ID here>,
              "ParamValue": <Param Value for filterValue here>,
              "DisplayValue": <Display Value here>,
              "InputId": <Input ID for filterValue here>,
              "InputOption": <Input Option here>,
              "TemplateContent": <Template Content here>
            }
          ],
          "ExecOrder": <Execution Order here>,
          "ReturnType": <Return Type here>,
          "PlaybookId": <Playbook ID here>,
          "IsPython": <Is Python here>,
          "IsCustom": <Is Custom here>,
          "Script": <Script here>,
          "CommandImplMode": <Command Implementation Mode here>
        }
      }
    ],
    "Correlation Condition": [
      {
        "Index": <Index here>,
        "LogicOp": <Logic Operation here>,
        "LeftParen": <Left Parenthesis here>,
        "RightParen": <Right Parenthesis here>,
        "Command": {
          "CommandId": <Command ID here>,
          "CommandName": <Command Name here>,
          "CommandDisplayName": <Command Display Name here>,
          "Operator": <Operator here>,
          "CommandParams": [
            {
              "ParamName": "selectedField",
              "ParamDisplayName": <Param Display Name here>,
              "ParamIndex": <Param Index here>,
              "ParamType": <Param Type here>,
              "ParamTypeName": <Param Type Name here>,
              "ParamInputId": <Param Input ID here>,
              "ParamValue": <Param Value for selectedField here>,
              "DisplayValue": <Display Value here>,
              "InputId": <Input ID for selectedField here>,
              "InputOption": <Input Option here>,
              "TemplateContent": <Template Content here>
            },
            {
              "ParamName": "filterValue",
              "ParamDisplayName": <Param Display Name here>,
              "ParamIndex": <Param Index here>,
              "ParamType": <Param Type here>,
              "ParamTypeName": <Param Type Name here>,
              "ParamInputId": <Param Input ID here>,
              "ParamValue": <Param Value for filterValue here>,
              "DisplayValue": <Display Value here>,
              "InputId": <Input ID for filterValue here>,
              "InputOption": <Input Option here>,
              "TemplateContent": <Template Content here>
            }
          ],
          "ExecOrder": <Execution Order here>
        }
      }
    ],
    "Incident Linkage": <Incident Linkage here>,
    "Link Relevant Incidents": <Link Relevant Incidents here>
  }
}

Body Parameters

Parameter Name	Type	Required/Optional	Description
Username	`string`	Required	The username of your D3 SOAR account.
Site	`string`	Required	The D3 SOAR site to run the remote command.
Source Event IDs	`array<string>`	Required	The list of event IDs used as the basis for correlation or analysis.
Time Range	`JSON Object`	Optional	The time range of consideration for correlating events. The options are: Past hour Past 24 Past week Past month Custom range Select the Custom range option to enable the date-time selectors.
Top Recent Event Number	`integer`	Optional	The maximum number of recent events to display.
Constraint Condition	`array<JSON Object>`	Optional	A JSON structure specifying specific constraints or conditions for filtering events. This might include logical operations, command executions, and parameter specifications.
Correlation Condition	`array<JSON Object>`	Optional	A JSON array that defines the conditions for correlating different events. This typically involves comparing fields between source and target events.
Incident Linkage	`integer`	Optional	The number of incidents to link to based on relevant criteria. The options are: No Link (1) Linked as Trigger Events (2) Linked as Related Events (3)
Link Relevant Incidents	`string`	Optional	A flag indicating whether incidents relevant to the defined conditions should be linked.

Sample Request

SAMPLE DATA

JSON

{
  "Username": "Admin",
  "Site": "Security Operations",
  "CommandParams": {
    "Source Event IDs": [
      100,
      101
    ],
    "Time Range": {
      "timeRangeType": 4,
      "startTime": "2020-06-04 23:02:11",
      "endTime": "2020-07-04 23:02:11"
    },
    "Top Recent Event Number": 20,
    "Constraint Condition": [
      {
        "Index": 1,
        "LogicOp": "",
        "LeftParen": 1,
        "RightParen": 1,
        "Command": {
          "CommandId": 204,
          "CommandName": null,
          "CommandDisplayName": null,
          "Operator": null,
          "CommandParams": [
            {
              "ParamName": "selectedField",
              "ParamDisplayName": null,
              "ParamIndex": 0,
              "ParamType": 0,
              "ParamTypeName": null,
              "ParamInputId": 0,
              "ParamValue": "Target.Events.DvcHostName",
              "DisplayValue": null,
              "InputId": 27754,
              "InputOption": null,
              "TemplateContent": null
            },
            {
              "ParamName": "filterValue",
              "ParamDisplayName": null,
              "ParamIndex": 0,
              "ParamType": 0,
              "ParamTypeName": null,
              "ParamInputId": 0,
              "ParamValue": "pc1",
              "DisplayValue": null,
              "InputId": 27755,
              "InputOption": null,
              "TemplateContent": null
            }
          ],
          "ExecOrder": 0,
          "ReturnType": 0,
          "PlaybookId": 0,
          "IsPython": false,
          "IsCustom": false,
          "Script": null,
          "CommandImplMode": 0
        }
      }
    ],
    "Correlation Condition": [
      {
        "Index": 1,
        "LogicOp": "",
        "LeftParen": 1,
        "RightParen": 1,
        "Command": {
          "CommandId": 204,
          "CommandName": null,
          "CommandDisplayName": null,
          "Operator": null,
          "CommandParams": [
            {
              "ParamName": "selectedField",
              "ParamDisplayName": null,
              "ParamIndex": 0,
              "ParamType": 0,
              "ParamTypeName": null,
              "ParamInputId": 0,
              "ParamValue": "Target.Events.Process.ProcessGUID",
              "DisplayValue": null,
              "InputId": 27743,
              "InputOption": null,
              "TemplateContent": null
            },
            {
              "ParamName": "filterValue",
              "ParamDisplayName": null,
              "ParamIndex": 0,
              "ParamType": 0,
              "ParamTypeName": null,
              "ParamInputId": 0,
              "ParamValue": "Source.Events.ParentProcessGuid",
              "DisplayValue": null,
              "InputId": 27742,
              "InputOption": null,
              "TemplateContent": null
            }
          ],
          "ExecOrder": 0
        }
      }
    ],
    "Incident Linkage": 1,
    "Link Relevant Incidents": null
  }
}

Response

Response Fields

Field Name	Type	Description
error	`string`	The error message if the API request has failed.
returnData	`boolean`	The return data from the API request.
contextData	`JSON Object`	The context data from the API request.

Sample Response

CODE

{
    "error": "",
    "returnData": "True",
    "contextData": {
      "eventCount": 5,
      "events": [
          {
              "ID": 15,
              "eventType": "Email Alerts",
              "eventTime": "2020-06-16 00:54:47",
              "intakeTime": "2020-06-16 00:54:47"
          },
          {
              "ID": 14,
              "eventType": "Email Alerts",
              "eventTime": "2020-06-16 00:54:47",
              "intakeTime": "2020-06-16 00:54:47"
          },
          {
              "ID": 13,
              "eventType": "Email Alerts",
              "eventTime": "2020-06-16 00:54:33",
              "intakeTime": "2020-06-16 00:54:33"
          },
          {
              "ID": 12,
              "eventType": "Email Alerts",
              "eventTime": "2020-06-16 00:54:03",
              "intakeTime": "2020-06-16 00:54:03"
          },
          {
              "ID": 11,
              "eventType": "Suspicious Email",
              "eventTime": "2020-06-16 00:52:03",
              "intakeTime": "2020-06-16 00:52:03",
              "linkedIncidentNumbers": [
                  "20211015-3"
              ]
          }
      ]
    }
}