Skip to main content
Skip table of contents

Get Incidents

LAST UPDATED: AUG 23, 2024

Retrieves a customized list of incidents.

Implementation

System

Command Category

Basic Utility

Tags

INCIDENT INCIDENT MANAGEMENT

Inputs

Parameter Name

Required/Optional

Description

Sample Data

Filter

Optional

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.

CODE
[
    [
        {
            "field": "Status",
            "operator": "=",
            "value": "Open"
        },
        {
            "field": "Severity",
            "operator": "=",
            "value": "High"
        }
    ],
    [
        {
            "section": "Customer",
            "field": "Name",
            "operator": "LIKE",
            "value": "VIP%"
        }
    ]
]

Static Fields

Optional

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.

BEFORE VERSION 16.8

CODE
[
    "IR Number",
    "IR Type",
    "Title",
    "Status",
    "Severity",
    "Stage",
    "Priority",
    "Disposition",
    "Tags",
    "Owner",
    "Creator",
    "Timezone",
    "Date Created",
    "Date Modified",
    "Playbook",
    "Description",
    "Conclusion",
    "Investigation Team",
    "Linked Incidents",
    "Incident Raw Data",
    "Event Raw Data"
]

VERSION 16.8+

CODE
[
    "Incident No.",
    "Incident Type",
    "Title",
    "Status",
    "Severity",
    "Stage",
    "Priority",
    "Disposition",
    "Tags",
    "Owner",
    "Creator",
    "Closed by",
    "Time Zone",
    "Date Created",
    "Date Modified",
    "Date Closed",
    "Playbook",
    "Description",
    "Conclusion",
    "Investigation Team",
    "Linked Incidents",
    "Incident Raw Data",
    "Custom Field",
    "Events"
]

Dynamic Fields

Optional

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.

CODE
{
    "Incident Owner": [
        "Owner Last Update Time",
        "Time Spend"
    ],
    "Customer": [
        "Name",
        "Country"
    ]
}

Start Time

Required

The start time (in UTC) for retrieving incidents, based on the "Date Created" field of the incident.

2019-03-26 00:00:00

End Time

Required

The end time (in UTC) for retrieving incidents, based on the "Date Created" field of the incident.

2021-12-31 10:15:00

Output Format

Optional

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.

2

Page Index

Optional

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.

0

Page Size

Optional

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.

100

Output

Key Fields

Important key-value pairs extracted from Raw Data.

SAMPLE DATA

JSON
{
  "Pagination" : {
      "PageIndex": 0,
      "PageSize": 100,
      "TotalPages": 10
  }
}
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
Successful
Raw Data

The response data from the utility command.

SAMPLE DATA BEFORE VERSION 16.8

JSON
{
    "incidents": [
        {
            "IR Number": "20211222-3",
            "IR Type": "Playbook - DLP",
            "Title": "222222222",
            "Status": "Open",
            "Severity": "High",
            "Stage": "Data Aggregation Stage",
            "Priority": "1 - Medium",
            "Disposition": "N/A",
            "Tags": "",
            "Owner": "admin user",
            "Creator": "admin",
            "Timezone": "PST",
            "Date Created": "2019-04-08 09:17:32",
            "Date Modified": "2019-04-09 11:31:30",
            "Playbook": "Endpoint Protection - Unauthorized Access",
            "Description": "",
            "Conclusion": "",
            "Investigation Team": "",
            "Linked Incidents": "",
            "Incident Raw Data": "",
            "Event Raw Data": "",
            "Customer - Name": "VIP_Mary",
            "Customer - Country": "France",
            "Incident Owner - Owner Last Update Time": null,
            "Incident Owner - Time Spend": null
        },
        {
            "IR Number": "20211222-4",
            "IR Type": "Playbook - DLP",
            "Title": "",
            "Status": "Open",
            "Severity": "High",
            "Stage": "Data Aggregation Stage",
            "Priority": "1 - Medium",
            "Disposition": "N/A",
            "Tags": "",
            "Owner": "admin user",
            "Creator": "admin",
            "Timezone": "PST",
            "Date Created": "2021-12-22 15:14:26",
            "Date Modified": "2021-12-22 15:51:56",
            "Playbook": "Endpoint Protection - Unauthorized Access",
            "Description": "",
            "Conclusion": "",
            "Investigation Team": "",
            "Linked Incidents": "",
            "Incident Raw Data": "",
            "Event Raw Data": "",
            "Customer - Name": "VIP_Robert",
            "Customer - Country": "Canada",
            "Incident Owner - Owner Last Update Time": null,
            "Incident Owner - Time Spend": null
        }
    ]
}

SAMPLE DATA VERSION 16.8+

