Utility Command API: Get Events | Get Incidents

LAST UPDATED: SEP 27, 2024

The D3 utility command API enables the execution of configured utility commands via REST API by sending requests to D3 SOAR. This section outlines the process for configuring the necessary webhook settings for a utility command, and provides sample data for an example request.

Webhook Setup and API Request Essentials

Navigate to Configuration > Utility Commands > Get Events / Get Incidents.
Click on the toggle next to the Webhook Authentication header.
Click on Webhook Keys.
Generate an API key.
1. Click on the + button.
2. Enter an alias for your key.
3. Click on the Generate button.

The generated webhook key and the associated information necessary for making the REST API request will be displayed under your selected connection name. Each parameter's value can be copied to your clipboard using the Copy button.

Observe all HTTP POST request constituents. Also see Introduction to D3 Command API.
1. The mutable name of the remote command key. The modified key name can be observed upon re-entering the command page.
2. Request URL: The endpoint URL for the API request. The URL of all D3 utility command API endpoints conforms to the following format: https://<site_url>/api/Command/<endpoint>.
3. Request Header Key: The key used in the request header for authenticating the API request.
4. Request Header Value: The request header value to authenticate the API request.
5. Request Body (Sample): A sample request body for the API request is provided. Input parameters vary among different utility commands, so it is essential to construct the body data according to the specific command.

After obtaining all required values, send a REST API request to execute the utility command using Postman or other tools. The API response will reflect the outcome of the command execution.

READER NOTE

When constructing your request, it is advisable to copy the sample data (step 5d in the Webhook Setup and API Request Essentials section) and modify it accordingly. This approach helps maintain the integrity of the request data's structure and format.

Get Events

The Get Events utility command can be accessed remotely via REST API. A filtered list of ingested events from D3 SOAR will be returned based on the criteria specified in the request body fields.

Request Body Fields for Send API Requests from External Applications

Request Body Fields	Description
Username	The username of the D3 SOAR user account making the request.
Site	The D3 SOAR site containing the desired events to retrieve with the request.
Command Params	An object containing the parameters required for executing the command.
Filter	The array of criteria, each containing one or more JSON object conditions, used to filter events. The "field" key points to an event field. The "operator" key is the condition operator that establishes the logical relationship between the field and the value. The supported operators are: ["<", ">", "=", "<=", ">=", "!=", "LIKE", "IS EMPTY", and "IS NOT EMPTY"]. The "value" key is the data or criterion that the field is compared against. The "AND" logic applies between JSON objects within the same array, whereas the "OR" logic applies between different arrays.
Fields	The event fields to include in the response data. If no fields are specified, the default fields displayed are all those listed in the Sample Data, except for "Event Raw Data."
Start Time	The start time (in UTC) for retrieving events. The time range is based on event intake time, rather than the time of occurrence. The API requires the input format to be yyyy-mm-dd HH:mm (e.g., 2024-08-22 00:00:00).
End Time	The end time (in UTC) for retrieving events. The time range is based on event intake time, rather than the time of occurrence. The API requires the DateTime format to be yyyy-mm-dd HH:mm (e.g., 2024-08-22 00:00:00).
Output Format	Allows users to choose the format in which to present event data. The options are: 1) CSV, 2) JSON, 3) CSV link, and 4) JSON link.
Page Index	The page number to view a subset of events. For example, if there exists 50 events, and the Page Size (the following parameter) is set to 49, and the Page Index is set to 1 (the second page), only one event will be displayed. The default page index is 0, indicating the first page. If no value or 0 is provided for both Page Index and Page Size, all incidents will be fetched. If the provide page index is greater than zero, a "TotalPages" property will be displayed within the Key Fields tab in the output.
Page Size	The maximum number of event records to fetch, ranging from 1 to 1000. For example, if there exists 50 events, and the Page Size is set to 49, and the Page Index (the previous parameter) is set to 1 (the second page), only one event will be displayed. If no value or 0 is provided, a default page size of 100 will be applied. If no value or 0 is provided for both Page Index and Page Size, all events will be fetched. If the page size is greater than zero, a "TotalPages" property will be displayed within the Key Fields tab in the output.

Sample Use Case

Let us examine a use case to illustrate how to structure an API request body for the Get Events command. The objective is to use the command via webhook to retrieve events from D3 SOAR. Consider the following criteria:

a. Events ingested from SentinelOne, with a status of "New," or

