Correlate Events

Search for events using two distinct criteria: constraint conditions, which are specific rules for identifying events, and correlation conditions, which rely on the values from the Source Event fields to discover related events. Furthermore, offer the capability to directly associate the events you identify with the ongoing incident and to connect any incidents related to these identified events to the same ongoing incident.

Implementation	System
Command Category	Cyber Utility
Tags	EVENT EVENTSEARCH

Inputs

Parameter Name	Required/Optional	Description	Sample Data
Source Event IDs	Optional	≈	`[` `100,` `101` `]`
Time Range	Optional	NOT AVAILABLE	`{` `"timeRangeType": 4,` `"startTime": "2020-06-04 23:02:11",` `"endTime": "2020-07-04 23:02:11"` `}`
Top Recent Event Number	Optional	NOT AVAILABLE	`20`
Constraint Condition	Optional	NOT AVAILABLE	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 - JSON Array Sample Data [ { "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	Optional	NOT AVAILABLE	`1`
Link Relevant Incidents	Optional	NOT AVAILABLE	NO SAMPLE DATA

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

No Sample Data

Context Data

The response data from the utility command.

SAMPLE DATA

JSON

No Sample Data

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/Optinal	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	`String`	Optional	NOT AVAILABLE
Time Range	`String`	Optional	NOT AVAILABLE
Top Recent Event Number	`Text Array`	Optional	NOT AVAILABLE
Constraint Condition	`JSON Object`	Optional	NOT AVAILABLE
Incident Linkage	`Number`	Optional	NOT AVAILABLE
Link Relevant Incidents	`JSON Array`	Optional	NOT AVAILABLE

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

NOT AVAILABLE