Get Events‎

POST /Command/GetEvents

Gets a list of filtered events with specified fields.

Request

Authentication: API keys or JSON web tokens (JWT)

Body Parameters

Parameter Name	Type	Required/Optional	Description
Username	`string`	Required	The username of the D3 SOAR user account making the request.
Site	`string`	Required	The D3 SOAR site containing the desired incidents to retrieve with the request.
Filter	`arrays<array<JSON Object>>`	Optional	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	`array<string>`	Optional	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	`string`	Required	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	`string`	Required	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	`integer`	Required	Allows users to choose the format in which to present event data. Available options are: 1 (CSV) 2 (JSON) 3 (CSV link) 4 (JSON link)
Page Index	`integer`	Optional	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	`integer`	Optional	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.
Sort Field	`string`	Optional	The field by which the results are sorted. Users can specify any field listed in the Fields parameter (e.g., `Date Created`, `Event ID`, etc.). Sorting will not apply to fields excluded from the Fields parameter. Fields containing a period (.) in their name are not supported for sorting.
Sort Order	`string`	Optional	The order in which the results are sorted. This parameter is used in conjunction with Sort Field to control the sort behaviour.

READER NOTE

Fields represents an input parameter as an array of strings. Each field in this array is optional. If you include these fields, the response will contain the specified fields. The options are:

ID, EventID, Type, Tactic, Technique, RiskLevel, TimeofOccurrence, IntakeTime, Status, Description, Site, Datasource, Eventsource, Username, Sourceip, Targetip, Integrationconnection, EventFileName, LastEscalatedBy, Event Raw Data, LinkedIncidents

READER NOTE
The fields "Event Raw Data" can contain large amounts of data. Use these fields cautiously and consider using pagination input parameters (page index and page number) to manage the data volume efficiently.

READER NOTE

For Date/Time parameters Start Time, End Time:

All times and timestamps are in this format: yyyy-MM-dd HH:mm:ss.

For example, May 15, 2024, 2:32 PM should be 2024-05-15 14:32:00.

Body Sample Data

application/json

JSON

{
  "Username": "Admin",
  "Site": "Security Operations",
  "CommandParams": {
    "Filter": [
      [
        {
          "field": "Status",
          "operator": "=",
          "value": "Escalated"
        },
        {
          "field": "IntakeTime",
          "operator": ">=",
          "value": "2020-09-25 23:20:03.693"
        }
      ],
      [
        {
          "field": "RiskLevel",
          "operator": "=",
          "value": "High"
        }
      ]
    ],
    "Fields": [
      "ID",
      "EventID",
      "Type",
      "Tactic",
      "Technique",
      "RiskLevel",
      "TimeofOccurrence",
      "IntakeTime",
      "Status",
      "Description",
      "Site",
      "Datasource",
      "Eventsource",
      "Username",
      "Sourceip",
      "Targetip",
      "Integrationconnection",
      "EventFileName",
      "LastEscalatedBy",
      "Event Raw Data",
      "LinkedIncidents"
    ],
    "Start Time": "2020-01-06 01:30:00",
    "End Time": "2020-10-23 07:45:00",
    "Output Format": 2,
    "Page Index": 0,
    "Page Size": 100,
    "Sort Field": "Event ID",
    "Sort Order": "Ascending"
  }
}

Response

200 OK

application/json

Response Fields

Field Name	Type	Description
error	`string`	The error message if the API request has failed.
keyFields	`JSON Object`	The key fields from the API request.
returnData	`string`	The return data from the API request.
rawData	`string`	The raw data from the API request.

Sample Data

JSON

