Darktrace

Overview

Darktrace offers intelligent, automatic threat detection and response, powered by self-learning AI that can catch every potential threat.

D3 SOAR is providing REST operations to function with the Darktrace.

For example, you can use Darktrace Integration to monitor your digital infrastructure and take intelligent preventive action to stop any threats from escalating into a crisis.

Darktrace Integration is available for use in:

D3 SOAR	V14.0.19.0+
Category	SIEM
Deployment Options	Option II, Option IV

Connection

To connect to Darktrace from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Server URL	The Darktrace server URL.	https://usw1-***-01.cloud.darktrace.com
Private Token	The private token for authentication with Darktrace.	YOUR_PRIVATE_TOKEN
Public Token	The public token for authentication with Darktrace.	YOUR_API_TOKEN

Configuring Darktrace to Work with D3 SOAR

Creating the API token requires access to the Darktrace Threat Visualizer interface and a user account with appropriate permissions to access and modify the System Config page.

Navigate to the System Config page on the Threat Visualizer of the appliance you wish to request data from. Select “Settings” from the left-hand menu.
Locate the “API Token” subsection and click “New”.
Two values will be displayed, a Public and Private token, the Private token will not be displayed again.
Both tokens are required to establish an integration connection in D3 SOAR.

Configuring D3 SOAR to Work with Darktrace

Log in to D3 SOAR.
Find the Darktrace integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Darktrace in the search box to find the integration, then click it to select it.
4. Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Darktrace.
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add your desired description for the connection.
6. Configure User Permissions: Defines which users have access to the connection.
7. Active: Check the tick box to ensure the connection is available for use.
8. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input your domain level Server URL.
  2. Input your Public Token.
  3. Input your Private Token.
9. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
10. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
  To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
Test the connection.
1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

Darktrace includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Darktrace Enterprise Immune System API, please refer to the Darktrace Enterprise Immune System API reference.

Note for Time-related parameters

The input format of time-related parameters may vary based on your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:

Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose your desired date and time format.

After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.

Acknowledge

Acknowledges the specified model breaches.

Reader Note

The parameter Breach IDs is required to run this command.

Run the Search Breaches command to obtain Breach IDs. Breach IDs can be found from the returned raw data at the path $[*].pbid.
Breaches can either be acknowledged or unacknowledged, but not be both. You may check the breach IDs’ acknowledge status from the response data of the Fetch Event command, at the JSON path $.[*].acknowledge. You can acknowledge the breaches that are unacknowledged (“false”). The breach IDs are returned under the key “pbid”.

Input

Input Parameter

Required/Optional

Description

Example

Breach IDs

Required

The ID(s) of the model breach(es) to acknowledge. Breach IDs can be obtained using the Search Breaches command.