b. Events ingested from SentinelOne with a status of "Escalated".

The first array, aligned with criteria a, is as follows:

JSON

[
   {
      "field":"Data Source",
      "operator":"=",
      "value":"SentinelOne"
   },
   {
      "field":"Status",
      "operator":"=",
      "value":"New"
   }
]

The second array, aligned with criteria b, is as follows:

JSON

[
    {
        "field": "Data Source",
        "operator": "=",
        "value": "SentinelOne"
    },
    {
        "field": "Status",
        "operator": "=",
        "value": "Escalated"
    }
]

READER NOTE

For the Get Events utility command, variations in the "Fields" command parameter exist across different vSOC versions. Consult the official utility command documentation to identify the fields available in the output.

Sample Request Body

Combining the two filter arrays, and nine desired request body fields for vSOC versions 16.8+ (inclusive), the complete request body is as follows:

JSON

{
   "Username":"Test_D3",
   "Site":"SentinelOne Site",
   "CommandParams":{
      "Filter":[
         [
            {
               "field":"Data Source",
               "operator":"=",
               "value":"SentinelOne"
            },
            {
               "field":"Status",
               "operator":"=",
               "value":"New"
            }
         ],
         [
            {
               "field":"Data Source",
               "operator":"=",
               "value":"SentinelOne"
            },
            {
               "field":"Status",
               "operator":"=",
               "value":"Escalated"
            }
         ]
      ],
      "Fields":[
         "Event ID",
         "Site",
         "Tactic",
         "Technique",
         "Description",
         "Time of Occurrence (UTC)",
         "Intake Time (UTC)",
         "Status",
         "Data Source"
      ],
      "Start Time":"2023-02-06 21:31:00",
      "End Time":"2023-02-06 23:30:00",
      "Output Format":2,
      "Page Index":0,
      "Page Size":100
   }
}

Sample Response Data

Upon sending the HTTP POST request, users will receive a JSON response data like the one below. In this example, the response includes details on seven events that meet the criteria specified in the request.

JSON

{
    "error": "",
    "returnData": "Successful",
    "rawData": {
        "events": [
            {
                "Event ID": 28401,
                "Site": "SentinelOne Site",
                "Tactic": "Execution, Initial Access",
                "Technique": "User Execution, Valid Accounts",
                "Description": "True positive",
                "Time of Occurrence (UTC)": "2022-09-14 05:43:51.767",
                "Intake Time (UTC)": "2023-02-06 23:14:58.070",
                "Status": "Escalated",
                "Data Source": "SentinelOne"
            },
            {
                "Event ID": 28397,
                "Site": "SentinelOne Site",
                "Tactic": "Execution, Initial Access",
                "Technique": "User Execution, Valid Accounts",
                "Description": "True positive",
                "Time of Occurrence (UTC)": "2022-09-14 05:43:51.767",
                "Intake Time (UTC)": "2023-02-06 22:48:20.610",
                "Status": "Escalated",
                "Data Source": "SentinelOne"
            },
            {
                "Event ID": 28391,
                "Site": "SentinelOne Site",
                "Tactic": "Execution, Initial Access",
                "Technique": "User Execution, Valid Accounts",
                "Description": "True positive",
                "Time of Occurrence (UTC)": "2022-09-14 05:43:51.767",
                "Intake Time (UTC)": "2023-02-06 21:42:09.860",
                "Status": "Escalated",
                "Data Source": "SentinelOne"
            },
            {
                "Event ID": 28389,
                "Site": "SentinelOne Site",
                "Tactic": "Execution, Initial Access",
                "Technique": "User Execution, Valid Accounts",
                "Description": "Suspicious",
                "Time of Occurrence (UTC)": "2022-09-14 05:43:51.767",
                "Intake Time (UTC)": "2023-02-06 21:37:30.317",
                "Status": "Escalated",
                "Data Source": "SentinelOne"
            },
            {
                "Event ID": 28388,
                "Site": "SentinelOne Site",
                "Tactic": "Execution, Initial Access",
                "Technique": "User Execution, Valid Accounts",
                "Description": "True positive",
                "Time of Occurrence (UTC)": "2022-09-14 05:43:51.767",
                "Intake Time (UTC)": "2023-02-06 21:36:52.547",
                "Status": "Escalated",
                "Data Source": "SentinelOne"
            },
            {
                "Event ID": 28385,
                "Site": "SentinelOne Site",
                "Tactic": "Execution",
                "Technique": "User Execution",
                "Description": "Undefined",
                "Time of Occurrence (UTC)": "2022-09-14 05:43:51.767",
                "Intake Time (UTC)": "2023-02-06 21:33:25.887",
                "Status": "New",
                "Data Source": "SentinelOne"
            },
            {
                "Event ID": 28384,
                "Site": "SentinelOne Site",
                "Tactic": "Execution",
                "Technique": "User Execution",
                "Description": "Undefined",
                "Time of Occurrence (UTC)": "2022-09-14 05:43:51.767",
                "Intake Time (UTC)": "2023-02-06 21:33:14.957",
                "Status": "New",
                "Data Source": "SentinelOne"
            }
        ]
    },
    "contextData": "",
    "outputData": {
        "PageIndex": 0,
        "PageSize": 100,
        "TotalPages": 1
    }
}