{
    "events": [
        {
            "ID": "*****",
            "Event ID": 60075,
            "Event Type": "DEVICE_PLUG",
            "Event Name": "Sample Name",
            "Tactic": "Defense Evasion",
            "Technique": "Drive-by Compromise",
            "Risk Level": "High",
            "Time of Occurrence": null,
            "Intake Time": "2020-09-24 23:24:09.640",
            "Status": "Open",
            "Description": null,
            "Site": "APSOC",
            "Data Source": "McAfee ePolicy Orchestrator",
            "Event Source": "Default Event Source",
            "Username": null,
            "Source IP": null,
            "Target IP": null,
            "Integration Connection": "Webhook",
            "Uploaded Event File Name": null,
            "Last Escalated By": "Admin User",
            "Time of Event Escalation (UTC)": "2024-08-26 18:23:47.270",
            "Time of Event Dismissal (UTC)": "",
            "Linked Incidents": [
                "20200924-5"
            ],
            "Event Raw Data": {
                "id": "*****",
                "createdDateTime": "2021-06-01T17:48:19Z",
                "lastModifiedDateTime": "2021-07-08T18:08:20Z",
                "receivedDateTime": "2021-06-01T17:48:19Z",
                "sentDateTime": "2021-06-01T17:47:55Z",
                "hasAttachments": true,
                "internetMessageId": "",
                "subject": "Report Phishing",
                "importance": "normal"
            }
        },
        {
            "ID": "*****",
            "Event ID": 60078,
            "Event Type": "DEVICE_PLUG",
            "Event Name": "Sample Name",
            "Tactic": "Execution",
            "Technique": "Timestomp",
            "Risk Level": "High",
            "Time of Occurrence": null,
            "Intake Time": "2020-09-25 23:20:03.693",
            "Status": "Escalated",
            "Description": null,
            "Site": "APSOC",
            "Data Source": "McAfee ePolicy Orchestrator",
            "Event Source": "Default Event Source",
            "Username": null,
            "Source IP": null,
            "Target IP": null,
            "Integration Connection": "Webhook",
            "Uploaded Event File Name": null,
            "Last Escalated By": "Admin User",
            "Time of Event Escalation (UTC)": "",
            "Time of Event Dismissal (UTC)": "2024-08-26 18:23:47.270",
            "Linked Incidents": [
                "20200925-5"
            ],
            "Event Raw Data": {
                "id": "*****",
                "createdDateTime": "2021-06-01T17:48:19Z",
                "lastModifiedDateTime": "2021-07-08T18:08:20Z",
                "receivedDateTime": "2021-06-01T17:48:19Z",
                "sentDateTime": "2021-06-01T17:47:55Z",
                "hasAttachments": true,
                "internetMessageId": "",
                "subject": "Report Phishing",
                "importance": "normal"
            }
        },
        {
            "ID": "*****",
            "Event ID": 60076,
            "Event Type": "DEVICE_PLUG",
            "Event Name": "Sample Name",
            "Tactic": "Collection",
            "Technique": "Data from Removable Media",
            "Risk Level": "High",
            "Time of Occurrence": null,
            "Intake Time": "2020-09-24 23:26:03.693",
            "Status": "Dismissed",
            "Description": null,
            "Site": "APSOC",
            "Data Source": "McAfee ePolicy Orchestrator",
            "Event Source": "Default Event Source",
            "Username": null,
            "Source IP": null,
            "Target IP": null,
            "Integration Connection": "Webhook",
            "Uploaded Event File Name": null,
            "Last Escalated By": "Admin User",
            "Time of Event Escalation (UTC)": "2024-08-26 18:23:47.270",
            "Time of Event Dismissal (UTC)": "",
            "Linked Incidents": [
                "20200924-1"
            ],
            "Event Raw Data": {
                "id": "*****=8",
                "createdDateTime": "2021-06-01T17:48:19Z",
                "lastModifiedDateTime": "2021-07-08T18:08:20Z",
                "receivedDateTime": "2021-06-01T17:48:19Z",
                "sentDateTime": "2021-06-01T17:47:55Z",
                "hasAttachments": true,
                "internetMessageId": "",
                "subject": "Report Phishing",
                "importance": "normal"
            }
        }
    ]
}

400 BadRequest

application/json

Response Fields

Field Name	Type	Description
Error	`string`	A error message when the API request fails.

Sample Data

JSON

{"Error": "The body of the request must be a valid JSON object"}

401 Unauthorized

application/json

Response Fields

Field Name	Type	Description
Error	`string`	A error message when the API request fails.

Sample Data

JSON

{"Error": "Invalid authentication key."}

429 TooManyRequests

application/json

Response Fields

Field Name	Type	Description
Error	`string`	A error message when the API request fails.

Sample Data

JSON

{"Error": "The request exceeds rate limits or is otherwise blocked by rate limiting policies."}

500 InternalServerError

application/json

Response Fields

Field Name	Type	Description
Error	`string`	A error message when the API request fails.

Sample Data

JSON

{"Error": "Unexpected Error."}