CODE
{
    "incidents": [
        {
            "Incident No.": "20211222-3",
            "Incident Type": "Playbook - DLP",
            "Title": "222222222",
            "Status": "Open",
            "Severity": "High",
            "Stage": "Data Aggregation Stage",
            "Priority": "1 - Medium",
            "Disposition": "",
            "Tags": "",
            "Owner": "Admin User",
            "Creator": "admin",
            "Closed by": "System User",
            "Time Zone": "PST",
            "Date Created": "2019-04-08 09:17:32",
            "Date Modified": "2019-04-09 11:31:30",
            "Date Closed": "2019-05-14 13:46:00",
            "Playbook": "Endpoint Protection - Unauthorized Access",
            "Description": "",
            "Conclusion": "",
            "Investigation Team": "",
            "Linked Incidents": "20211223-20",
            "Incident Raw Data": "",
            "Customer - Name": "VIP_Mary",
            "Customer - Country": "France",
            "Incident Owner - Owner Last Update Time": null,
            "Incident Owner - Time Spend": null,
            "Custom Field": ""
        },
        {
            "Incident No.": "20211222-4",
            "Incident Type": "Playbook - DLP",
            "Title": "",
            "Status": "Open",
            "Severity": "High",
            "Stage": "Data Aggregation Stage",
            "Priority": "1 - Medium",
            "Disposition": "",
            "Tags": "",
            "Owner": "Admin User",
            "Creator": "admin",
            "Closed by": "System User",
            "Time Zone": "PST",
            "Date Created": "2021-12-22 15:14:26",
            "Date Modified": "2021-12-22 15:51:56",
            "Date Closed": "2021-12-24 16:15:14",
            "Playbook": "Endpoint Protection - Unauthorized Access",
            "Description": "",
            "Conclusion": "",
            "Investigation Team": "",
            "Linked Incidents": "20211225-1,20211225-2",
            "Incident Raw Data": "",
            "Customer - Name": "VIP_Robert",
            "Customer - Country": "Canada",
            "Incident Owner - Owner Last Update Time": null,
            "Incident Owner - Time Spend": null,
            "Custom Field": ""
        }
    ]
}

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/GetIncidents

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": {
    "Filter": "<Filter here>",
    "Static Fields": "<Static Fields here>",
    "Dynamic Fields": "<Dynamic Fields here>",
    "Start Time": "<Start Time here>",
    "End Time": "<End Time here>",
    "Output Format": "<Output Format here>",
    "Page Index": "<Page Index here>",
    "Page Size": "<Page Size 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.

Filter

array<array<JSON Object>>

Optional

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

array<string>

Optional

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

JSON Object

Optional

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

string

Required

The start time (in UTC) for retrieving incidents, based on the "Date Created" field of the incident.

End Time

string

Required

The end time (in UTC) for retrieving incidents, based on the "Date Created" field of the incident.

Output Format

integer

Optional

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

integer

Optional

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

integer

Optional

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 Request

SAMPLE DATA BEFORE VERSION 16.8

JSON
{
  "Username": "Admin",
  "Site": "Security Operations",
  "CommandParams": {
    "Filter": [
      [
        {
          "field": "Status",
          "operator": "=",
          "value": "Open"
        },
        {
          "field": "Severity",
          "operator": "=",
          "value": "High"
        }
      ],
      [
        {
          "section": "Customer",
          "field": "Name",
          "operator": "LIKE",
          "value": "VIP%"
        }
      ]
    ],
    "Static Fields": [
      "IR Number",
      "IR Type",
      "Title",
      "Status",
      "Severity",
      "Stage",
      "Priority",
      "Disposition",
      "Tags",
      "Owner",
      "Creator",
      "Timezone",
      "Date Created",
      "Date Modified",
      "Playbook",
      "Description",
      "Conclusion",
      "Investigation Team",
      "Linked Incidents",
      "Incident Raw Data",
      "Event Raw Data"
    ],
    "Dynamic Fields": {
      "Incident Owner": [
        "Owner Last Update Time",
        "Time Spend"
      ],
      "Customer": [
        "Name",
        "Country"
      ]
    },
    "Start Time": "2019-03-26 00:00:00",
    "End Time": "2021-12-31 10:15:00",
    "Output Format": 2,
    "Page Index": 0,
    "Page Size": 100
  }
}

SAMPLE DATA FOR VERSION 16.8+

CODE
{
  "Username": "Admin",
  "Site": "Security Operations",
  "CommandParams": {
    "Filter": [
      [
        {
          "field": "Status",
          "operator": "=",
          "value": "Open"
        },
        {
          "field": "Severity",
          "operator": "=",
          "value": "High"
        }
      ],
      [
        {
          "section": "Customer",
          "field": "Name",
          "operator": "LIKE",
          "value": "VIP%"
        }
      ]
    ],
    "Static Fields": [
      "Incident No.",
      "Incident Type",
      "Title",
      "Status",
      "Severity",
      "Stage",
      "Priority",
      "Disposition",
      "Tags",
      "Owner",
      "Creator",
      "Closed by",
      "Time Zone",
      "Date Created",
      "Date Modified",
      "Date Closed",
      "Playbook",
      "Description",
      "Conclusion",
      "Investigation Team",
      "Linked Incidents",
      "Incident Raw Data",
      "Custom Field"
    ],
    "Dynamic Fields": {
      "Incident Owner": [
        "Owner Last Update Time",
        "Time Spend"
      ],
      "Customer": [
        "Name",
        "Country"
      ]
    },
    "Start Time": "2019-03-26 00:00:00",
    "End Time": "2021-12-31 10:15:00",
    "Output Format": 2,
    "Page Index": 0,
    "Page Size": 100
  }
}

