D3 Command API: Get Events | Get Incidents
Configuring Webhook Settings for a Utility Command
The D3 command API allows you to send requests to D3 SOAR to execute configured utility commands via REST API. This section will guide you through the process of configuring the required webhook settings for a utility command and provide sample data of an example request.
Find and select the desired integration command. Navigate to Configuration > Utility Commands > [Your Desired Utility Command]. For this example, we will select the Get Events utility command.
Under Webhook Settings, toggle on Webhook Keys and click on it.
On the Setup Webhook Keys window, click +. A webhook key will be generated. Click > to view the corresponding key's related information.
The generated webhook key and related information required to make the REST API request will appear under your selected connection name. You may use the Copy button of each corresponding parameter to copy the values to your clipboard easily.
Request URL: The request URL for the API request. A banner indicating the request method (e.g.
POST) will appear on the left of the request URL.Request Header Key: The request header key to authenticate the API request.
Request Header Value: The request header value to authenticate the API request. You may regenerate a new value by clicking Regenerate Key.
Request Body (Sample): A sample body data for the API request. Please note that the input parameters for different utility commands vary. Therefore, you will need to construct body data with the correct structure in your request. The provided sample body data is structured accordingly for the specific command. Using it as a template to build your body data is recommended.
Warning
The request body data must be structured properly in order to send a successful request.
With all the necessary values, you can send a REST API request to execute the utility command through Postman or other programs. The response of the API call will indicate the result of the command execution.
Get Events
The Get Events utility command can be accessed remotely via REST API, which returns a filtered list of ingested events from D3 SOAR 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 | A first-level object containing the command parameters. |
Filter | A second-level object containing the condition queries to filter events. The conditions are expressed as an array of arrays, where each inner array represents a set of conditions that must be satisfied for an event to be returned. An "AND" logic applies between JSON objects in the same array, and an "OR" logic applies between different arrays. Within each inner array, the "field" key indicates the selected field column (see the Fields parameter description for the list of available field columns), the "operator" key indicates the condition operator (listed below) applied to the field column, and the "value" key is the desired filter value. The available operators are: ["<",">","=","<=",">=","!=","LIKE",”IS EMPTY”,”IS NOT EMPTY”] |
Fields | The second-level object containing the array of event field columns to include in the response data. In the case of an empty input, all general fields (except for "Event Raw Data") will be displayed in respective events. The general fields are "ID", "Event ID", "Event Type", "Tactic" ,"Technique", "Risk Level", "Time of Occurrence (UTC)", "Intake Time (UTC)", "Status", "Description", "Site", "Data Source", "Event Source", "Username", "Source Ip", "Target Ip", "Integration Connection", "Uploaded Event File Name", "Last Escalated By", "Event Raw Data". |
Start Time | The start time of the specified time range to filter events. The DateTime format for this key is yyyy-mm-dd HH:mm:ss (e.g. 2023-01-26 00:00:00). Note: The time range is by event intake time, not time of occurrence. |
End Time | The end time of the specified time range to filter events. The DateTime format for this key is yyyy-mm-dd HH:mm:ss (e.g. 2023-01-27 00:00:00). Note: The time range is by event intake time, not time of occurrence. |
Output Format | The output format of the response data. The available formats for webhook are CSV and JSON. "1" - CSV "2" - JSON |
Page Index | The number of the page of results to return, expressed as an integer. This allows you to specify which portion of the overall results to retrieve. When combined with the Page Size parameter, the API can return a specific portion of the overall results, making it easier to work with large datasets. |
Page Size | The number of results to return in a single page of the response data, expressed as an integer. This allows you to specify the number of items to retrieve in each request. When combined with the Page Index parameter, the API can return a specific portion of the overall results, making it easier to work with large datasets. |
Sample Use Case
Let's consider a use case to understand how to structure an API request body for the Get Events command. In this scenario, we want to use the command, via webhook to retrieve events from D3 SOAR with the following criteria:
a. Ingested from SentinelOne, with the status of "New"
or
b. Ingested from SentinelOne, with the status of "Escalated".
Let's examine the "Filter" field and how we should structure our request body to match the criteria mentioned above. For the "Filter" field, an "AND" logic applies between JSON objects in the same array, and an "OR" logic applies between different arrays. So for our request, we would need to have two JSON arrays, each with two conditions.
Reader Note
When building your request, it is recommended to copy the sample data and modify it according to your scenario. This ensures the integrity of your request data's structure and format. For the explanation of each request body field, see Request Body Fields for Send API Requests from External Applications.
The first array, corresponding with criteria a, is as follows:
[
{
"field":"Data Source",
"operator":"=",
"value":"SentinelOne"
},
{
"field":"Status",
"operator":"=",
"value":"New"
}
]The second array, corresponding to criteria b, is as follows:
[
{
"field": "Data Source",
"operator": "=",
"value": "SentinelOne"
},
{
"field": "Status",
"operator": "=",
"value": "Escalated"
}
]Sample Request Body
Combining the two filters arrays and other request body fields, the complete request body is as follows:
{
"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
This JSON response data below includes information about seven events that matched the defined criteria in our request. The "rawData" section lists the seven events, along with the requested fields, including "Status" and "Data Source". The "outputData" section provides pagination information, including the current page index, page size, and the total number of pages. The "returnData" section indicates that the response was successful.
{
"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, which returns a filtered list of ingested incidents from D3 SOAR 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 | A first-level object containing the command parameters. |
Filter | A second-level object containing the condition queries to filter incidents. The conditions are expressed as an array of arrays, where each inner array represents a set of conditions that must be satisfied for an incident to be returned. An "AND" logic applies between JSON objects in the same array, and an "OR" logic applies between different arrays. Within each inner array, the "field" key indicates the selected field column (see Fields for the list of available field columns), the "operator" key indicates the condition operator (listed below) applied to the field column, and the "value" key is the desired filter value. The available operators are: ["<",">","=","<=",">=","!=","LIKE",”IS EMPTY”,”IS NOT EMPTY”] |
Static Fields | The second-level object containing the array of static incident field columns to include in the response data. In the case of an empty input, all general fields (except for "Incident Raw Data" and "Event Raw Data") will be displayed in respective events. The general fields are "Incident No.", "Incident Type", "Title", "Status", "Severity", "Stage", "Priority", "Disposition", "Tags", "Owner", "Created by", "Time Zone", "Date Created (UTC)", "Date Modified", "Playbook", "Description", "Conclusion", "Investigation Team", "Linked Incidents", "Incident Raw Data", "Event Raw Data". |
Dynamic Fields | This second-level object containing the array of dynamic field columns. The key in the JSON object represents the section name of a dynamic field. The value array contains the names of the elements under the section. |
Start Time | The start time of the specified time range to filter incidents. The DateTime format for this key is yyyy-mm-dd HH:mm:ss (e.g. 2023-01-26 00:00:00). Note: The time range is by incident creation time. |
End Time | The end time of the specified time range to filter incidents. The DateTime format for this key is yyyy-mm-dd HH:mm:ss (e.g. 2023-01-27 00:00:00). Note: The time range is by incident creation time. |
Output Format | The output format of the response data. The available formats for webhook are CSV and JSON. "1" - CSV "2" - JSON |
Page Index | The number of the page of results to return, expressed as an integer. This allows you to specify which portion of the overall results to retrieve. When combined with the Page Size parameter, the API can return a specific portion of the overall results, making it easier to work with large datasets. |
Page Size | The number of results to return in a single page of the response data, expressed as an integer. This allows you to specify the number of items to retrieve in each request. When combined with the Page Index parameter, the API can return a specific portion of the overall results, making it easier to work with large datasets. |
Sample Use Case
Let's consider a use case to understand how to structure an API request body for the Get Incidents command. In this scenario, we want to use the command, via webhook to retrieve incidents from D3 SOAR with the following criteria:
Has the status as "Open", a "critical" severity level with the user account "Test D3" as the incident owner
or
Has the status as "Open", a "high" severity level with the user account "Test D3" as the incident owner.
Let's examine the "Filter" field and how we should structure our request body to match the criteria mentioned above. For the "Filter" field, an "AND" logic applies between JSON objects in the same array, and an "OR" logic applies between different arrays. So for our request, we would need to have two JSON arrays, each with three conditions.
Reader Note
When building your request, it is recommended to copy the sample data and modify it according to your scenario. This ensures the integrity of your request data's structure and format. For the explanation of each request body field, see Request Body Fields for Send API Requests from External Applications..
The first array, corresponding with criteria a, is as follows:
[
{
"field":"Status",
"operator":"=",
"value":"Open"
},
{
"field":"Severity",
"operator":"=",
"value":"Critical"
},
{
"field":"Owner",
"operator":"=",
"value":"Test D3"
}
]The second array, corresponding to criteria b, is as follows:
[
{
"field":"Status",
"operator":"=",
"value":"Open"
},
{
"field":"Severity",
"operator":"=",
"value":"High"
},
{
"field":"Owner",
"operator":"=",
"value":"Test D3"
}
]Sample Request Body
Combining the two filters arrays and other request body fields, the complete request body is as follows:
{
"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
This JSON response data below includes information about two events that matched the defined criteria in our request. The "rawData" section lists the two events, along with the requested fields, including "Status" and "Severity". The "outputData" section provides pagination information, including the current page index, page size, and the total number of pages. The "returnData" section indicates that the response was successful.
{
"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
}
}