Get Incidents

The Get Incidents utility command can be accessed remotely via REST API. A filtered list of ingested incidents from D3 SOAR will be returned based on the criteria specified in the request body fields.

Request Body Fields for Send API Requests from External Applications

Request Body Fields	Description
Username	The username of the D3 SOAR user account making the request.
Site	The D3 SOAR site containing the desired incidents to retrieve with the request.
Command Params	An object containing the parameters required for executing the command.
Filter	The list of criteria, each containing one or more JSON object conditions, used to filter incidents. The "field" key points to an incident field. The "operator" key is the condition operator that establishes the logical relationship between the field and the value. The supported operators are: ["<", ">", "=", "<=", ">=", "!=", "LIKE", "IS EMPTY", and "IS NOT EMPTY"]. The "value" key is the data or criterion that the field is compared against. The "section" key is optional. When included in a condition, filtering will use Dynamic Fields instead of Static Fields. The "field" property must be assigned a value that matches the name of an Activity or Info Activity UI block under the specified section in the Incident Form Editor. The "AND" logic applies between JSON objects within the same array, whereas the "OR" logic applies between different arrays. For non-dynamic "field" values, refer to the sample data for the following Static Fields input parameter.
Static Fields	The static incident fields to be included in the results. Default fields will be selected for each resulting incident if the Static Fields input is left empty. For D3 vSOC versions earlier than 16.8, default fields are all those in the sample data except for "Incident Raw Data" and "Event Raw Data." For D3 vSOC versions 16.8 and later, default fields are all those in the sample data except for "Date Closed," "Closed by," "Incident Raw Data" and "Custom Field." In these later versions, the "Playbook" static field returns playbooks that have either been completed or stopped due to an error. The static fields "Date Created," "Date Modified" and "Date Closed" are in UTC time.
Dynamic Fields	The dynamic incident fields to be included in the results. A key in the JSON object is the user-specified Section name of a dynamic field (i.e. incident form). The value (string array) corresponding to a key is the user-specified Activity or Info Activity name within the section.
Start Time	The start time (in UTC) for retrieving incidents, based on the "Date Created" field of the incident.
End Time	The end time (in UTC) for retrieving incidents, based on the "Date Created" field of the incident.
Output Format	Allows users to choose the format in which to present incident data. The options are: 1) CSV, 2) JSON, 3) CSV link, and 4) JSON link.
Page Index	A page of incident records. The default page index is 0, indicating the first page. For example, if there exists 50 incidents, and the Page Size (the following parameter) is set to 49, and the Page Index is set to 1 (the second page), only one incident will be displayed. If no value or 0 is provided for both Page Index and Page Size, all incidents will be fetched. If the provide page index is greater than zero, a "TotalPages" property will be displayed within the Key Fields tab in the output.
Page Size	The number of incident records to display within a page, ranging from 1 to 1000. If no value or 0 is provided, a default page size of 100 will be applied. If no value or 0 is provided for both Page Index and Page Size, all incidents will be fetched. If the page size is greater than zero, a "TotalPages" property will be displayed within the Key Fields tab in the output.

Sample Use Case

Let us examine a use case to illustrate how to structure an API request body for the Get Incidents command. The objective is to use the command via webhook to retrieve incidents from D3 SOAR. Consider the following incident criteria:

a. The status is "Open," the severity level is "critical," and the incident owner is the user account "Test D3." or

b. The status is "Open," the severity level is "high," and the incident owner is the user account "Test D3."

The first array, aligned with criteria a, is as follows:

JSON