Response

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

JSON Object

The raw data from the API request.

Sample Response

BEFORE VERSION 16.8

JSON
{
    "error": "",
    "keyFields": "{
      "Pagination" : {
          "PageIndex": 0,
          "PageSize": 100,
          "TotalPages": 10
      }
    }",
    "returnData": "Successful",
    "rawData": {
      "incidents": [
          {
              "IR Number": "20211222-3",
              "IR Type": "Playbook - DLP",
              "Title": "222222222",
              "Status": "Open",
              "Severity": "High",
              "Stage": "Data Aggregation Stage",
              "Priority": "1 - Medium",
              "Disposition": "N/A",
              "Tags": "",
              "Owner": "admin user",
              "Creator": "admin",
              "Timezone": "PST",
              "Date Created": "2019-04-08 09:17:32",
              "Date Modified": "2019-04-09 11:31:30",
              "Playbook": "Endpoint Protection - Unauthorized Access",
              "Description": "",
              "Conclusion": "",
              "Investigation Team": "",
              "Linked Incidents": "",
              "Incident Raw Data": "",
              "Event Raw Data": "",
              "Customer - Name": "VIP_Mary",
              "Customer - Country": "France",
              "Incident Owner - Owner Last Update Time": null,
              "Incident Owner - Time Spend": null
          },
          {
              "IR Number": "20211222-4",
              "IR Type": "Playbook - DLP",
              "Title": "",
              "Status": "Open",
              "Severity": "High",
              "Stage": "Data Aggregation Stage",
              "Priority": "1 - Medium",
              "Disposition": "N/A",
              "Tags": "",
              "Owner": "admin user",
              "Creator": "admin",
              "Timezone": "PST",
              "Date Created": "2021-12-22 15:14:26",
              "Date Modified": "2021-12-22 15:51:56",
              "Playbook": "Endpoint Protection - Unauthorized Access",
              "Description": "",
              "Conclusion": "",
              "Investigation Team": "",
              "Linked Incidents": "",
              "Incident Raw Data": "",
              "Event Raw Data": "",
              "Customer - Name": "VIP_Robert",
              "Customer - Country": "Canada",
              "Incident Owner - Owner Last Update Time": null,
              "Incident Owner - Time Spend": null
          }
      ]
    }
}

VERSION 16.8+

CODE
{
    "error": "",
    "keyFields": "{
      "Pagination" : {
          "PageIndex": 0,
          "PageSize": 100,
          "TotalPages": 10
      }
    }",
    "returnData": "Successful",
    "rawData": {
      "incidents": [
          {
              "IR Number": "20211222-3",
              "IR Type": "Playbook - DLP",
              "Title": "222222222",
              "Status": "Open",
              "Severity": "High",
              "Stage": "Data Aggregation Stage",
              "Priority": "1 - Medium",
              "Disposition": "N/A",
              "Tags": "",
              "Owner": "admin user",
              "Creator": "admin",
              "Timezone": "PST",
              "Date Created": "2019-04-08 09:17:32",
              "Date Modified": "2019-04-09 11:31:30",
              "Playbook": "Endpoint Protection - Unauthorized Access",
              "Description": "",
              "Conclusion": "",
              "Investigation Team": "",
              "Linked Incidents": "",
              "Incident Raw Data": "",
              "Event Raw Data": "",
              "Customer - Name": "VIP_Mary",
              "Customer - Country": "France",
              "Incident Owner - Owner Last Update Time": null,
              "Incident Owner - Time Spend": null
          },
          {
              "IR Number": "20211222-4",
              "IR Type": "Playbook - DLP",
              "Title": "",
              "Status": "Open",
              "Severity": "High",
              "Stage": "Data Aggregation Stage",
              "Priority": "1 - Medium",
              "Disposition": "N/A",
              "Tags": "",
              "Owner": "admin user",
              "Creator": "admin",
              "Timezone": "PST",
              "Date Created": "2021-12-22 15:14:26",
              "Date Modified": "2021-12-22 15:51:56",
              "Playbook": "Endpoint Protection - Unauthorized Access",
              "Description": "",
              "Conclusion": "",
              "Investigation Team": "",
              "Linked Incidents": "",
              "Incident Raw Data": "",
              "Event Raw Data": "",
              "Customer - Name": "VIP_Robert",
              "Customer - Country": "Canada",
              "Incident Owner - Owner Last Update Time": null,
              "Incident Owner - Time Spend": null
          }
      ]
    }
}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.