[

***

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "response": "SUCCESS"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Responses": [
        "SUCCESS"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Acknowledge failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: ERROR

Error Sample Data

Acknowledge failed.

Status Code: 400.

Message: ERROR

Add Comments

Adds a comment to the specified breaches.

Reader Note

The parameter Breach IDs is required to run this command.

Run the Search Breaches command to obtain Breach IDs. Breach IDs can be found from the returned raw data at the path $[*].pbid.

Input

Input Parameter

Required/Optional

Description

Example

Breach IDs

Required

The ID(s) of the model breach(es) to add a comment. Breach IDs can be obtained using the Search Breaches command.

[

***

]

Comment

Required

The comment text to add.

Hello World!!!

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "response": "SUCCESS"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Responses": [
        "SUCCESS"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Add Comments failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API SIGNATURE ERROR.

Error Sample Data

Add Comments failed.

Status Code: 400.

Message: API SIGNATURE ERROR.

Create Actions

Creates manual Darktrace RESPOND/Network actions from Darktrace Threat Visualizer 6.

Reader Note

The parameter Device IDs is required to run this command.

Run the List Devices command to obtain Device IDs. Device IDs can be found from the returned raw data at the path $[*].did.

Input

Input Parameter	Required/Optional	Description	Example
Device IDs	Required	The IDs of the devices modeled in the Darktrace system on which to take action. Device IDs can be obtained using the List Devices command.	[ 20 ]
Action	Required	The action to take on the specified devices. Available action options are Block Matching Connections(connection), Enforce pattern of life(pol), Enforce group pattern of life(gpol), Quarantine device(quarantine), Block all outgoing traffic(quarantineOutgoing) and Block all incoming traffic(quarantineIncoming).	Block Matching Connections
Duration	Optional	The duration of the action in seconds. If this parameter is not defined, the default duration is 60 seconds.	30
Reason	Optional	The purpose of the action.	Test
Connections	Optional	The connection pairs to block against. Inputs are in Array format with available fields src, dst and port. Please note, this parameter is valid only for the Action parameter choose to Connections. Each connection pair must include src and dst fields, and port field is optional. Src can be an IP or hostname of an endpoint to block connections from. Dst can be an IP or hostname of an endpoint to block connections to. Port is an optional port for dst.	[ { "src": "10.10.10.10", "dst": "8.8.8.9", "port": 443 } ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "did": 20,
        "code": **
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "ActionIDs": [
        ***
    ]
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Created Actions Count

1

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Create Actions failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Device ID Not found.

Error Sample Data

Create Actions failed.

Status Code: 404

Message: Device ID Not found.

Create PCAP

Creates new PCAP files.

Input

Input Parameter	Required/Optional	Description	Example
Source IP	Required	The source IP of connections in the packet capture.	1.1.1.1
Source Port	Optional	The port number for the source IP.	443
Destination IP	Optional	The destination IP of connections in the packet capture.	8.8.8.8
Destination Port	Optional	The port number for the destination IP.	80
Start Time	Required	The start time for the packet capture in UTC time. Please note, the maximum timeframe for PCAP creation between Start Time and End Time is 30 minutes.	2023-01-24 00:00
End Time	Required	The end time for the packet capture in UTC time. Please note, the maximum timeframe for PCAP creation between Start Time and End Time is 30 minutes.	2023-01-25 00:00
Protocol	Optional	The layer 3 protocol to be specified. Accepts “TCP” or “UDP”. Please note, to use the protocol filter, the Destination IP and Destination port must be specified.	TCP

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "tmqid": **,
    "startTime": 1679604024,
    "filename": "/pcaps/***.pcap",
    "index": "***",
    "l3proto": "***",
    "ip1": "1.2.3.4",
    "port1": 443,
    "ip2": "8.8.8.8",
    "port2": 80,
    "start": 1598258880,
    "end": 1598258940,
    "state": "pending"
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "TmQueryID": *,
    "SourceIP": "1.2.3.4",
    "DestinationIP": "8.8.8.8",
    "State": "pending"
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

tmqid	**
startTime	1679604024
filename	/pcaps/***.pcap
index	connection4
l3proto	tcp
ip1	1.2.3.4
port1	443
ip2	8.8.8.8
port2	80
start	1598258880
end	1598258940
state	pending

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Create PCAP failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid Source IP.

Error Sample Data

Create PCAP failed.

Status Code: 403.

Message: Invalid Source IP.

Get Enumerated Types

Returns the corresponding string values for numeric codes (enumerated types) that are used in many API responses.

Input

Input Parameter	Required/Optional	Description	Example
Enumerated Types	Optional	The enumerated type to retrieve string values for numeric codes. The valid enumerated types are applicationprotocols, protocols, countries, destinationdevicetypes, sourcedevicetypes and vendors. If this parameter is not defined, all enumerated types will be returned.	[ "protocols", "countries" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "code": "0",
        "name": "Unknown",
        "enumeratedType": "protocols"
    },
    {
        "code": "1",
        "name": "ICMP",
        "enumeratedType": "protocols"
    },
    {
        "code": "2",
        "name": "IGMP",
        "enumeratedType": "protocols"
    },
    {
        "code": "6",
        "name": "TCP",
        "enumeratedType": "protocols"
    },
    {
        "code": "17",
        "name": "UDP",
        "enumeratedType": "protocols"
    },
    {
        "code": "41",
        "name": "IPv6",
        "enumeratedType": "protocols"
    },
    {
        "code": "45",
        "name": "IDRP",
        "enumeratedType": "protocols"
    },
    {
        "code": "47",
        "name": "GRE",
        "enumeratedType": "protocols"
    },
    {
        "code": "50",
        "name": "ESP",
        "enumeratedType": "protocols"
    },
    {
        "code": "51",
        "name": "AH",
        "enumeratedType": "protocols"
    },
    {
        "code": "58",
        "name": "IPv6-ICMP",
        "enumeratedType": "protocols"
    },
    {
        "code": "10000",
        "name": "ICS/Other",
        "enumeratedType": "protocols"
    },
    {
        "code": "Other",
        "name": "Other",
        "enumeratedType": "protocols"
    }
]

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Enumerated Types failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API SIGNATURE ERROR.

Error Sample Data

Get Enumerated Types failed.

Status Code: 400.

Message: API SIGNATURE ERROR.

Fetch Event

Returns events (model breaches) based on the specified criteria. Note: Events beyond one year cannot be returned.

Reader Note

The syntax for the Search Condition input parameter is <field1>=<value1>&<field2>=<value2>.... The available input filter fields are did, minscore, pid, pbid and uuid. & is the AND operator, which is the only supported operator for input.

If no parameters are defined, up to 100 events within a year will be returned.
If only Start Time and End Time parameters are defined, and assuming that the input time range is valid, all events within the time range will be returned.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Optional	The start time of the time range to fetch events in UTC time. Note: Both Start Time and End Time must be defined for the input value of this command to be effective. Otherwise, breaches within a year will return.	2023-01-26 00:00
End Time	Optional	The end time of the time range to fetch events in UTC time format. Note: Both Start Time and End Time must be defined for the input value of this command to be effective. Otherwise, breaches within a year will return.	2023-01-27 00:00
Number of Event(s) Fetched	Optional	The number of events to return. Note: If this parameter is not defined, but the Start Time and End time parameters are, all breaches between the specified time range will be returned. If all three parameters are not defined, the default value of 100 for this parameter will be used.	10
Search Condition	Optional	The search condition to filter fetched events. The syntax for the Search Condition input parameter is <field1>=<value1>&<field2>=<value2>.... The available input filter fields are did, minscore, pid, pbid and uuid. Note: Do not input time range fields (i.e. starttime, endtime, from and to). They will be overridden by the Start Time and End Time parameters.	did=33&minscore=0.5
Tolerance Scope	Optional	The tolerance scope (the default value is 10) in minutes of the query to fetch events between start and end time to avoid the loss of events. Events will be fetched between {Start Time - Tolerance Scope, End Time}.	0

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "acknowledged": false,
        "commentCount": 0,
        "pbid": ***,
        "time": 1664212389000,
        "creationTime": 1664212400000,
        "model": {
            "then": {
                "name": "Device::Threat Indicator",
                "pid": **,
                "phid": ***,
                "uuid": "***-***-***-***-***",
                "logic": {
                    "data": [
                        {
                            "cid": ***,
                            "weight": 1
                        },
                        {
                            "cid": ***,
                            "weight": 1
                        },
                        {
                            "cid": ***,
                            "weight": 1
                        }
                    ],
                    "targetScore": 1,
                    "type": "weightedComponentList",
                    "version": 1
                },
                "throttle": ***,
                "sharedEndpoints": false,
                "actions": {
                    "alert": true,
                    "antigena": {},
                    "breach": true,
                    "model": true,
                    "setPriority": false,
                    "setTag": false,
                    "setType": false,
                    "tagTTL": ***
                },
                "tags": [
                    "",
                    "Requires Configuration"
                ],
                "interval": 1,
                "delay": 0,
                "sequenced": false,
                "active": true,
                "modified": "2022-06-15 12:01:36",
                "activeTimes": {
                    "devices": {},
                    "tags": {},
                    "type": "exclusions",
                    "version": 2
                },
                "autoUpdatable": true,
                "autoUpdate": true,
                "autoSuppress": true,
                "description": "A device has visited an external location that has been identified by an Indicator added to the watchlists or via TAXII.\\n\\nAction: Investigate devices network behaviours paying particular attention to the domains or IP's being highlighted. Verify the indicator is a true malicious indicator.",
                "behaviour": "decreasing",
                "created": {
                    "by": "System"
                },
                "edited": {
                    "by": "System"
                },
                "version": 39,
                "priority": 5,
                "category": "Critical",
                "compliance": false
            },
            "now": {
                "name": "Device::Threat Indicator",
                "pid": ***,
                "phid": ***,
                "uuid": "***-***-***-***-***",
                "logic": {
                    "data": [
                        {
                            "cid": ***,
                            "weight": 1
                        },
                        {
                            "cid": ***,
                            "weight": 1
                        },
                        {
                            "cid": ***,
                            "weight": 1
                        }
                    ],
                    "targetScore": 1,
                    "type": "weightedComponentList",
                    "version": 1
                },
                "throttle": ***,
                "sharedEndpoints": false,
                "actions": {
                    "alert": true,
                    "antigena": {},
                    "breach": true,
                    "model": true,
                    "setPriority": false,
                    "setTag": false,
                    "setType": false,
                    "tagTTL": 604800
                },
                "tags": [
                    "",
                    "Requires Configuration"
                ],
                "interval": 1,
                "delay": 0,
                "sequenced": false,
                "active": true,
                "modified": "2022-06-15 12:01:36",
                "activeTimes": {
                    "devices": {},
                    "tags": {},
                    "type": "exclusions",
                    "version": 2
                },
                "autoUpdatable": true,
                "autoUpdate": true,
                "autoSuppress": true,
                "description": "A device has visited an external location that has been identified by an Indicator added to the watchlists or via TAXII.\\n\\nAction: Investigate devices network behaviours paying particular attention to the domains or IP's being highlighted. Verify the indicator is a true malicious indicator.",
                "behaviour": "decreasing",
                "created": {
                    "by": "System"
                },
                "edited": {
                    "by": "System"
                },
                "message": "Updated Watched endpoint source regex to exclude 'Attack Surface Management'",
                "version": 39,
                "priority": 5,
                "category": "Critical",
                "compliance": false
            }
        },
        "triggeredComponents": [
            {
                "time": 1664212388000,
                "cbid": **,
                "cid": ***,
                "chid": ***,
                "size": 1,
                "threshold": 0,
                "interval": ***,
                "logic": {
                    "data": {
                        "left": "A",
                        "operator": "AND",
                        "right": {
                            "left": "F",
                            "operator": "AND",
                            "right": {
                                "left": "G",
                                "operator": "AND",
                                "right": {
                                    "left": "H",
                                    "operator": "AND",
                                    "right": {
                                        "left": "I",
                                        "operator": "AND",
                                        "right": {
                                            "left": "J",
                                            "operator": "AND",
                                            "right": "K"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "version": "v0.1"
                },
                "metric": {
                    "mlid": ***,
                    "name": "***",
                    "label": "Watched Domain"
                },
                "triggeredFilters": [
                    {
                        "cfid": **,
                        "id": "A",
                        "filterType": "Watched endpoint source",
                        "arguments": {
                            "value": "^(\\_?Darktrace.*|Attack Surface Management)"
                        },
                        "comparatorType": "does not match regular expression",
                        "trigger": {
                            "value": "ThreatIntel"
                        }
                    },
                    {
                        "cfid": **,
                        "id": "F",
                        "filterType": "Watched endpoint source",
                        "arguments": {
                            "value": ".+"
                        },
                        "comparatorType": "matches regular expression",
                        "trigger": {
                            "value": "ThreatIntel"
                        }
                    },
                    {
                        "cfid": ***,
                        "id": "G",
                        "filterType": "Watched endpoint source",
                        "arguments": {
                            "value": "Default"
                        },
                        "comparatorType": "does not match",
                        "trigger": {
                            "value": "ThreatIntel"
                        }
                    },
                    {
                        "cfid": ***,
                        "id": "H",
                        "filterType": "Tagged internal source",
                        "arguments": {
                            "value": 4
                        },
                        "comparatorType": "does not have tag",
                        "trigger": {
                            "value": "4",
                            "tag": {
                                "tid": 4,
                                "expiry": 0,
                                "thid": 4,
                                "name": "Security Device",
                                "restricted": false,
                                "data": {
                                    "auto": false,
                                    "color": 55,
                                    "description": "",
                                    "visibility": "Public"
                                },
                                "isReferenced": true
                            }
                        }
                    },
                    {
                        "cfid": **,
                        "id": "I",
                        "filterType": "Internal source device type",
                        "arguments": {
                            "value": "12"
                        },
                        "comparatorType": "is not",
                        "trigger": {
                            "value": "6"
                        }
                    },
                    {
                        "cfid": ***,
                        "id": "J",
                        "filterType": "Tagged internal source",
                        "arguments": {
                            "value": ***
                        },
                        "comparatorType": "does not have tag",
                        "trigger": {
                            "value": "***",
                            "tag": {
                                "tid": ***,
                                "expiry": 0,
                                "thid": ***,
                                "name": "DNS Server",
                                "restricted": false,
                                "data": {
                                    "auto": false,
                                    "color": 112,
                                    "description": "Devices receiving and making DNS queries",
                                    "visibility": "Public"
                                },
                                "isReferenced": true
                            }
                        }
                    },
                    {
                        "cfid": ***,
                        "id": "K",
                        "filterType": "Direction",
                        "arguments": {
                            "value": "out"
                        },
                        "comparatorType": "is",
                        "trigger": {
                            "value": "out"
                        }
                    },
                    {
                        "cfid": ***,
                        "id": "**",
                        "filterType": "Age of destination",
                        "arguments": {},
                        "comparatorType": "display",
                        "trigger": {
                            "value": "**"
                        }
                    },
                    {
                        "cfid": ***,
                        "id": "***",
                        "filterType": "Destination IP",
                        "arguments": {},
                        "comparatorType": "display",
                        "trigger": {
                            "value": "1.2.3.4"
                        }
                    },
                    {
                        "cfid": ***,
                        "id": "***",
                        "filterType": "ASN",
                        "arguments": {},
                        "comparatorType": "display",
                        "trigger": {
                            "value": ""
                        }
                    },
                    {
                        "cfid": ***,
                        "id": "***",
                        "filterType": "Destination port",
                        "arguments": {},
                        "comparatorType": "display",
                        "trigger": {
                            "value": "***"
                        }
                    },
                    {
                        "cfid": ***,
                        "id": "***",
                        "filterType": "Watched endpoint source",
                        "arguments": {},
                        "comparatorType": "display",
                        "trigger": {
                            "value": "ThreatIntel"
                        }
                    },
                    {
                        "cfid": ***,
                        "id": "***",
                        "filterType": "Message",
                        "arguments": {},
                        "comparatorType": "display",
                        "trigger": {
                            "value": "google.com"
                        }
                    }
                ]
            }
        ],
        "score": 0.797,
        "device": {
            "did": ***,
            "macaddress": "00:c0:ae:ba:00:00",
            "vendor": "",
            "ip": "1.2.3.4",
            "ips": [
                {
                    "ip": "1.2.3.4",
                    "timems": 1664312400000,
                    "time": "2022-09-27 21:00:00",
                    "sid": 3
                }
            ],
            "sid": 3,
            "hostname": "***",
            "firstSeen": 1653658719000,
            "lastSeen": 1664315065000,
            "devicelabel": "testing label",
            "typename": "desktop",
            "typelabel": "Desktop",
            "credentials": [
                "vagrant"
            ]
        }
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "BreachIDs": [
        ***
    ],
    "Time": [
        "2022-09-26T17:13:09Z"
    ],
    "CreationTime": [
        "2022-09-26T17:13:20Z"
    ],
    "Scores": [
        0.797
    ],
    "DeviceIDs": [
        ***
    ],
    "DeviceIPs": [
        "1.2.3.4"
    ],
    "HostNames": [
        "***"
    ],
    "ModelNames": [
        "Device::Threat Indicator"
    ],
    "ModelIDs": [
        ***
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

ACKNOWLEDGED	COMMENTCOUNT	PBID	TIME	CREATIONTIME	MODEL	TRIGGEREDCOMPONENTS	SCORE	DEVICE
False	0	**	1664212389000	1664212400000			0.797

Fetch Event Field Mapping

Please note that Fetch Event commands require event field mapping. Field mapping plays a key role in the data normalization process part of the event pipeline. Field mapping converts the original data fields from the different providers to the D3 fields which are standardized by the D3 Model. Please refer to Event and Incident Intake Field Mapping for details.

If you require a custom field mapping, click +Add Field to add a custom field mapping. You may also remove built-in field mappings by clicking x. Please note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.

As a system integration, the Darktrace integration has some pre-configured field mappings for default field mapping.

Default Event Source
The Default Event Source is the default set of field mappings that are applied when this fetch event command is executed. For out-of-the-box integrations, you will find a set of field mapping provided by the system. Default event source provides field mappings for common fields from fetched events . The default event source has a “Main Event JSON Path” (i.e., $) that is used to extract a batch of events from the response raw data. Click Edit Event Source to view the “Main Event JSON Path”.
- Main Event JSON Path: $
  The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...’]) should be used to separate child elements in JSON arrays.
  For example, the root node of a JSON Path is . The child node denoting the Metric Name field would be .triggeredComponents[*].metric.label. Putting it together, the JSON Path expression to extract the Metric Name is $[*].triggeredComponents[*].metric.label.

The pre-configured field mappings are detailed below:

Field Name	Source Field
Unique Event Key	.pbid
Event Type	.model.now.name
Start Time	.time
Description	.model.now.description
Score	.score
Device	.device.hostname
Device IP Address	.device.ip
Device Mac Address	.device.macaddress
Device category	.device.typelabel
Device ID	.device.did
Acknowledged	.acknowledged
Creation Time	.creationTime
Severity	.model.now.category
Priority	.model.now.priority
Metric Logic ID	.triggeredComponents[*].metric.mlid
Metric Name	.triggeredComponents[*].metric.label

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Event failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API SIGNATURE ERROR.

Error Sample Data

Fetch Event failed.

Status Code: 400.

Message: API SIGNATURE ERROR.

List Filter Types

Returns all internal Darktrace filters used in the Model Editor, their filter types (e.g. boolean and numeric) and the available comparators.

Input

N/A

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "filtertype": "Provider",
        "valuetype": "string",
        "comparators": [
            "matches",
            "does not match",
            "contains",
            "does not contain",
            "matches regular expression",
            "does not match regular expression",
            "is longer than",
            "is shorter than"
        ]
    },
    {
        "filtertype": "Description",
        "valuetype": "string",
        "comparators": [
            "matches",
            "does not match",
            "contains",
            "does not contain",
            "matches regular expression",
            "does not match regular expression",
            "is longer than",
            "is shorter than"
        ]
    },
    {
        "filtertype": "Connection Hostnames",
        "valuetype": "string",
        "comparators": [
            "matches",
            "does not match",
            "contains",
            "does not contain",
            "matches regular expression",
            "does not match regular expression",
            "is longer than",
            "is shorter than"
        ]
    }
]

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Filter Types failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API DATE ERROR.

Error Sample Data

List Filter Types failed.

Status Code: 400.

Message: API DATE ERROR.

Get Breaches

Returns information from the specified model breaches.

Reader Note

The parameter Breach IDs is required to run this command.

Run the Search Breaches command to obtain Breach IDs. Breach IDs can be found from the returned raw data at the path $[*].pbid.

Both acknowledged and unacknowledged breaches will be returned, so the acknowledged breaches can also be obtained from this command.

Input

Input Parameter

Required/Optional

Description

Example

Breach IDs

Required

The ID(s) of the model breach(es) to retrieve information from. Breach IDs can be obtained using the Search Breaches command.

[

***

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "commentCount": 0,
        "pbid": ***,
        "time": 1664212389000,
        "creationTime": 1664212400000,
        "model": {
            "then": {
                "name": "Device::Threat Indicator",
                "pid": ***,
                "phid": ***,
                "uuid": "***-***-***-***-***",
                "logic": {
                    "data": [
                        {
                            "cid": ***,
                            "weight": 1
                        },
                        {
                            "cid": ***,
                            "weight": 1
                        },
                        {
                            "cid": ***,
                            "weight": 1
                        }
                    ],
                    "targetScore": 1,
                    "type": "weightedComponentList",
                    "version": 1
                },
                "throttle": **,
                "sharedEndpoints": false,
                "actions": {
                    "alert": true,
                    "antigena": {},
                    "breach": true,
                    "model": true,
                    "setPriority": false,
                    "setTag": false,
                    "setType": false,
                    "tagTTL": ***
                },
                "tags": [
                    "",
                    "Requires Configuration"
                ],
                "interval": 1,
                "delay": 0,
                "sequenced": false,
                "active": true,
                "modified": "2022-06-15 12:01:36",
                "activeTimes": {
                    "devices": {},
                    "tags": {},
                    "type": "exclusions",
                    "version": 2
                },
                "autoUpdatable": true,
                "autoUpdate": true,
                "autoSuppress": true,
                "description": "A device has visited an external location that has been identified by an Indicator added to the watchlists or via TAXII.\\n\\nAction: Investigate devices network behaviours paying particular attention to the domains or IP's being highlighted. Verify the indicator is a true malicious indicator.",
                "behaviour": "decreasing",
                "created": {
                    "by": "System"
                },
                "edited": {
                    "by": "System"
                },
                "version": 39,
                "priority": 5,
                "category": "Critical",
                "compliance": false
            },
            "now": {
                "name": "Device::Threat Indicator",
                "pid": ***,
                "phid": ***,
                "uuid": "***-***-***-***-***",
                "logic": {
                    "data": [
                        {
                            "cid": ***,
                            "weight": 1
                        },
                        {
                            "cid": ***,
                            "weight": 1
                        },
                        {
                            "cid": ***,
                            "weight": 1
                        }
                    ],
                    "targetScore": 1,
                    "type": "weightedComponentList",
                    "version": 1
                },
                "throttle": ***,
                "sharedEndpoints": false,
                "actions": {
                    "alert": true,
                    "antigena": {},
                    "breach": true,
                    "model": true,
                    "setPriority": false,
                    "setTag": false,
                    "setType": false,
                    "tagTTL": ***
                },
                "tags": [
                    "",
                    "Requires Configuration"
                ],
                "interval": 1,
                "delay": 0,
                "sequenced": false,
                "active": true,
                "modified": "2022-06-15 12:01:36",
                "activeTimes": {
                    "devices": {},
                    "tags": {},
                    "type": "exclusions",
                    "version": 2
                },
                "autoUpdatable": true,
                "autoUpdate": true,
                "autoSuppress": true,
                "description": "A device has visited an external location that has been identified by an Indicator added to the watchlists or via TAXII.\\n\\nAction: Investigate devices network behaviours paying particular attention to the domains or IP's being highlighted. Verify the indicator is a true malicious indicator.",
                "behaviour": "decreasing",
                "created": {
                    "by": "System"
                },
                "edited": {
                    "by": "System"
                },
                "message": "Updated Watched endpoint source regex to exclude 'Attack Surface Management'",
                "version": 39,
                "priority": 5,
                "category": "Critical",
                "compliance": false
            }
        },
        "triggeredComponents": [
            {
                "time": 1664212388000,
                "cbid": **,
                "cid": **,
                "chid": ***,
                "size": 1,
                "threshold": 0,
                "interval": **,
                "logic": {
                    "data": {
                        "left": "A",
                        "operator": "AND",
                        "right": {
                            "left": "F",
                            "operator": "AND",
                            "right": {
                                "left": "G",
                                "operator": "AND",
                                "right": {
                                    "left": "H",
                                    "operator": "AND",
                                    "right": {
                                        "left": "I",
                                        "operator": "AND",
                                        "right": {
                                            "left": "J",
                                            "operator": "AND",
                                            "right": "K"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "version": "v0.1"
                },
                "metric": {
                    "mlid": **,
                    "name": "**",
                    "label": "Watched Domain"
                },
                "triggeredFilters": [
                    {
                        "cfid": ***,
                        "id": "A",
                        "filterType": "Watched endpoint source",
                        "arguments": {
                            "value": "^(\\_?Darktrace.*|Attack Surface Management)"
                        },
                        "comparatorType": "does not match regular expression",
                        "trigger": {
                            "value": "ThreatIntel"
                        }
                    },
                    {
                        "cfid": ***,
                        "id": "F",
                        "filterType": "Watched endpoint source",
                        "arguments": {
                            "value": ".+"
                        },
                        "comparatorType": "matches regular expression",
                        "trigger": {
                            "value": "ThreatIntel"
                        }
                    },
                    {
                        "cfid": ***,
                        "id": "G",
                        "filterType": "Watched endpoint source",
                        "arguments": {
                            "value": "Default"
                        },
                        "comparatorType": "does not match",
                        "trigger": {
                            "value": "ThreatIntel"
                        }
                    },
                    {
                        "cfid": **,
                        "id": "H",
                        "filterType": "Tagged internal source",
                        "arguments": {
                            "value": 4
                        },
                        "comparatorType": "does not have tag",
                        "trigger": {
                            "value": "4",
                            "tag": {
                                "tid": 4,
                                "expiry": 0,
                                "thid": 4,
                                "name": "Security Device",
                                "restricted": false,
                                "data": {
                                    "auto": false,
                                    "color": 55,
                                    "description": "",
                                    "visibility": "Public"
                                },
                                "isReferenced": true
                            }
                        }
                    },
                    {
                        "cfid": **,
                        "id": "I",
                        "filterType": "Internal source device type",
                        "arguments": {
                            "value": "12"
                        },
                        "comparatorType": "is not",
                        "trigger": {
                            "value": "6"
                        }
                    },
                    {
                        "cfid": ***,
                        "id": "J",
                        "filterType": "Tagged internal source",
                        "arguments": {
                            "value": 18
                        },
                        "comparatorType": "does not have tag",
                        "trigger": {
                            "value": "18",
                            "tag": {
                                "tid": 18,
                                "expiry": 0,
                                "thid": 18,
                                "name": "DNS Server",
                                "restricted": false,
                                "data": {
                                    "auto": false,
                                    "color": 112,
                                    "description": "Devices receiving and making DNS queries",
                                    "visibility": "Public"
                                },
                                "isReferenced": true
                            }
                        }
                    },
                    {
                        "cfid": **,
                        "id": "K",
                        "filterType": "Direction",
                        "arguments": {
                            "value": "out"
                        },
                        "comparatorType": "is",
                        "trigger": {
                            "value": "out"
                        }
                    },
                    {
                        "cfid": **,
                        "id": "d1",
                        "filterType": "Age of destination",
                        "arguments": {},
                        "comparatorType": "display",
                        "trigger": {
                            "value": "14542435"
                        }
                    },
                    {
                        "cfid": **,
                        "id": "d3",
                        "filterType": "Destination IP",
                        "arguments": {},
                        "comparatorType": "display",
                        "trigger": {
                            "value": "192.168.1.2"
                        }
                    },
                    {
                        "cfid": **,
                        "id": "d4",
                        "filterType": "ASN",
                        "arguments": {},
                        "comparatorType": "display",
                        "trigger": {
                            "value": ""
                        }
                    },
                    {
                        "cfid": **,
                        "id": "d5",
                        "filterType": "Destination port",
                        "arguments": {},
                        "comparatorType": "display",
                        "trigger": {
                            "value": "53"
                        }
                    },
                    {
                        "cfid": ***,
                        "id": "d7",
                        "filterType": "Watched endpoint source",
                        "arguments": {},
                        "comparatorType": "display",
                        "trigger": {
                            "value": "ThreatIntel"
                        }
                    },
                    {
                        "cfid": ***,
                        "id": "d8",
                        "filterType": "Message",
                        "arguments": {},
                        "comparatorType": "display",
                        "trigger": {
                            "value": "google.com"
                        }
                    }
                ]
            }
        ],
        "score": 0.797,
        "device": {
            "did": ***,
            "macaddress": "00:c0:ae:ba:00:00",
            "vendor": "",
            "ip": "1.2.3.4",
            "ips": [
                {
                    "ip": "1.2.3.4",
                    "timems": 1664312400000,
                    "time": "2022-09-27 21:00:00",
                    "sid": 3
                }
            ],
            "sid": ***,
            "hostname": "***",
            "firstSeen": 1653658719000,
            "lastSeen": 1664315967000,
            "devicelabel": "testing label",
            "typename": "desktop",
            "typelabel": "Desktop",
            "credentials": [
                "vagrant"
            ]
        }
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "BreachIDs": [
        ***
    ],
    "Time": [
        "2022-09-26T17:13:09Z"
    ],
    "CreationTime": [
        "2022-09-26T17:13:20Z"
    ],
    "Scores": [
        0.797
    ],
    "DeviceIDs": [
        ***
    ],
    "DeviceIPs": [
        "1.2.3.4"
    ],
    "HostNames": [
        "***"
    ],
    "ModelNames": [
        "Device::Threat Indicator"
    ],
    "ModelIDs": [
        ***
    ]
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

COMMENTCOUNT	PBID	TIME	CREATIONTIME	MODEL	TRIGGEREDCOMPONENTS	SCORE	DEVICE
0	***	1664212389000	1664212400000			0.797	{'did': *, 'macaddress': '00:c0:ae:ba:00:00', 'vendor': '', 'ip': '1.2.3.4', 'ips': [{'ip': '1.3.4.4', 'timems': 1664312400000, 'time': '2022-09-27 21:00:00', 'sid': }], 'sid': , 'hostname': '', 'firstSeen': 1653658719000, 'lastSeen': 1664315967000, 'devicelabel': 'testing label', 'typename': 'desktop', 'typelabel': 'Desktop', 'credentials': ['**']}

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Breaches failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace Enterprise Immune System portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API DATE ERROR.

Error Sample Data

Get Breaches failed.

Status Code: 400.

Message: API DATE ERROR.

Get Comments

Returns the current comments of the specified model breaches. The returned comments are sorted by comment time, in ascending order.

Reader Note

The parameter Breach IDs is required to run this command.

Run the Search Breaches command to obtain Breach IDs. Breach IDs can be found from the returned raw data at the path $[*].pbid.

Input

Input Parameter

Required/Optional

Description

Example

Breach IDs

Required

The ID(s) of the model breach(es) to retrieve comments. Breach IDs can be obtained using the Search Breaches command.

[

***

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "message": "Hello World",
        "username": "***",
        "time": 1664384254000,
        "pid": ***
    },
    {
        "message": "Hello World",
        "username": "***",
        "time": 1664384488000,
        "pid": ***
    },
    {
        "message": "Hello World1",
        "username": "***",
        "time": 1664384570000,
        "pid": ***
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Messages": [
        "Hello World"
    ],
    "CommentTime": [
        "2022-09-28T16:57:34Z"
    ],
    "UserNames": [
        "***"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Comments failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API DATE ERROR.

Error Sample Data

Get Comments failed.

Status Code: 400.

Message: API DATE ERROR.

Get Details

Returns a time-sorted list of connections and events for a device or entity (e.g. a SaaS credential). The request requires a device (returned under the “did” field of the raw data from the List Devices command), a model breach ID (returned under the “pbid” field of the raw data from the Search Breaches command) or a message field value (“msg”). You must specify at least one of three parameters - device ID, breach ID or message.

Alert

At least one of the Device ID, Breach ID and Message needs to be defined. The relationship between all input parameters is AND, meaning only connections and events matching all the input conditions will be returned. Otherwise, the command will run successfully with no returned results.

Reader Note

Device ID and Breach ID are optional parameters to run this command.
- Run the List Devices command to obtain Device ID. Device IDs can be found from the returned raw data at the path $[*].did.
- Run the Search Breaches command to obtain Breach ID. Breach IDs can be found from the returned raw data at the path $[*].pbid.
The format of the returned raw data may vary depending on the returned connections and events.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Optional	The start time of the time range to search for connections and events in UTC time.	2023-01-26 00:00
End Time	Optional	The end time of the time range to search for connections and events in UTC time.	2023-01-27 00:00
Device ID	Optional	The ID of the device to retrieve corresponding connections and events. Device IDs can be obtained using the List Devices command.	***
Breach ID	Optional	The ID of the model breach to retrieve corresponding connections and events. Breach IDs can be obtained using the Search Breaches command.	***
Message	Optional	The value of the message field in notice events to return details for. Typically used to specify user credential strings.	google.com
Event Type	Optional	The event type to retrieve details. The valid event types are Connection, Unusual Connection, New Connection, Notice, Device History, Model Breach, and Policy Breach. If not specified, all types of events will be returned.	3
Count	Optional	The number of items to return. If this parameter is not defined, but the Start Time and End time parameters are, all connections and events between the specified time range will be returned. If all three parameters are not defined, the default value of 200 will be used for this parameter.	10

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "time": "2022-09-26 17:13:09",
        "timems": 1664212389000,
        "pbid": ***,
        "pid": ***,
        "phid": ***,
        "eventType": "policybreach",
        "action": "policybreach",
        "creationTime": 1664212400000,
        "creationTimestamp": "2022-09-26 17:13:20",
        "name": "Device::Threat Indicator",
        "components": [
            ***,
            ***,
            ***
        ],
        "didRestrictions": [],
        "didExclusions": [],
        "throttle": ***,
        "sharedEndpoints": false,
        "interval": 1,
        "sequenced": false,
        "active": true,
        "retired": false,
        "instanceID": ***,
        "acknowledged": false,
        "state": "New",
        "score": 0.7969956,
        "commentCount": 5,
        "componentBreaches": [
            ***
        ],
        "componentBreachTimes": [
            1664212388000
        ],
        "devices": [
            ***
        ],
        "deviceLabels": [
            "testing label"
        ]
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "EventType": [
        "policybreach"
    ],
    "Time": [
        "2022-09-22 22:56:06"
    ],
    "CreationTime": [
        "2022-09-22 22:56:15"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Details failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API SIGNATURE ERROR.

Error Sample Data

Get Details failed.

Status Code: 400.

Message: API SIGNATURE ERROR.

Get Device Info

Returns the data used in the “Connections Data” view for the specified device(s) that can be accessed from the Threat Visualizer omnisearch. The data returned covers a 4 week period.

Reader Note

Device ID and Destination Device ID are required parameters to run this command.

Run the List Devices command to obtain Device ID and Destination Device ID. It can be found from the returned raw data at the path $[*].did.

Input

Input Parameter	Required/Optional	Description	Example
Device ID	Required	The ID of the device to retrieve info about. Device IDs can be obtained using the List Devices command.	[ ** ]
Data Type	Optional	The type of return data for either Connections, Data Size Out, or Data Size In. If this parameter is not defined, the default value is Connections.	Connections
Destination Device ID	Optional	The ID of the destination device modeled in the Darktrace system to restrict data to. You can get Device ID using the List Devices command. If this parameter is not defined, all external connectivity will be returned.	**
External Domain	Optional	Restricts external data to a particular domain name.	google.com
Port	Optional	Restricts returned connection data to the port specified.	***

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "deviceInfo": [
        {
            "did": ***,
            "similarityScore": 100,
            "domain": "google.com",
            "graphData": [],
            "info": {
                "totalUsed": 0,
                "totalServed": 0,
                "totalDevicesAndPorts": 0,
                "devicesAndPorts": [],
                "portsUsed": [],
                "portsServed": [],
                "devicesUsed": [],
                "devicesServed": []
            }
        }
    ]
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "DeviceIDs": [
        ***
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Devices Count

1

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Device Info failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Device ID not found.

Error Sample Data

Get Device Info failed.

Status Code: 404.

Message: Device ID not found.

Get Device Metric Data

Returns time series metrics data of a device. The default interval is 1 minute. If the Start Time and End Time parameters are not specified, the default time range is from 10 hours ago to the current time. It is suggested not to enter a large time range to avoid oversized return data.

Reader Note

Device ID and Metric Name are required parameters to run this command.

Run the List Devices command to obtain Device ID. Device IDs can be found from the returned raw data at the path $[*].did.
Run the List Metrics command to obtain Metric Name. Metric Name can be found from the returned raw data at the path $[*].name.

Input

Input Parameter	Required/Optional	Description	Example
Device ID	Required	The ID of the device to retrieve metrics data. Device IDs can be obtained using the List Devices command.	33
Metric Name	Required	The name of the metric to return. Metric names can be obtained using the List Metrics command.	[ "internalconnections", "connections" ]
Start Time	Optional	The start time of the time range to fetch metrics data in UTC time.	2023-01-28 00:00
End Time	Optional	The end time of the time range to fetch metrics data in UTC time.	2023-01-29 00:00

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "metric": "internalconnections",
        "data": [
            {
                "metric": "internalconnections",
                "time": "2022-09-29 00:00:00",
                "timems": 1664409600000,
                "size": 8,
                "in": 0,
                "out": 8
            },
            {
                "metric": "internalconnections",
                "time": "2022-09-29 00:01:00",
                "timems": 1664409660000,
                "size": 12,
                "in": 0,
                "out": 12
            },
            {
                "metric": "internalconnections",
                "time": "2022-09-29 00:02:00",
                "timems": 1664409720000,
                "size": 10,
                "in": 0,
                "out": 10
            },
            {
                "metric": "internalconnections",
                "time": "2022-09-29 00:03:00",
                "timems": 1664409780000,
                "size": 9,
                "in": 0,
                "out": 9
            },
            {
                "metric": "internalconnections",
                "time": "2022-09-29 00:04:00",
                "timems": 1664409840000,
                "size": 12,
                "in": 0,
                "out": 12
            }
        ]
    },
    {
        "metric": "connections",
        "data": [
            {
                "metric": "connections",
                "time": "2022-09-29 00:00:00",
                "timems": 1664409600000,
                "size": 11,
                "in": 0,
                "out": 11
            },
            {
                "metric": "connections",
                "time": "2022-09-29 00:01:00",
                "timems": 1664409660000,
                "size": 17,
                "in": 0,
                "out": 17
            },
            {
                "metric": "connections",
                "time": "2022-09-29 00:02:00",
                "timems": 1664409720000,
                "size": 13,
                "in": 0,
                "out": 13
            },
            {
                "metric": "connections",
                "time": "2022-09-29 00:03:00",
                "timems": 1664409780000,
                "size": 14,
                "in": 0,
                "out": 14
            },
            {
                "metric": "connections",
                "time": "2022-09-29 00:04:00",
                "timems": 1664409840000,
                "size": 15,
                "in": 0,
                "out": 15
            }
        ]
    }
]

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Device Metric Data failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API SIGNATURE ERROR.

Error Sample Data

Get Device Metric Data failed.

Status Code: 400.

Message: API SIGNATURE ERROR.

Get Device Summary

Returns contextual information for the specified device(s).

Reader Note

Device ID is a required parameter to run this command.

Run the List Devices command to obtain Device ID. Device IDs can be found from the returned raw data at the path $[*].did.

Input

Input Parameter

Required/Optional

Description

Example

Device ID

Required

The ID of the device to retrieve the summary. Device IDs can be obtained using the List Devices command.

[

**

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "data": [
        {
            "devices": {
                "id": **,
                "ip": "1.2.3.4",
                "ips": [
                    {
                        "ip": "1.2.3.4",
                        "timems": 1679594400000,
                        "time": "2023-03-23 18:00:00",
                        "sid": **
                    }
                ],
                "did": ***,
                "sid": ***,
                "time": 1646056755000,
                "endtime": 1679597403000,
                "typename": "desktop",
                "typelabel": "Desktop"
            },
            "details": [],
            "deviceinfo": {
                "deviceInfo": [
                    {
                        "did": ***,
                        "similarityScore": 100,
                        "graphData": [
                            {
                                "time": 1677196800000,
                                "count": 0
                            }
                        ],
                        "info": {
                            "totalUsed": ***,
                            "totalServed": 0,
                            "totalDevicesAndPorts": ***,
                            "devicesAndPorts": [
                                {
                                    "deviceAndPort": {
                                        "direction": "out",
                                        "device": ***,
                                        "port": ***
                                    },
                                    "count": ***,
                                    "size": ***,
                                    "commonProtocol": **,
                                    "udp": **
                                }
                            ],
                            "portsUsed": [
                                {
                                    "port": ***,
                                    "count": ***,
                                    "size": ***
                                }
                            ],
                            "portsServed": [],
                            "devicesUsed": [
                                {
                                    "did": **,
                                    "count": **,
                                    "size": ***
                                }
                            ],
                            "devicesServed": []
                        }
                    }
                ],
                "devices": [
                    {
                        "did": **8,
                        "ip": "1.2.3.4",
                        "ips": [
                            {
                                "ip": "1.2.3.4",
                                "timems": 1679594400000,
                                "time": "2023-03-23 18:00:00",
                                "sid": **
                            }
                        ],
                        "sid": **,
                        "firstSeen": 1646056754000,
                        "lastSeen": 1679597403000,
                        "typename": "desktop",
                        "typelabel": "Desktop"
                    },
                    {
                        "did": **,
                        "macaddress": "00:00:0a:00:00:c0",
                        "vendor": "",
                        "ip": "1.2.3.4",
                        "ips": [
                            {
                                "ip": "1.2.3.4",
                                "timems": 1679598000000,
                                "time": "2023-03-23 19:00:00",
                                "sid": 3
                            }
                        ],
                        "sid": 3,
                        "firstSeen": 1649669953000,
                        "lastSeen": 1679598276000,
                        "os": "Windows  (10.0)",
                        "typename": "dnsserver",
                        "typelabel": "DNS Server",
                        "tags": [
                            {
                                "tid": **,
                                "expiry": 0,
                                "thid": ***,
                                "name": "**",
                                "restricted": false,
                                "data": {
                                    "auto": false,
                                    "color": 112,
                                    "description": "Devices receiving and making DNS queries",
                                    "visibility": "Public"
                                },
                                "isReferenced": true
                            },
                            {
                                "tid": **,
                                "expiry": 0,
                                "thid": **,
                                "name": "**",
                                "restricted": false,
                                "data": {
                                    "auto": false,
                                    "color": 168,
                                    "description": "",
                                    "visibility": "Public"
                                },
                                "isReferenced": true
                            }
                        ]
                    }
                ]
            },
            "similardevices": [
                {
                    "did": **,
                    "score": **,
                    "macaddress": "00:c0:ae:ba:00:00",
                    "vendor": "",
                    "ip": "1.2.3.4",
                    "ips": [
                        {
                            "ip": "1.2.3.4",
                            "timems": 1679594400000,
                            "time": "2023-03-23 18:00:00",
                            "sid": *
                        }
                    ],
                    "sid": *,
                    "hostname": "**local",
                    "firstSeen": 1653658719000,
                    "lastSeen": 1679597690000,
                    "os": "Windows  (10.0)",
                    "devicelabel": "testing label",
                    "typename": "desktop",
                    "typelabel": "Desktop"
                }
            ],
            "modelbreaches": [
                {
                    "acknowledged": false,
                    "commentCount": 0,
                    "pbid": **,
                    "time": 1679591669000,
                    "creationTime": 1679591676000,
                    "devicescore": 0.353,
                    "score": 0.211
                }
            ]
        }
    ]
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "DeviceIDs": [
        **
    ],
    "DeviceIPs": [
        "1.2.3.4"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Devices Count

1

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Device Summary failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Device ID Not Found.

Error Sample Data

Get Device Summary failed.

Status Code: 404.

Message: Device ID Not Found.

Get Device Tags

Retrieves the current tag(s) for the specified device.

Reader Note

Device ID is a required parameter to run this command.

Run the List Devices command to obtain Device ID. Device IDs can be found from the returned raw data at the path $[*].did.

Input

Input Parameter

Required/Optional

Description

Example

Device ID

Required

The ID of the device to retrieve tags. Device IDs can be obtained using the List Devices command.

20

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "tid": ***,
        "expiry": 0,
        "thid": **,
        "name": "**",
        "restricted": false,
        "data": {
            "auto": false,
            "color": 200,
            "description": "",
            "visibility": ""
        },
        "isReferenced": true
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "TagIDs": [
        **
    ],
    "TagNames": [
        "**"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Devices Count

1

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Device Tags failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Device ID Not Found.

Error Sample Data

Get Device Tags failed.

Status Code: 404.

Message: Device ID Not Found.

Get External Endpoint Details

Returns locations, IP address and device connection information for external IPs and hostnames.

Input

Input Parameter	Required/Optional	Description	Example
Endpoint Value	Required	The IP address or hostname to return details. Both IPv4 and IPv6 addresses are supported.	google.com

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "hostname": "google.com",
    "firsttime": 1600279233000,
    "devices": [
        {
            "did": **,
            "macaddress": "00:00:0a:00:00:c0",
            "vendor": "",
            "ip": "1.2.3.4",
            "ips": [
                {
                    "ip": "1.2.3.4",
                    "timems": 1664398800000,
                    "time": "2022-09-28 21:00:00",
                    "sid": *
                }
            ],
            "sid": *,
            "firstSeen": 1649669953000,
            "lastSeen": 1664399660000,
            "typename": "*",
            "typelabel": "DNS Server"
        },
        {
            "did": **,
            "macaddress": "00:c0:ae:ba:00:00",
            "vendor": "",
            "ip": "1.2.3.4",
            "ips": [
                {
                    "ip": "1.2.3.4",
                    "timems": 1664398800000,
                    "time": "2022-09-28 21:00:00",
                    "sid": *
                }
            ],
            "sid": *,
            "hostname": "**",
            "firstSeen": 1653658719000,
            "lastSeen": 1664399676000,
            "devicelabel": "testing label",
            "typename": "desktop",
            "typelabel": "Desktop"
        }
    ],
    "ips": [
        {
            "ip": "1.6.6.6",
            "firsttime": 1646673190000,
            "lasttime": 1664212400000
        },
        {
            "ip": "1.8.8.8",
            "firsttime": 1655745165000,
            "lasttime": 1663607610000
        }
    ],
    "locations": [
        {
            "latitude": ***,
            "longitude": -***,
            "country": "United States",
            "city": ""
        }
    ],
    "popularity": 100,
    "dgascore": 0
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Hostname": "google.com",
    "IP": "8.8.8.8",
    "Popularity": 100,
    "DeviceIDs": [
        31,
        33
    ],
    "DeviceIPs": [
        "1.2.3.4",
        "1.3.3.4"
    ],
    "DeviceTypes": [
        "DNS Server",
        "Desktop"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

hostname	google.com
firsttime	1600279233000
devices	{'did': *, 'macaddress': '00:00:0a:00:00:c0', 'vendor': '', 'ip': '1.2.2.2', 'ips': [{'ip': '1.2.3.4', 'timems': 1664398800000, 'time': '2022-09-28 21:00:00', 'sid': }], 'sid': * 'firstSeen': 1649669953000, 'lastSeen': 1664399660000, 'typename': '*', 'typelabel': 'DNS Server'}
ips	{'ip': '1.6.6.6', 'firsttime': 1646673190000, 'lasttime': 1664212400000} {'ip': '1.8.8.8', 'firsttime': 1655745165000, 'lasttime': 1663607610000}
locations	{'latitude': , 'longitude': -, 'country': 'United States', 'city': ''}
popularity	100
dgascore	0

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get External Endpoint Details failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 408.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Request Timeout.

Error Sample Data

Get External Endpoint Details failed.

Status Code: 408.

Message: Request Timeout.

Get Models

Returns information of the specified model UUIDs.

Reader Note

Model UUIDs is an optional parameter to run this command.

Run the Search Breaches command to obtain Model UUIDs. Module UUIDs are located at the JSON path $.model.uuid in the returned raw data.

Input

Input Parameter	Required/Optional	Description	Example
Model UUIDs	Optional	The UUID(s) of the model(s) to return. Model UUIDs can be obtained using the Search Breaches command. If this parameter is not defined, all models will be returned.	[ "*----**" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "name": "Device::Threat Indicator",
        "pid": **,
        "phid": **,
        "uuid": "***-***-***-***-***",
        "logic": {
            "data": [
                {
                    "cid": **,
                    "weight": 1
                },
                {
                    "cid": **,
                    "weight": 1
                },
                {
                    "cid": **,
                    "weight": 1
                }
            ],
            "targetScore": 1,
            "type": "weightedComponentList",
            "version": 1
        },
        "throttle": **,
        "sharedEndpoints": false,
        "actions": {
            "alert": true,
            "antigena": {},
            "breach": true,
            "model": true,
            "setPriority": false,
            "setTag": false,
            "setType": false,
            "tagTTL": **
        },
        "tags": [
            "",
            "Requires Configuration"
        ],
        "interval": 1,
        "delay": 0,
        "sequenced": false,
        "active": true,
        "modified": "2022-06-15 12:01:36",
        "activeTimes": {
            "devices": {},
            "tags": {},
            "type": "exclusions",
            "version": 2
        },
        "autoUpdatable": true,
        "autoUpdate": true,
        "autoSuppress": true,
        "description": "A device has visited an external location that has been identified by an Indicator added to the watchlists or via TAXII.\\n\\nAction: Investigate devices network behaviours paying particular attention to the domains or IP's being highlighted. Verify the indicator is a true malicious indicator.",
        "behaviour": "decreasing",
        "created": {
            "by": "System"
        },
        "edited": {
            "by": "System"
        },
        "history": [
            {
                "modified": "2022-06-15 12:01:36",
                "active": true,
                "message": "Updated Watched endpoint source regex to exclude 'Attack Surface Management'",
                "by": "System",
                "phid": **
            },
            {
                "modified": "2021-06-28 19:31:20",
                "active": false,
                "message": "Preventing the model from breaching on incoming connections",
                "by": "System",
                "phid": **
            },
            {
                "modified": "2020-09-01 00:25:40",
                "active": false,
                "message": "Changing filter A of the third component to be case sensitive",
                "by": "System",
                "phid": **
            },
            {
                "modified": "2020-09-01 00:12:21",
                "active": false,
                "message": "enabled by default and moved to the device folder",
                "by": "Nobody",
                "phid": **
            }
        ],
        "message": "Updated Watched endpoint source regex to exclude 'Attack Surface Management'",
        "version": 39,
        "priority": *,
        "category": "Critical",
        "compliance": false
    }
]

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Models failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: DATANOTFOUND ERROR.

Error Sample Data

Get Models failed.

Status Code: 404.

Message: DATA NOT FOUND ERROR.

Get Status

Returns detailed system health information.

Input

N/A

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "excessTraffic": false,
    "time": "2023-03-23 21:32",
    "installed": "2020-09-02",
    "mobileAppConfigured": false,
    "version": "6.0.23 (**)",
    "ipAddress": "1.2.3.4",
    "modelsUpdated": "2023-03-23 08:10:38",
    "modelPackageVersion": "6.0.**~**~**",
    "bundleVersion": "60051",
    "bundleDate": "2023-03-14 11:13:33",
    "bundleInstalledDate": "2023-03-21 08:47:29",
    "hostname": "**-**-01",
    "inoculation": false,
    "applianceOSCode": "f",
    "license": "",
    "saasConnectorLicense": "",
    "antigenaSaasLicense": "",
    "syslogTLSSHA1Fingerprint": "**",
    "syslogTLSSHA256Fingerprint": "0**",
    "antigenaNetworkEnabled": true,
    "antigenaNetworkLicense": "",
    "antigenaNetworkRunning": true,
    "logIngestionReplicated": 0,
    "logIngestionProcessed": 0,
    "logIngestionTCP": 0,
    "logIngestionUDP": 0,
    "logIngestionTypes": {
        "TestingDeviceObjects-connectionlogs": 88
    },
    "licenseCounts": {
        "saas": {
            "total": 0
        },
        "licenseIPCount": 9
    },
    "type": "master",
    "diskUtilization": 1,
    "uptime": "13:31:48",
    "systemUptime": "192:18:55",
    "load": 73,
    "cpu": 20,
    "memoryUsed": 48,
    "dataQueue": 0,
    "darkflowQueue": 0,
    "networkInterfacesState_eth0": "up",
    "networkInterfacesAddress_eth0": "**",
    "networkInterfacesReceived_eth0": **,
    "networkInterfacesTransmitted_eth0": **,
    "bandwidthCurrent": 0,
    "bandwidthCurrentString": "0 kbps",
    "bandwidthAverage": 0,
    "bandwidthAverageString": "0 kbps",
    "bandwidth7DayPeak": 0,
    "bandwidth7DayPeakString": "0 kbps",
    "bandwidth2WeekPeak": 0,
    "bandwidth2WeekPeakString": "0 kbps",
    "processedBandwidthCurrent": 0,
    "processedBandwidthCurrentString": "0 kbps",
    "processedBandwidthAverage": 0,
    "processedBandwidthAverageString": "0 kbps",
    "processedBandwidth7DayPeak": 0,
    "processedBandwidth7DayPeakString": "0 kbps",
    "processedBandwidth2WeekPeak": 0,
    "processedBandwidth2WeekPeakString": "0 kbps",
    "eventsPerMinuteCurrent": {
        "networkConnections": 282,
        "logInputConnections": 0,
        "cSensorConnections": 0,
        "cSensorNotices": 0,
        "cSensorDeviceDetails": 0,
        "cSensorModelEvents": 0,
        "networkNotices": 1,
        "networkDeviceDetails": 0,
        "networkModelEvents": 1411,
        "logInputNotices": 0,
        "logInputDeviceDetails": 0,
        "logInputModelEvents": 0,
        "saasNotices": 0,
        "saasModelEvents": 0
    },
    "probes": {
        "1": {
            "id": 1,
            "antigenaNetworkBlockedConnections": {
                "attempted": 62222,
                "failed": 59
            },
            "configuredServer": "**",
            "version": "6.0.11 (aefe9a)",
            "ipAddress": "1.1.1.1",
            "hostname": "ip-1-1-1-1",
            "time": "2023-03-23 21:30",
            "applianceOSCode": "f",
            "syslogTLSSHA1Fingerprint": "***",
            "syslogTLSSHA256Fingerprint": "**",
            "antigenaNetworkRunning": true,
            "logIngestionReplicated": 0,
            "logIngestionProcessed": 0,
            "logIngestionTCP": **,
            "logIngestionUDP": 0,
            "type": "vSensor",
            "diskUtilization": 1,
            "uptime": "324:03:43",
            "systemUptime": "1066:57:42",
            "load": 22,
            "cpu": 10,
            "memoryUsed": 90,
            "networkInterfacesState_ens5": "up",
            "networkInterfacesAddress_ens5": "**",
            "networkInterfacesReceived_ens5": **,
            "networkInterfacesTransmitted_ens5": **,
            "bandwidthCurrent": 2843993,
            "bandwidthCurrentString": "2.84 Mbps",
            "bandwidthAverage": 625000,
            "bandwidthAverageString": "625 kbps",
            "bandwidth7DayPeak": 5535089,
            "bandwidth7DayPeakString": "5.54 Mbps",
            "bandwidth2WeekPeak": 5535089,
            "bandwidth2WeekPeakString": "5.54 Mbps",
            "processedBandwidthCurrent": 2757163,
            "processedBandwidthCurrentString": "2.76 Mbps",
            "processedBandwidthAverage": 373175,
            "processedBandwidthAverageString": "373 kbps",
            "processedBandwidth7DayPeak": 5076054,
            "processedBandwidth7DayPeakString": "5.08 Mbps",
            "processedBandwidth2WeekPeak": 5076054,
            "processedBandwidth2WeekPeakString": "5.08 Mbps",
            "connectionsPerMinuteCurrent": 133,
            "connectionsPerMinuteAverage": 145,
            "connectionsPerMinute7DayPeak": 280,
            "connectionsPerMinute2WeekPeak": 280
        }
    },
    "connectionsPerMinuteCurrent": 133,
    "connectionsPerMinuteAverage": 144,
    "connectionsPerMinute7DayPeak": 280,
    "connectionsPerMinute2WeekPeak": 280,
    "operatingSystems": 2,
    "newDevices4Weeks": 2,
    "newDevices7Days": 0,
    "newDevices24Hours": 0,
    "newDevicesHour": 0,
    "activeDevices4Weeks": 12,
    "activeDevices7Days": 10,
    "activeDevices24Hours": 10,
    "activeDevicesHour": 7,
    "deviceHostnames": 1,
    "deviceMACAddresses": 3,
    "deviceRecentIPChange": 0,
    "models": 975,
    "modelsBreached": **,
    "modelsSuppressed": **,
    "devicesModeled": 10,
    "exampleUnidirectionalConnections": [],
    "recentUnidirectionalConnections": 0,
    "mostRecentDCE_RPCTraffic": "2023-03-23 21:13:00",
    "mostRecentDHCPTraffic": "2022-10-25 12:41:00",
    "mostRecentDNSTraffic": "2023-03-23 21:27:00",
    "mostRecentGSSAPITraffic": "2023-03-23 21:29:00",
    "mostRecentH2Traffic": "2023-03-23 21:04:00",
    "mostRecentHTTPTraffic": "2023-03-23 21:32:00",
    "mostRecentKERBEROSTraffic": "2023-03-23 21:29:00",
    "mostRecentLDAPTraffic": "2023-03-23 21:13:00",
    "mostRecentNETLOGONTraffic": "2023-03-21 00:02:00",
    "mostRecentNTLMTraffic": "2023-03-21 00:04:00",
    "mostRecentNTPTraffic": "2023-03-23 21:15:00",
    "mostRecentSMBTraffic": "2023-03-23 21:29:00",
    "mostRecentSSHTraffic": "2023-02-28 12:36:00",
    "mostRecentSSLTraffic": "2023-03-23 21:32:00",
    "internalIPRangeList": [
        "10.0.0.0/8",
        "1.0.0.0/12",
        "1.1.0.0/16"
    ],
    "internalIPRanges": 3,
    "dnsServers": 2,
    "internalDomains": 0,
    "internalAndExternalDomains": 0,
    "proxyServers": 0,
    "subnets": 2,
    "subnetData": [
        {
            "recentTrafficPercent": 67,
            "recentUnidirectionalTrafficPercent": 0,
            "sid": 4,
            "network": "19.0.0.0/24",
            "devices": 4,
            "clientDevices": 3,
            "mostRecentTraffic": "2023-03-23 21:00:00",
            "mostRecentDHCP": "Never"
        },
        {
            "recentTrafficPercent": 100,
            "recentUnidirectionalTrafficPercent": 1,
            "sid": 3,
            "network": "1.0.0.0/20",
            "devices": 4,
            "clientDevices": 2,
            "mostRecentTraffic": "2023-03-23 21:00:00",
            "mostRecentDHCP": "2022-10-25 12:00:00",
            "kerberosQuality": 100
        }
    ]
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "IPAddress": "1.2.3.4",
    "HostName": "**-**-01"
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

excessTraffic	False
version	6.0.23 (**)
ipAddress	1.2.3.4
hostname	--01

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Status failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 408.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Request Timeout

Error Sample Data

Get Status failed.

Status Code: 408.

Message: Request Timeout

List Actions

Returns information about current and past Darktrace RESPOND/Network (formerly Antigena Network) actions. It can be used to retrieve a list of currently quarantined devices or Darktrace RESPOND Actions requiring approval.

Reader Note

Breach ID is a required parameter to run this command.

Run the Search Breaches command to obtain Breach ID. Breach IDs can be found from the returned raw data at the path $[*].pbid.

Input

Input Parameter	Required/Optional	Description	Example
From	Optional	The start time of actions to return in UTC time.	2023-01-23 00:00
To	Optional	The end time of actions to return in UTC time.	2023-01-24 00:00
Breach ID	Optional	The ID of the model breach to retrieve corresponding connections and events. Breach ID can be obtained using the Search Breaches command.	***
Include Cleared	Optional	The option to return Darktrace RESPOND actions that are already cleared. The default option is False.	True
Include History	Optional	The option to include additional history information about the action state, such as when it was created or extended. The default option is False.	True
Need Confirming	Optional	Filters returned Darktrace RESPOND actions by those that need human confirmation or do not need human confirmation. The default option is False.	False

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "actions": [
        {
            "codeid": **,
            "did": **,
            "ip": "1.2.3.4",
            "ips": [
                "1.2.3.4"
            ],
            "action": "connection",
            "manual": true,
            "triggerer": {
                "username": "**",
                "reason": ""
            },
            "history": [
                {
                    "family": "NETWORK",
                    "username": "**",
                    "action": "created",
                    "reason": "",
                    "time": 1679616324000
                },
                {
                    "family": "NETWORK",
                    "username": "**",
                    "action": "expired",
                    "reason": "",
                    "time": 1679616444000
                }
            ],
            "label": "Block connections",
            "detail": "from 10.10.10.10 to 8.8.8.8 port **",
            "score": 0,
            "pbid": 0,
            "model": "",
            "modeluuid": "",
            "start": 1679616324000,
            "expires": 1679616444000,
            "blocked": false,
            "active": true,
            "cleared": false
        }
    ],
    "connections": []
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "DeviceIDs": [
        **
    ],
    "DeviceIPs": [
        "1.2.3.4"
    ],
    "ActionLabels": [
        "Block connections"
    ],
    "ActionDetails": [
        "from 10.10.10.10 to 8.8.8.8 port **"
    ],
    "ActionIDs": [
        **
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Actions Count

1

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Actions failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Breach ID Not Found.

Error Sample Data

List Actions failed.

Status Code: 404.

Message: Breach ID Not Found.

List Devices

Returns a list of devices identified by Darktrace.

Reader Note

Returned devices are sorted by “dids”, in ascending order.
The minimum input value for the Seen Since parameter is 1 second.
The Seen Since parameter does not accept multiple time unit inputs (e.g. 1 week and 1 min). Only one time unit can be used for one input value.
The valid time units for the Seen Since parameter are as follows:
- Second: <number> (you do not need to specify seconds, as it is the default time unit)
- Minute: <number>min(s) or <number> min(s)
- Hour: <number>hour(s) or <number> hour(s), please note that “hr” is not valid
- Day: <number>day(s) or <number> day(s)
- Week: <number>week(s) or <number> week(s)

Input

Input Parameter	Required/Optional	Description	Example
Seen Since	Optional	Filters returned devices by last seen activity time. The valid input can be the number of seconds before the current time, or a number with a time unit modifier such as day or week. If this parameter is not defined, all devices will be returned.	10min

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "id": -*,
        "did": -*,
        "sid": -*,
        "time": 1599009216000,
        "endtime": 1664487002000,
        "devicelabel": "Link Local Traffic",
        "typename": "networkrange",
        "typelabel": "Network Range"
    },
    {
        "id": -*,
        "did": -*,
        "sid": -*,
        "time": 1599009216000,
        "endtime": 1664487535000,
        "devicelabel": "Internal Multicast Traffic",
        "typename": "networkrange",
        "typelabel": "Network Range"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "dids": [
        -*,
        *
    ],
    "ips": [
        "",
        "1.2.3.4"
    ],
    "macaddresses": [
        "",
        "00:c0:ae:ba:00:00"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

ID	TYPELABEL	IP	MACADDRESS
-*	Network Range
**	Desktop	1.2.3.4	00:0e:e0:00:00:00

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Devices failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API SIGNATURE ERROR.

Error Sample Data

List Devices failed.

Status Code: 400.

Message: API SIGNATURE ERROR.

List Metrics

Returns the list of metrics available for filtering other API calls and for use in model making.

Input

N/A

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "mlid": *,
        "name": "**",
        "label": "External Connections",
        "set": "A",
        "units": "",
        "filtertypes": [
            "Feature model",
            "Inoculation source",
            "Inoculation strength",
            "Inoculation endpoint",
            "Inoculation description",
            "MD5 file hash",
            "SHA1 file hash",
            "SHA256 file hash",
            "Unusual JA3 server hash",
            "New JA3 server hash for device",
            "Unusual JA3 server hash for device",
            "Increased JA3 server hash use",
            "JA3 server hash",
            "JA3 hash",
            "Unusual JA3 hash",
            "New JA3 hash for device",
            "Unusual JA3 hash for device",
            "Increased JA3 hash use",
            "JA3 hash rare hostname",
            "User agent rare hostname",
            "Process popularity",
            "New connectivity for hour",
            "Cipher suite",
            "SSL/TLS version",
            "Certificate Issuer",
            "Certificate subject",
            "Same IP",
            "Same port",
            "Same hostname",
            "Same domain",
            "Unique ports",
            "Unique hostnames",
            "Unique domains",
            "Unique IPs",
            "Direction",
            "Connection hostname",
            "Watched endpoint",
            "Watched endpoint source",
            "Watched endpoint description",
            "Watched endpoint strength",
            "Matched endpoint",
            "Country",
            "ASN",
            "Proxied connection",
            "Location",
            "Destination IP",
            "Source port",
            "Duration",
            "Destination port",
            "Source IP",
            "Endpoint public IP",
            "Application protocol",
            "Internal source device type",
            "Internal destination device type",
            "Internal source device OS",
            "Internal destination device OS",
            "Internal destination device priority",
            "Internal source device priority",
            "Internal source credential",
            "Internal destination credential",
            "Protocol",
            "Individual size up",
            "Individual size down",
            "Data ratio",
            "New connection",
            "New external IP",
            "Internal source device name",
            "Internal source device hostname",
            "Internal source device label",
            "Internal destination device name",
            "Internal destination device hostname",
            "Internal destination device label",
            "Internal source device vendor",
            "Internal destination device vendor",
            "Internal source device MAC address",
            "Internal source activity",
            "Internal source subnet label",
            "Internal destination device MAC address",
            "Internal destination activity",
            "Internal destination subnet label",
            "Message",
            "Beaconing score",
            "Unusual connectivity",
            "Unusual incoming data volume",
            "Unusual outgoing data volume",
            "Unusual number of connections",
            "Unusual sustained connectivity for group",
            "Unusual individual connection for group",
            "Unusual port for application protocol",
            "Increase in activity score",
            "Counter seconds",
            "Age of source",
            "Age of destination",
            "User agent",
            "Rare external IP",
            "Rare hostname",
            "Rare domain",
            "Trusted hostname",
            "Age of external hostname",
            "DGA domain score",
            "DGA hostname score",
            "Rare external endpoint",
            "URI",
            "HTTP no referrer",
            "HTTP referrer",
            "HTTP X-Forwarded-For",
            "HTTP method",
            "HTTP content type",
            "HTTP response code",
            "Time since first connection",
            "Suspicious request data",
            "Tagged internal source",
            "Tagged internal destination",
            "Day of the week",
            "Hour of the day"
        ],
        "unitsinterval": 3600,
        "lengthscale": 9999960
    }
]

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Metrics failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API SIGNATURE ERROR.

Error Sample Data

List Metrics failed.

Status Code: 400.

Message: API SIGNATURE ERROR.

Get Model Components

Returns information for the specified components.

Reader Note

Component CIDs is an optional parameter to run this command.

Run the Search Breaches command to obtain the Component CIDs. Component CIDs will be returned in the returned raw data under the key “cid”.
Some Component CIDs may not be retrievable. It is recommended to input the latest component CIDs.
If the input parameter is not defined, all model components will be returned. This may cause the command to run for a long time.

Input

Input Parameter	Required/Optional	Description	Example
Component CIDs	Optional	The ID(s) of the component(s) to return. Component CIDs can be obtained using the Search Breaches command. If this parameter is not defined, all components will be returned.	[ **]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "cid": **,
        "chid": **,
        "mlid": **,
        "threshold": 0,
        "interval": 3600,
        "logic": {
            "data": {
                "left": {
                    "left": "A",
                    "operator": "AND",
                    "right": "B"
                },
                "operator": "OR",
                "right": {
                    "left": "A",
                    "operator": "AND",
                    "right": "C"
                }
            },
            "version": "v0.1"
        },
        "filters": [
            {
                "id": "A",
                "cfid": **,
                "cfhid": **,
                "filtertype": "Direction",
                "comparator": "is",
                "arguments": {
                    "value": "out"
                }
            },
            {
                "id": "B",
                "cfid": **,
                "cfhid": **,
                "filtertype": "Message",
                "comparator": "does not match regular expression",
                "arguments": {
                    "value": "^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$"
                }
            },
            {
                "id": "C",
                "cfid": **,
                "cfhid": **,
                "filtertype": "Destination IP",
                "comparator": "does not match",
                "arguments": {
                    "value": "0.0.0.0"
                }
            },
            {
                "id": "**",
                "cfid": **,
                "cfhid": **,
                "filtertype": "Message",
                "comparator": "display",
                "arguments": {}
            },
            {
                "id": "*",
                "cfid": **,
                "cfhid": **,
                "filtertype": "Connection hostname",
                "comparator": "display",
                "arguments": {}
            }
        ],
        "active": true
    }
]

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Model Components failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: DATANOTFOUND ERROR.

Error Sample Data

Get Model Components failed.

Status Code: 404.

Message: DATA NOT FOUND ERROR.

List PCAPs

Returns a list of PCAPs and their status.

Reader Note

Once the Create PCAP command requested PCAP status becomes "state":"finished", it can be retrieved with this command.

Input

N/A

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "tmqid": **,
        "startTime": 1677146576,
        "filename": "/pcaps/**.pcap",
        "index": "connection2",
        "ip1": "1.2.3.4",
        "ip2": "1.2.2.2",
        "start": 1655805223,
        "end": 1655805250,
        "state": "failed"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "TmQueryIDs": [
       **
    ],
    "SourceIPs": [
        "1.2.3.4"
    ],
    "DestinationIPs": [
        "1.2.3.4"
    ],
    "States": [
        "failed"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

PCAPs Count

5

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List PCAPs failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API SIGNATURE ERROR.

Error Sample Data

List PCAPs failed.

Status Code: 400.

Message: API SIGNATURE ERROR.

List Similar Devices

Returns a list of devices similar to the specified device on the network.

Reader Note

Device ID is a required parameter to run this command.

Run the List Devices command to obtain the Device ID. Device IDs can be found from the returned raw data at the path $[*].did.

Input

Input Parameter

Required/Optional

Description

Example

Device ID

Required

The ID of the device to list similar devices. Device IDs can be obtained using the List Devices command.

**

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "did": **,
        "quarantine": 1664478948000,
        "score": 99,
        "macaddress": "00:00:ce:00:00:0e",
        "vendor": "",
        "ip": "1.3.3.3",
        "ips": [
            {
                "ip": "1.1.1.1",
                "timems": 1664496000000,
                "time": "2022-09-30 00:00:00",
                "sid": *
            }
        ],
        "sid": *,
        "hostname": "**",
        "firstSeen": 1653658812000,
        "lastSeen": 1664498363000,
        "typename": "server",
        "typelabel": "Server",
        "tags": [
            {
                "tid": *,
                "expiry": 0,
                "thid": *,
                "name": "Domain Authenticated",
                "restricted": false,
                "data": {
                    "auto": false,
                    "color": 200,
                    "description": ""
                },
                "isReferenced": true
            },
            {
                "tid": *,
                "expiry": 0,
                "thid": *,
                "name": "High Risk",
                "restricted": false,
                "data": {
                    "auto": false,
                    "color": 200,
                    "description": ""
                },
                "isReferenced": true
            },
            {
                "tid": *,
                "expiry": 0,
                "thid": *,
                "name": "Microsoft Windows",
                "restricted": false,
                "data": {
                    "auto": false,
                    "color": 168,
                    "description": "",
                    "visibility": "Public"
                },
                "isReferenced": true
            }
        ]
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "DeviceIDs": [
        *
    ],
    "IPs": [
        "1.2.3.3"
    ],
    "SimilarScore": [
        99
    ],
    "DeviceTypes": [
        "Server"
    ],
    "LastSeenTime": [
        "2022-09-30T00:39:23Z"
    ],
    "SubnetIDs": [
        *
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Similar Metrics failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API DATE ERROR

Error Sample Data

List Similar Metrics failed.

Status Code: 400.

Message: API DATE ERROR

List Subnets

Retrieves subnets with activity in the specified time period processed by Darktrace.

Reader Note

Returned subnets are sorted by “mlid”, in ascending order.
The Seen Since parameter does not multiple time unit inputs (e.g. 1 week and 1 min). Only one time unit can be used for one input value.
The valid time units for the Seen Since parameter are as follows:
- Second: <number> (you do not need to specify seconds, as it is the default time unit)
- Minute: <number>min(s) or <number> min(s)
- Hour: <number>hour(s) or <number> hour(s), please note that “hr” is not valid
- Day: <number>day(s) or <number> day(s)
- Week: <number>week(s) or <number> week(s)
- Month: <number>month(s) or <number> month(s) (max 6 months to input)

Input

Input Parameter

Required/Optional

Description

Example

Seen Since

Optional

Filters returned subnets by last seen activity time. The valid input can be the number of seconds before the current time, or a number with a time unit modifier such as day or week (e.g. 2hour or 1day).

Note: The minimum input value is 1second, and the maximum is 6months.

5min

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "sid": *,
        "auto": true,
        "dhcp": true,
        "firstSeen": 1646083848000,
        "label": "1.0.0.0/24",
        "lastSeen": 1671307699000,
        "latitude": 52,
        "longitude": 0,
        "network": "1.0.0.0/24",
        "shid": 7,
        "uniqueHostnames": false,
        "uniqueUsernames": false,
        "confidence": 2,
        "recentTrafficPercent": 0,
        "dhcpCount": 0,
        "kerberosCount": 0,
        "dhcpQuality": 0,
        "probes": [
            0
        ],
        "kerberosQuality": 0,
        "clientDevices": 1,
        "serverDevices": 0,
        "mostRecentTraffic": **
    }
]

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Subnets failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API SIGNATURE ERROR.

Error Sample Data

List Subnets failed.

Status Code: 400

Message: API SIGNATURE ERROR.

List Tags

Returns the details for all current tags.

Input

Input Parameter

Required/Optional

Description

Example

Tag Names

Optional

The name(s) of the tag(s) to retrieve. Tag Names are case insensitive.

[

"active threat"

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "tid": **,
        "expiry": 0,
        "thid": **,
        "name": "Active Threat",
        "restricted": false,
        "data": {
            "auto": false,
            "color": 200,
            "description": ""
        },
        "isReferenced": true
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "TagIDs": [
        **
    ],
    "TagNames": [
        "Active Threat"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Tags Count

1

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Tags failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Tag Name not found.

Error Sample Data

List Tags failed.

Status Code: 404.

Message: Tag name Not Found.

Search Breaches

Returns a time-sorted list of model breaches, filtered by the specified parameters.

Reader Note

Device ID is an optional parameter to run this command.

Run the List Devices command to obtain Device ID. Device IDs can be found from the returned raw data at the path $[*].did.
If no input parameters are defined, up to 100 non-acknowledged breaches will be returned.
If only the Start Time and End Time parameters are defined, all non-acknowledged breaches within the time range will be returned.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Optional	The start time of the time range to search breaches in UTC time.	2023-01-26 00:00
End Time	Optional	The end time of the time range to search breaches in UTC time.	2023-01-27 00:00
Minimum Score	Optional	The minimum score to filter searched breaches.	0.5
Device ID	Optional	The ID of the device modeled in Darktrace to search breaches. Device IDs can be obtained using the List Devices command.	**
Include Acknowledged	Optional	The option to return acknowledged breaches in the search. If this parameter is not defined, the returned data will exclude acknowledged breaches.	True
Count	Optional	The number of breaches to return. Note: If this parameter is not defined, but the Start Time and End time parameters are, all items between the specified time range will be returned. If all three parameters are not defined, the default value of 100 for this parameter will be used.	3

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "acknowledged": false,
        "commentCount": 0,
        "pbid": ***,
        "time": 1664212389000,
        "creationTime": 1664212400000,
        "model": {
            "then": {
                "name": "Device::Threat Indicator",
                "pid": **,
                "phid": ***,
                "uuid": "***-***-***-***-***",
                "logic": {
                    "data": [
                        {
                            "cid": ***,
                            "weight": 1
                        },
                        {
                            "cid": ***,
                            "weight": 1
                        },
                        {
                            "cid": ***,
                            "weight": 1
                        }
                    ],
                    "targetScore": 1,
                    "type": "weightedComponentList",
                    "version": 1
                },
                "throttle": ***,
                "sharedEndpoints": false,
                "actions": {
                    "alert": true,
                    "antigena": {},
                    "breach": true,
                    "model": true,
                    "setPriority": false,
                    "setTag": false,
                    "setType": false,
                    "tagTTL": ***
                },
                "tags": [
                    "",
                    "Requires Configuration"
                ],
                "interval": 1,
                "delay": 0,
                "sequenced": false,
                "active": true,
                "modified": "2022-06-15 12:01:36",
                "activeTimes": {
                    "devices": {},
                    "tags": {},
                    "type": "exclusions",
                    "version": 2
                },
                "autoUpdatable": true,
                "autoUpdate": true,
                "autoSuppress": true,
                "description": "A device has visited an external location that has been identified by an Indicator added to the watchlists or via TAXII.\\n\\nAction: Investigate devices network behaviours paying particular attention to the domains or IP's being highlighted. Verify the indicator is a true malicious indicator.",
                "behaviour": "decreasing",
                "created": {
                    "by": "System"
                },
                "edited": {
                    "by": "System"
                },
                "version": 39,
                "priority": 5,
                "category": "Critical",
                "compliance": false
            },
            "now": {
                "name": "Device::Threat Indicator",
                "pid": ***,
                "phid": ***,
                "uuid": "***-***-***-***-***,
                "logic": {
                    "data": [
                        {
                            "cid": ***,
                            "weight": 1
                        },
                        {
                            "cid": ***,
                            "weight": 1
                        },
                        {
                            "cid": ***,
                            "weight": 1
                        }
                    ],
                    "targetScore": 1,
                    "type": "weightedComponentList",
                    "version": 1
                },
                "throttle": ***,
                "sharedEndpoints": false,
                "actions": {
                    "alert": true,
                    "antigena": {},
                    "breach": true,
                    "model": true,
                    "setPriority": false,
                    "setTag": false,
                    "setType": false,
                    "tagTTL": ***
                },
                "tags": [
                    "",
                    "Requires Configuration"
                ],
                "interval": 1,
                "delay": 0,
                "sequenced": false,
                "active": true,
                "modified": "2022-06-15 12:01:36",
                "activeTimes": {
                    "devices": {},
                    "tags": {},
                    "type": "exclusions",
                    "version": 2
                },
                "autoUpdatable": true,
                "autoUpdate": true,
                "autoSuppress": true,
                "description": "A device has visited an external location that has been identified by an Indicator added to the watchlists or via TAXII.\\n\\nAction: Investigate devices network behaviours paying particular attention to the domains or IP's being highlighted. Verify the indicator is a true malicious indicator.",
                "behaviour": "decreasing",
                "created": {
                    "by": "System"
                },
                "edited": {
                    "by": "System"
                },
                "message": "Updated Watched endpoint source regex to exclude 'Attack Surface Management'",
                "version": 39,
                "priority": 5,
                "category": "Critical",
                "compliance": false
            }
        },
        "triggeredComponents": [
            {
                "time": 1664212388000,
                "cbid": ***,
                "cid": **,
                "chid": **,
                "size": 1,
                "threshold": 0,
                "interval": 3600,
                "logic": {
                    "data": {
                        "left": "A",
                        "operator": "AND",
                        "right": {
                            "left": "F",
                            "operator": "AND",
                            "right": {
                                "left": "G",
                                "operator": "AND",
                                "right": {
                                    "left": "H",
                                    "operator": "AND",
                                    "right": {
                                        "left": "I",
                                        "operator": "AND",
                                        "right": {
                                            "left": "J",
                                            "operator": "AND",
                                            "right": "K"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "version": "v0.1"
                },
                "metric": {
                    "mlid": **,
                    "name": "dtwatcheddomain",
                    "label": "Watched Domain"
                },
                "triggeredFilters": [
                    {
                        "cfid": **,
                        "id": "A",
                        "filterType": "Watched endpoint source",
                        "arguments": {
                            "value": "^(\\_?Darktrace.*|Attack Surface Management)"
                        },
                        "comparatorType": "does not match regular expression",
                        "trigger": {
                            "value": "ThreatIntel"
                        }
                    },
                    {
                        "cfid": **,
                        "id": "F",
                        "filterType": "Watched endpoint source",
                        "arguments": {
                            "value": ".+"
                        },
                        "comparatorType": "matches regular expression",
                        "trigger": {
                            "value": "ThreatIntel"
                        }
                    },
                    {
                        "cfid": **,
                        "id": "G",
                        "filterType": "Watched endpoint source",
                        "arguments": {
                            "value": "Default"
                        },
                        "comparatorType": "does not match",
                        "trigger": {
                            "value": "ThreatIntel"
                        }
                    },
                    {
                        "cfid": **,
                        "id": "H",
                        "filterType": "Tagged internal source",
                        "arguments": {
                            "value": 4
                        },
                        "comparatorType": "does not have tag",
                        "trigger": {
                            "value": "4",
                            "tag": {
                                "tid": 4,
                                "expiry": 0,
                                "thid": 4,
                                "name": "Security Device",
                                "restricted": false,
                                "data": {
                                    "auto": false,
                                    "color": 55,
                                    "description": "",
                                    "visibility": "Public"
                                },
                                "isReferenced": true
                            }
                        }
                    }
                ]
            }
        ],
        "score": 0.797,
        "device": {
            "did": **,
            "macaddress": "00:c0:ae:ba:00:00",
            "vendor": "",
            "ip": "1.1.1.4",
            "ips": [
                {
                    "ip": "1.1.1.4",
                    "timems": 1664312400000,
                    "time": "2022-09-27 21:00:00",
                    "sid": *
                }
            ],
            "sid": *,
            "hostname": "**",
            "firstSeen": 1653658719000,
            "lastSeen": 1664315065000,
            "devicelabel": "testing label",
            "typename": "desktop",
            "typelabel": "Desktop",
            "credentials": [
                "vagrant"
            ]
        }
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "BreachIDs": [
        **
    ],
    "Time": [
        "2022-09-26T17:13:09Z"
    ],
    "CreationTime": [
        "2022-09-26T17:13:20Z"
    ],
    "Scores": [
        0.797
    ],
    "DeviceIDs": [
        **
    ],
    "DeviceIPs": [
        "1.1.1.4"
    ],
    "HostNames": [
        "**"
    ],
    "ModelNames": [
        "Device::Threat Indicator"
    ],
    "ModelIDs": [
        ***
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Search Breaches failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API SIGNATURE ERROR.

Error Sample Data

Search Breaches failed.

Status Code: 400.

Message: API SIGNATURE ERROR.

Tag Devices

Adds tag(s) to the specified device(s).

Reader Note

Device ID and Tags are required parameters to run this command.

Run the List Devices command to obtain Device IDs. Device IDs can be found from the returned raw data at the path $[*].did.
Run the List Tags command to obtain Tags. Tags referring to the Tag Names, which can be found in the returned raw data at the path $.name.

Input

Input Parameter	Required/Optional	Description	Example
Device IDs	Required	The IDs of the devices modeled in the Darktrace system to add tags to. Device IDs can be obtained using the List Devices command.	[ ** ]
Tags	Required	The existing tag name(s) to add to the devices. You can obtain existing tag names using the List Tags command.	[ "Admin" ]
Duration	Optional	How long the tag should be set for the device in seconds. The tag will be removed once this duration has expired.	3600

Output

Raw Data

The primary response data from the API request.

D3 customizes the Raw Data by extracting the data from path $.did in API returned JSON.

SAMPLE DATA

JSON

[
    {
        "did": **,
        "teid": **,
        "tehid": **,
        "tid": **,
        "thid": 0,
        "entityType": "Device",
        "entityValue": "20",
        "valid": true
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "TagIDs": [
        **
    ],
    "DeviceIDs": [
        **
    ]
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Device Tags Count

1

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Tags failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Device IDs Not Found.

Error Sample Data

List Tags failed.

Status Code: 404.

Message: Device IDs Not Found.

Unacknowledge

Unacknowledges the specified model breaches.

Reader Note

Input parameter Breach IDs is required to run this command.

Run the Search Breaches command to obtain Breach IDs.
Breaches can either be acknowledged or unacknowledged, but can not be both. You may check the breach IDs’ acknowledge status from the response data of the Fetch Event command, at the JSON path $.[*].acknowledge. You can acknowledge the breaches that are unacknowledged (“false”). The breach IDs are returned under the key “pbid”.

Input

Input Parameter

Required/Optional

Description

Example

Breach IDs

Required

The ID(s) of the model breach(es) to unacknowledge. Breach IDs can be obtained using the Search Breaches command.

[

**

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "response": "SUCCESS"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Responses": [
        "SUCCESS"
    ]
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Unacknowledge failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API DATE ERROR

Error Sample Data

Unacknowledge failed.

Status Code: 400.

Message: API DATE ERROR

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

SAMPLE DATA

CODE

Successful

Error Handling

If the Return Data is failed, an Error tab will appear in the Test Result window.

The error tab contains the responses from the third-party API calls including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Darktrace portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API SIGNATURE ERROR.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 400.

Message: API SIGNATURE ERROR.