[
   {
      "field":"Status",
      "operator":"=",
      "value":"Open"
   },
   {
      "field":"Severity",
      "operator":"=",
      "value":"Critical"
   },
   {
      "field":"Owner",
      "operator":"=",
      "value":"Test D3"
   }
]

The second array, aligned with criteria b, is as follows:

JSON

[
   {
      "field":"Status",
      "operator":"=",
      "value":"Open"
   },
   {
      "field":"Severity",
      "operator":"=",
      "value":"High"
   },
   {
      "field":"Owner",
      "operator":"=",
      "value":"Test D3"
   }
]

READER NOTE

For the Get Incidents utility command, variations in the "Static Fields" command parameter exist across different vSOC versions. Consult the official utility command documentation to identify the static fields available in the output.

Sample Request Body

Combining the two filters arrays and other request body fields, the complete request body is as follows:

JSON

{
    "Username": "Test_D3",
    "Site": "SentinelOne Site",
    "CommandParams": {
        "Filter": [
            [
                {
                    "field": "Status",
                    "operator": "=",
                    "value": "Open"
                },
                {
                    "field": "Severity",
                    "operator": "=",
                    "value": "Critical"
                },
                {
                    "field": "Owner",
                    "operator": "=",
                    "value": "Test D3"
                }
            ],
            [
                {
                    "field": "Status",
                    "operator": "=",
                    "value": "Open"
                },
                {
                    "field": "Severity",
                    "operator": "=",
                    "value": "High"
                },
                {
                    "field": "Owner",
                    "operator": "=",
                    "value": "Test D3"
                }
            ]
        ],
        "Static Fields": [
            "Incident No.",
            "Incident Type",
            "Title",
            "Status",
            "Severity",
            "Stage",
            "Owner",
            "Date Created (UTC)"
        ],
        "Dynamic Fields": {
            "Blacklist Check": [
                "IPs in the Blacklist",
                "Domains in the Blacklist",
                "Host Name in the Blacklist"
            ],
            "Whitelist Check": [
                "IPs in the Whitelist",
                "Domains in the Whitelist",
                "Host Name in the Whitelist"
            ]
        },
        "Start Time": "2023-02-06 21:31:00",
        "End Time": "2023-02-06 23:30:00",
        "Output Format": 2,
        "Page Index": 0,
        "Page Size": 100
    }
}

Sample Response Data

Upon sending the HTTP POST request, users will receive a JSON response data like the one below. In this example, the response includes details on two incidents that meet the criteria specified in the request.

JSON

{
   "error":"",
   "returnData":"Successful",
   "rawData":{
      "incidents":[
         {
            "Incident No.":"20230206-23",
            "Incident Type":"Malware",
            "Title":"Anomalous Single Factor Sign-in",
            "Status":"Open",
            "Severity":"High",
            "Stage":"Event Correlation",
            "Owner":"Test D3",
            "Date Created (UTC)":"2023-02-06 22:48:24.453",
            "Blacklist Check - IPs in the Blacklist":"216.251.148.178, 5.255.99.205",
            "Blacklist Check - Domains in the Blacklist":"xmr.pool.minergate.com",
            "Blacklist Check - Host Name in the Blacklist":"HN-XYZ-1,HN-XYZ-2",
            "Whitelist Check - IPs in the Whitelist":"8.8.8.8",
            "Whitelist Check - Domains in the Whitelist":"google.com",
            "Whitelist Check - Host Name in the Whitelist":"HN-ZZZ-1"
         },
         {
            "Incident No.":"20230206-19",
            "Incident Type":"Malware",
            "Title":"Brute force attack against Azure Portal",
            "Status":"Open",
            "Severity":"Critical",
            "Stage":"Event Correlation",
            "Owner":"Test D3",
            "Date Created (UTC)":"2023-02-06 21:36:55.873",
            "Blacklist Check - IPs in the Blacklist":"195.178.120.152",
            "Blacklist Check - Domains in the Blacklist":"xmr.pool.minergate.com",
            "Blacklist Check - Host Name in the Blacklist":"HN-XYZ-2,HN-XYZ-3",
            "Whitelist Check - IPs in the Whitelist":"208.65.153.238",
            "Whitelist Check - Domains in the Whitelist":"youtube.com",
            "Whitelist Check - Host Name in the Whitelist":"HN-YYY-2"
         }
      ]
   },
   "contextData":"",
   "outputData":{
      "PageIndex":0,
      "PageSize":100,
      "TotalPages":1
   }
}