Darktrace, which is Enterprise Immune System's flagship threat detection and defense capability, is based on unsupervised machine learning and probabilistic mathematics. Darktrace works by creating unique behavioral models for every user and device across the enterprises and analyzing the relationships between them.
This document provides information about the Darktrace connector, which facilitates automated interactions, with a Darktrace server using FortiSOAR™ playbooks. Add the Darktrace connector as a step in FortiSOAR™ playbooks and perform automated operations, such as adding or removing a domain, hostname, or IP address from Darktrace's internal watchlist.
Connector Version: 1.3.0
Authored By: Fortinet
Certified: No
Following enhancements have been made to the Darktrace connector in version 1.3.0:
Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command as a root user to install the connector:
yum install cyops-connector-darktrace
For the procedure to configure a connector, click here
In FortiSOAR™, on the Connectors page, click the Darktrace connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:
| Parameter | Description |
|---|---|
| Server URL | The URL of the Darktrace server to which you will connect and perform the automated operations. |
| API Public Token | The public token of the Darktrace server to which you will connect and perform the automated operations. |
| API Private Token | The private key of the Darktrace server to which you will connect and perform the automated operations. |
| Time difference (minutes) from Darktrace Server Time | Allows you to modify the current time passed (default=0) to the Darktrace API to allow for timezone differences, e.g., passing 29 will add 29 minutes to the time, and -29 will take off 29 minutes. NOTE: The maximum allowed time difference is 30 minutes. |
| Verify SSL | Specifies whether the SSL certificate for the server is to be verified. By default, this option is selected, i.e., set to true. |
You can use the following automated operations in playbooks and also use the annotations to access operations:
| Function | Description | Annotation and Category |
|---|---|---|
| Get Watch List | Retrieves a list of indicators from a watch list. | get_watchlist Investigation |
| Add To Watch List | Adds external domains, hostnames, or IP addresses to Darktrace's internal watch list. You can add multiple domains, hostnames, or IP addresses at a time, as comma-separated values or in a list format. | add_to_watchlist Containment |
| Remove From Watch List | Removes an external domain, hostname, or IP address from Darktrace's internal watch list. | remove_from_watchlist Remediation |
| Get Incidents | Retrieves a list of all incidents or specific incidents provided by AI Analyst events based on the input parameters you have specified. | get_incidents Investigation |
| Search Query | Retrieves 'Advanced Search' data that can be queried and got in JSON format from the Darktrace appliance based on the input parameters you have specified. | search_query Investigation |
| Get Incident Comments | Retrieves current comments on an AI Analyst event based on the UUID of the event you have specified. | get_comments Investigation |
| Acknowledge Breach | Allows breaches to be acknowledged programmatically, based on the policy breach ID (PBID) you have specified. | acknowledge_breach Investigation |
| Unacknowledge Breach | Allows breaches to be unacknowledged programmatically, based on the policy breach ID (PBID) you have specified. | unacknowledge_breach Investigation |
| Get Breach Details | Retrieve the details of the model breach based on the policy breach ID (PBID) you have specified. | get_breach_details Investigation |
| Get Model Breaches | Returns a time-sorted list of model breaches from Darktrace, based on the input parameters you have specified. | get_model_breaches Investigation |
| Get Models | Retrieves a list of all models that currently exist on the Threat Visualizer, including custom models and de-activated models based on the models' UUID or Policy ID (PID) you have specified. | get_models Investigation |
| Get Components | Retrieves a list of all component parts of defined models, identified by their component ID (CID). The CID is referenced in the data attribute for model breaches. | get_components Investigation |
| Get Devices | Retrieves a list of all devices identified by Darktrace or details of a specific device for the specified time window. If you specify a Device ID (DID), then the endpoint returns the information displayed in the UI pop-up while hovering over a device. | get_devices Investigation |
| Get Similar Devices | Retrieves a list of similar devices based on the Device ID (DID) of a specific device on the network. | get_similar_devices Investigation |
| Get External Endpoint Details | Retrieves the location, IP address, and (optionally) device connection information from Darktrace for external IPs and hostnames you have specified. | get_external_endpoint_details Investigation |
| Get Device Information | Retrieves the data used in the Connections Data view for a specific device that can be accessed from the Threat Visualizer omnisearch based on the Device ID and other input parameters you have specified. | get_device_information Investigation |
| Get Entity Details | Returns a time-sorted list of connections and events for a device or entity (such as a SaaS credential) from Darktrace based on the input parameters you have specified. | get_entity_details Investigation |
| Get Model Breach Comments | Returns all comments across all model breaches, or for a specific model breach from Darktrace based on the input parameters you have specified. | get_mb_comments Investigation |
| Create Manual Antigena | Creates a manual antigena in Darktrace using the device ID, action, and other input parameters you have specified. | create_manual_antigena Investigation |
| Get Antigena Summary | Retrieves an antigena summary from Darktrace based on the start time, end time, and other filter criteria you have specified. | get_antigena_summary Investigation |
| Get Antigena List | Retrieve a list of currently quarantined devices or Darktrace RESPOND Actions from Darktrace based on the device details, date time range, and other filter criteria that you have specified. | get_antigena Investigation |
| Update Antigena | Updates an antigena details in Darktrace based on the code ID, reason and other input parameters you have specified. | update_antigena Investigation |
None.
No output schema is available at this time.
| Parameter | Description |
|---|---|
| Domain/Hostname/IP Address (In CSV / In List) | Specify the domain(s), hostname(s), or IP address(es) that you want to add to Darktrace's internal watch list. You can add multiple domains, hostnames, or IP addresses at a time, using the CSV or list format. |
The output contains the following populated JSON schema:
{
"response": "",
"added": ""
}
| Parameter | Description |
|---|---|
| Domain/Hostname/IP Address | Specify the domain, hostname, or IP address that you want to remove from Darktrace's internal watch list. |
The output contains the following populated JSON schema:
{
"response": ""
}
| Parameter | Description |
|---|---|
| Include Acknowledged | (Optional) Select this option to include acknowledged events in the data retrieved from Darktrace. |
| Start Time | (Optional) Specify the start time from when you want to retrieve data from Darktrace, relative to midnight, January 1st, 1970 UTC. |
| End Time | (Optional) Specify the end time till when you want to retrieve data from Darktrace, relative to midnight January 1st, 1970 UTC. |
| Locale | (Optional) Select the Locale, i.e., the language for returned strings from Darktrace. Currently supported locales are de_DE (German), en_GB (English locale string UK), en_US (English US), es_ES (Spanish), es_419 (Spanish Latin America), fr_FR (French), ja_JP (Japanese), ko_KR (Korean), and pt_BR (Portuguese Brazil). |
| UUID | Specify the unique identifier of an AI Analyst event based on which you want to retrieve incidents from Darktrace. You can specify comma-separated values. |
| Merge Events | Select this option (True by default) to aggregate multiple child events (such as cross-network incidents) into a single event while retrieving data from Darktrace. |
The output contains the following populated JSON schema:
[
{
"summariser": "",
"acknowledged": "",
"pinned": "",
"createdAt": "",
"attackPhases": [],
"title": "",
"id": "",
"children": [],
"category": "",
"currentGroup": "",
"groupCategory": "",
"groupScore": "",
"groupPreviousGroups": [],
"activityId": "",
"groupingIds": [],
"groupByActivity": "",
"userTriggered": "",
"externalTriggered": "",
"aiaScore": "",
"summary": "",
"periods": [
{
"start": "",
"end": ""
}
],
"breachDevices": [
{
"identifier": "",
"hostname": "",
"ip": "",
"mac": "",
"subnet": "",
"did": "",
"sid": ""
}
],
"relatedBreaches": [
{
"modelName": "",
"pbid": "",
"threatScore": "",
"timestamp": ""
}
],
"details": [
[
{
"header": "",
"contents": [
{
"key": "",
"type": "",
"values": [
{
"start": "",
"end": ""
}
]
}
]
}
]
]
}
]
| Parameter | Description |
|---|---|
| Time Selection | Select the option of time selection to retrieve data from the Darktrace server. You can choose from the following options:
|
| Search Query | (Optional) Specify the 'Advanced Search' search query using which to search for data on the Darktrace server.
Note: Ensure that all double quotes are escaped. For example: @type:"ssl" AND @fields.dest_port:"443"
|
| Offset | (Optional) Specify the count of records to skip when retrieving results. The offset works with the 'Size' parameter to determine how many records to retrieve starting from the offset. |
| Size | (Optional) Specify the number of records to return in a single search. |
The output contains the following populated JSON schema:
{
"took": "",
"timed_out": "",
"_shards": {
"total": "",
"successful": "",
"skipped": "",
"failed": ""
},
"hits": {
"total": "",
"max_score": "",
"hits": [
{
"_index": "",
"_type": "",
"_id": "",
"_score": "",
"_source": {
"@fields": {
"orig_pkts": "",
"epochdate": "",
"orig_ttl": "",
"resp_bytes": "",
"conn_state_full": "",
"dest_port": "",
"conn_state": "",
"orig_bytes": "",
"resp_ip_bytes": "",
"history": "",
"source_port": "",
"proto": "",
"source_ip": "",
"resp_pkts": "",
"orig_ip_bytes": "",
"dest_ip": "",
"start_ts": "",
"missed_bytes_orig": "",
"uid": "",
"missed_bytes_resp": "",
"local_resp": "",
"local_orig": "",
"duration": ""
},
"@type": "",
"@timestamp": "",
"@message": "",
"@darktrace_probe": ""
},
"sort": []
}
]
},
"darktraceChildError": "",
"kibana": {
"index": [],
"per_page": "",
"time": {
"from": "",
"to": ""
},
"default_fields": []
}
}
| Parameter | Description |
|---|---|
| Incident ID | Specify the unique identifier for the AI Analyst event whose current comments you want to retrieve from Darktrace.
NOTE: Only one value is supported at a time, i.e., you can specify a single UUID only for a single operation. |
The output contains the following populated JSON schema:
{
"comments": [
{
"username": "",
"time": "",
"incident_id": "",
"message": ""
}
]
}
| Parameter | Description |
|---|---|
| Policy Breach ID(PBID) | Specify the Policy Breach ID that you want to acknowledge in Darktrace. |
The output contains the following populated JSON schema:
{
"response": ""
}
| Parameter | Description |
|---|---|
| Policy Breach ID(PBID) | Specify the Policy Breach ID that you want to unacknowledge in Darktrace. |
The output contains the following populated JSON schema:
{
"response": ""
}
| Parameter | Description |
|---|---|
| Policy Breach ID(PBID) | Specify the Policy Breach ID based on which you want to retrieve the details of the model breach from Darktrace. |
The output contains the following populated JSON schema:
{
"commentCount": "",
"pbid": "",
"time": "",
"creationTime": "",
"model": {
"then": {
"name": "",
"pid": "",
"phid": "",
"uuid": "",
"logic": {
"data": [
{
"cid": "",
"weight": ""
}
],
"targetScore": "",
"type": "",
"version": ""
},
"throttle": "",
"sharedEndpoints": "",
"actions": {
"alert": "",
"antigena": {},
"breach": "",
"model": "",
"setPriority": "",
"setTag": "",
"setType": ""
},
"tags": [],
"interval": "",
"delay": "",
"sequenced": "",
"active": "",
"modified": "",
"activeTimes": {
"devices": {},
"tags": {},
"type": "",
"version": ""
},
"autoUpdatable": "",
"autoUpdate": "",
"autoSuppress": "",
"description": "",
"behaviour": "",
"created": {
"by": ""
},
"edited": {
"by": ""
},
"version": "",
"priority": "",
"category": "",
"compliance": ""
},
"now": {
"name": "",
"pid": "",
"phid": "",
"uuid": "",
"logic": {
"data": [
{
"cid": "",
"weight": ""
}
],
"targetScore": "",
"type": "",
"version": ""
},
"throttle": "",
"sharedEndpoints": "",
"actions": {
"alert": "",
"antigena": {},
"breach": "",
"model": "",
"setPriority": "",
"setTag": "",
"setType": ""
},
"tags": [],
"interval": "",
"delay": "",
"sequenced": "",
"active": "",
"modified": "",
"activeTimes": {
"devices": {},
"tags": {},
"type": "",
"version": ""
},
"autoUpdatable": "",
"autoUpdate": "",
"autoSuppress": "",
"description": "",
"behaviour": "",
"created": {
"by": ""
},
"edited": {
"by": ""
},
"message": "",
"version": "",
"priority": "",
"category": "",
"compliance": ""
}
},
"triggeredComponents": [
{
"time": "",
"cbid": "",
"cid": "",
"chid": "",
"size": "",
"threshold": "",
"interval": "",
"logic": {
"data": {},
"version": ""
},
"metric": {
"mlid": "",
"name": "",
"label": ""
},
"triggeredFilters": [
{
"cfid": "",
"id": "",
"filterType": "",
"arguments": {
"value": ""
},
"comparatorType": "",
"trigger": {
"value": ""
}
}
]
}
],
"score": "",
"device": {
"did": "",
"macaddress": "",
"vendor": "",
"ip": "",
"sid": "",
"hostname": "",
"firstSeen": "",
"lastSeen": "",
"typename": "",
"typelabel": "",
"credentials": []
}
}
| Parameter | Description |
|---|---|
| Device ID(DID) | (Optional) Specify the identification number of a device modeled in the Darktrace system whose breach details you want to retrieve from Darktrace. |
| Start Time | (Optional) Specify the start time from when you want to retrieve data from Darktrace, relative to midnight January 1st, 1970 UTC |
| End Time | (Optional) Specify the end time till when you want to retrieve data from Darktrace, relative to midnight January 1st, 1970 UTC. |
| Include Acknowledged | (Optional) Select this option to include acknowledged breaches in the data retrieved from Darktrace. |
| Include Breach URL | (Optional) Select this option to return a URL for the model breach in the long form of the model breach data. |
| Policy Breach ID(PBID) | (Optional) Specify the Policy Breach ID if you want to return only the model breach with the specified PBID. |
| Policy ID(PID) | (Optional) Specify the Policy Breach ID if you want to return only the model breach with the specified PBID. |
| UUID | (Optional) Specify the UUID of the model if you want to return only the model breaches for the specified model. All models have a UUID and a PID. The UUID (universally unique identifier) is a 128-bit hexadecimal number. |
The output contains the following populated JSON schema:
[
{
"pbid": "",
"time": "",
"model": {
"now": {
"pid": "",
"name": "",
"phid": "",
"tags": [],
"uuid": "",
"delay": "",
"logic": {
"data": [
{
"cid": "",
"weight": ""
}
],
"type": "",
"version": "",
"targetScore": ""
},
"active": "",
"edited": {
"by": ""
},
"actions": {
"alert": "",
"model": "",
"breach": "",
"setTag": "",
"setType": "",
"antigena": {},
"setPriority": ""
},
"created": {
"by": ""
},
"defeats": [],
"message": "",
"version": "",
"category": "",
"interval": "",
"modified": "",
"priority": "",
"throttle": "",
"behaviour": "",
"sequenced": "",
"autoUpdate": "",
"compliance": "",
"activeTimes": {
"tags": {},
"type": "",
"devices": {},
"version": ""
},
"description": "",
"autoSuppress": "",
"autoUpdatable": "",
"sharedEndpoints": ""
},
"then": {
"pid": "",
"name": "",
"phid": "",
"tags": [],
"uuid": "",
"delay": "",
"logic": {
"data": [
{
"cid": "",
"weight": ""
}
],
"type": "",
"version": "",
"targetScore": ""
},
"active": "",
"edited": {
"by": ""
},
"actions": {
"alert": "",
"model": "",
"breach": "",
"setTag": "",
"setType": "",
"antigena": {},
"setPriority": ""
},
"created": {
"by": ""
},
"version": "",
"category": "",
"interval": "",
"modified": "",
"priority": "",
"throttle": "",
"behaviour": "",
"sequenced": "",
"autoUpdate": "",
"compliance": "",
"activeTimes": {
"tags": {},
"type": "",
"devices": {},
"version": ""
},
"description": "",
"autoSuppress": "",
"autoUpdatable": "",
"sharedEndpoints": ""
}
},
"score": "",
"device": {
"ip": "",
"did": "",
"ips": [
{
"ip": "",
"sid": "",
"time": "",
"timems": ""
}
],
"sid": "",
"vendor": "",
"hostname": "",
"lastSeen": "",
"typename": "",
"firstSeen": "",
"typelabel": "",
"macaddress": ""
},
"acknowledged": "",
"commentCount": "",
"creationTime": "",
"triggeredComponents": [
{
"cid": "",
"cbid": "",
"chid": "",
"size": "",
"time": "",
"logic": {},
"metric": {
"mlid": "",
"name": "",
"label": ""
},
"interval": "",
"threshold": "",
"triggeredFilters": [
{
"id": "",
"cfid": "",
"trigger": {
"value": ""
},
"arguments": {
"value": ""
},
"filterType": "",
"comparatorType": ""
}
]
}
]
}
]
| Parameter | Description |
|---|---|
| Get Models by | (Optional) Select the parameter using which you want to retrieve the list of all models that currently exist on the Threat Visualizer. You can choose from the following options:
|
The output contains the following populated JSON schema:
[
{
"name": "",
"pid": "",
"phid": "",
"uuid": "",
"logic": {
"data": [
{
"cid": "",
"weight": ""
}
],
"targetScore": "",
"type": "",
"version": ""
},
"throttle": "",
"sharedEndpoints": "",
"actions": {
"alert": "",
"antigena": {},
"breach": "",
"model": "",
"setPriority": "",
"setTag": "",
"setType": ""
},
"tags": [],
"interval": "",
"delay": "",
"sequenced": "",
"active": "",
"modified": "",
"activeTimes": {
"devices": {},
"tags": {},
"type": "",
"version": ""
},
"autoUpdatable": "",
"autoUpdate": "",
"autoSuppress": "",
"description": "",
"behaviour": "",
"created": {
"by": ""
},
"edited": {
"by": ""
},
"history": [
{
"modified": "",
"active": "",
"message": "",
"by": "",
"phid": ""
}
],
"message": "",
"version": "",
"priority": "",
"category": "",
"compliance": ""
}
]
| Parameter | Description |
|---|---|
| Component ID(CID) | (Optional) Specify the component ID (a unique identifier) of the model whose details you want to retrieve from Darktrace. |
The output contains the following populated JSON schema:
[
{
"cid": "",
"chid": "",
"mlid": "",
"threshold": "",
"interval": "",
"logic": {},
"filters": [
{
"id": "",
"cfid": "",
"cfhid": "",
"filtertype": "",
"comparator": "",
"arguments": {
"value": ""
}
}
],
"active": ""
}
]
| Parameter | Description |
|---|---|
| Device ID(DID) | (Optional) Specify the identification number of a device modeled in the Darktrace system whose details you want to retrieve from Darktrace. |
| IP | (Optional) Specify the IP address of the device model in the Darktrace system whose details you want to retrieve from Darktrace |
| Seen Since | (Optional) Specify the relative offset for activity, i.e., devices with activity in the specified time period are returned from Darktrace. The format is either a number representing the number of seconds before the current time or a number with a modifier such as second, minute, hour, day, or week (Minimum allowed value is 1 second). |
| MAC | (Optional) Specify the MAC address of the device whose details you want to retrieve from Darktrace. |
| Subnet ID(SID) | (Optional) Specify the identification number of a subnet modeled in the Darktrace system that contains the device whose details you want to retrieve from Darktrace. |
| Count | (Optional) Specify the maximum number of devices to return. This only limits the number of devices within the current time frame. |
| Include Tags | (Optional) Select this option to include tags applied to the device in the response. |
The output contains the following populated JSON schema:
Output schema when you choose Include Tags as true:
[
{
"id": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"did": "",
"sid": "",
"time": "",
"endtime": "",
"tags": [
{
"tid": "",
"expiry": "",
"thid": "",
"name": "",
"restricted": "",
"data": {
"auto": "",
"color": "",
"description": ""
},
"isReferenced": ""
}
],
"typename": "",
"typelabel": ""
}
]
Output schema when you choose Include Tags as false:
[
{
"id": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"did": "",
"sid": "",
"time": "",
"endtime": "",
"typename": "",
"typelabel": ""
}
]
| Parameter | Description |
|---|---|
| Device ID(DID) | Specify the Device ID (unique identifier) of a specific device on the network, based on which you want to retrieve similar devices from Darktrace. |
| Count | (Optional) Specify the maximum number of devices to return. This only limits the number of devices within the current time frame. |
| Full Device Details | (Optional) Select this option to return the full device detail objects for all devices referenced by data in the API response. |
The output contains the following populated JSON schema:
Output schema when you choose Full Device Details as true:
[
{
"did": "",
"score": "",
"macaddress": "",
"vendor": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"firstSeen": "",
"lastSeen": "",
"typename": "",
"typelabel": "",
"tags": [
{
"tid": "",
"expiry": "",
"thid": "",
"name": "",
"restricted": "",
"data": {
"auto": "",
"color": "",
"description": ""
},
"isReferenced": ""
}
]
}
]
Output schema when you choose Full Device Details as false:
[
{
"did": "",
"score": "",
"macaddress": "",
"vendor": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"firstSeen": "",
"lastSeen": "",
"typename": "",
"typelabel": ""
}
]
| Parameter | Description |
|---|---|
| Get Endpoints by | Select the parameter using which you want to get external endpoints details. You can choose from following options:
|
| Score | (Optional) Select this option to return rarity data for the endpoints in the response. |
| Devices | (Optional) Select this option to return a list of devices that have recently connected to the endpoint in the response. |
Output schema when you select:
truetrue
{
"ip": "",
"firsttime": "",
"country": "",
"asn": "",
"city": "",
"region": "",
"name": "",
"longitude": "",
"latitude": "",
"popularity": "",
"devices": [
{
"did": "",
"macaddress": "",
"vendor": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"firstSeen": "",
"lastSeen": "",
"typename": "",
"typelabel": ""
}
]
}
Output schema when:
truefalse
{
"ip": "",
"asn": "",
"city": "",
"name": "",
"region": "",
"country": "",
"devices": [
{
"ip": "",
"did": "",
"ips": [
{
"ip": "",
"sid": "",
"time": "",
"timems": ""
}
],
"sid": "",
"vendor": "",
"lastSeen": "",
"typename": "",
"firstSeen": "",
"typelabel": "",
"macaddress": ""
}
],
"latitude": "",
"firsttime": "",
"longitude": ""
}
Output schema when:
truefalse
{
"ip": "",
"firsttime": "",
"country": "",
"asn": "",
"city": "",
"region": "",
"name": "",
"longitude": "",
"latitude": "",
"popularity": ""
}
Output schema when:
falsefalse
{
"ip": "",
"firsttime": "",
"country": "",
"asn": "",
"city": "",
"region": "",
"name": "",
"longitude": "",
"latitude": ""
}
Output schema when:
truetruetrue
{
"hostname": "",
"firsttime": "",
"devices": [
{
"did": "",
"macaddress": "",
"vendor": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"firstSeen": "",
"lastSeen": "",
"devicelabel": "",
"typename": "",
"typelabel": ""
}
],
"ips": [
{
"ip": "",
"firsttime": "",
"lasttime": ""
}
],
"locations": [
{
"latitude": "",
"longitude": "",
"country": "",
"city": ""
}
],
"popularity": "",
"dgascore": ""
}
Output schema when:
truetruefalse
{
"hostname": "",
"firsttime": "",
"devices": [
{
"did": "",
"macaddress": "",
"vendor": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"firstSeen": "",
"lastSeen": "",
"devicelabel": "",
"typename": "",
"typelabel": ""
}
],
"ips": [
{
"ip": "",
"firsttime": "",
"lasttime": ""
}
],
"locations": [
{
"latitude": "",
"longitude": "",
"country": "",
"city": ""
}
]
}
Output schema when:
falsetruetrue
{
"hostname": "",
"firsttime": "",
"ips": [
{
"ip": "",
"firsttime": "",
"lasttime": ""
}
],
"locations": [
{
"latitude": "",
"longitude": "",
"country": "",
"city": ""
}
],
"popularity": "",
"dgascore": ""
}
Output schema when:
falsetruefalse
{
"hostname": "",
"firsttime": "",
"ips": [
{
"ip": "",
"firsttime": "",
"lasttime": ""
}
],
"locations": [
{
"latitude": "",
"longitude": "",
"country": "",
"city": ""
}
]
}
Output schema when:
truefalsefalse
{
"hostname": "",
"firsttime": "",
"devices": [
{
"did": "",
"macaddress": "",
"vendor": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"firstSeen": "",
"lastSeen": "",
"devicelabel": "",
"typename": "",
"typelabel": ""
}
]
}
Output schema when:
falsefalsetrue
{
"hostname": "",
"firsttime": "",
"popularity": "",
"dgascore": ""
}
Output schema when:
falsefalsetrue
{
"hostname": "",
"firsttime": "",
"popularity": "",
"dgascore": ""
}
If you choose Get Endpoints by as Hostname and Devices as false, then the output contains the following populated JSON schema:
{
"hostname": "",
"firsttime": ""
}
| Parameter | Description |
|---|---|
| Device ID(DID) | Specify the identification number of a device modeled in the Darktrace system whose details you want to retrieve from Darktrace. |
| Data Type | Select the type of data you want to retrieve for the specified device from Darktrace. You can choose from the following options:
|
| External Domain | (Optional) Specify the domain name based on which you want to filter external domains for devices whose details you want to retrieve from Darktrace. |
| Full Device Details | (Optional) Select this option to return the full device detail objects for all devices referenced by data in an API response. The use of this parameter alters the JSON structure of the API response for certain calls. |
| Show All Graph Data | (Optional) Select this option to return an entry for all time intervals in the graph data, including zero counts. |
| Similar Devices | (Optional) Specify the number of similar devices whose details you want to retrieve from Darktrace. This parameter returns data for the primary device and the specified number of similar devices. |
| Port | (Optional) Specify the port number if you want to restrict the returned connection data to the port you have specified. |
| Interval Hours | (Optional) Specify the size in hours used to group the returned time series data. |
The output contains the following populated JSON schema:
Output schema when you choose Show All Graph Data as true:
{
"deviceInfo": [
{
"did": "",
"similarityScore": "",
"graphData": [
{
"time": "",
"count": ""
}
],
"info": {
"totalUsed": "",
"totalServed": "",
"totalDevicesAndPorts": "",
"devicesAndPorts": [
{
"deviceAndPort": {
"direction": "",
"device": "",
"port": ""
},
"size": ""
}
],
"portsUsed": [
{
"port": "",
"size": "",
"firstTime": ""
}
],
"portsServed": [
{
"port": "",
"size": ""
}
],
"devicesUsed": [
{
"did": "",
"size": "",
"firstTime": ""
}
],
"devicesServed": [
{
"did": "",
"size": ""
}
]
}
}
]
}
Output schema when you choose Show All Graph Data as false:
{
"deviceInfo": [
{
"did": "",
"similarityScore": "",
"graphData": [],
"info": {
"totalUsed": "",
"totalServed": "",
"totalDevicesAndPorts": "",
"devicesAndPorts": [
{
"deviceAndPort": {
"direction": "",
"device": "",
"port": ""
},
"size": ""
}
],
"portsUsed": [
{
"port": "",
"size": "",
"firstTime": ""
}
],
"portsServed": [
{
"port": "",
"size": ""
}
],
"devicesUsed": [
{
"did": "",
"size": "",
"firstTime": ""
}
],
"devicesServed": [
{
"did": "",
"size": ""
}
]
}
}
]
}
This is the default output schema:
{
"deviceInfo": [
{
"did": "",
"similarityScore": "",
"graphData": [
{
"time": "",
"count": ""
}
],
"info": {
"totalUsed": "",
"totalServed": "",
"totalDevicesAndPorts": "",
"devicesAndPorts": [
{
"deviceAndPort": {
"direction": "",
"device": "",
"port": ""
},
"size": ""
}
],
"portsUsed": [
{
"port": "",
"size": "",
"firstTime": ""
}
],
"portsServed": [
{
"port": "",
"size": ""
}
],
"devicesUsed": [
{
"did": "",
"size": "",
"firstTime": ""
}
],
"devicesServed": [
{
"did": "",
"size": ""
}
]
}
}
]
}
| Parameter | Description |
|---|---|
| Device ID(DID) | Specify the identification number of a device modeled in the Darktrace system whose entity details you want to retrieve from Darktace |
| Application Protocol | (Optional) Specify the application protocol using which you want to filter data returned by this operation. |
| Destination Device ID(DDID) | (Optional) Specify the identification number of a destination device modeled in the Darktrace system using which you want to filter data returned by this operation. |
| Deduplicate | (Optional) Select this option to display only one equivalent connection per hour. |
| Port | (Optional) Specify the port number if you want to filter the returned data by source or destination port. |
| Start Time | (Optional) Specify the start time from when you want to retrieve data from Darktrace. |
| End Time | (Optional) Specify the end time till when you want to retrieve data from Darktrace. |
| Event Type | (Optional) Specifies a type of event whose details you want to retrieve from Darktrace. You can specify the following values: connection, unusualconnection, newconnection, notice, devicehistory, or modelbreach. |
| External Hostname | (Optional) Specify an external hostname whose details you want to retrieve from Darktace |
| Full Device Details | (Optional) Select this option to return the full device detail objects for all devices referenced by data in an API response. The use of this parameter alters the JSON structure of the API response for certain calls. |
| Offset | (Optional) Specify the count of records to skip when retrieving results. |
| Count | (Optional) Specify the maximum number of items to return.
NOTE: The 'Count' parameter is ignored when the 'Start' time parameter is used. |
The output contains the following populated JSON schema:
Output schema when you choose Full Device Details as true:
[
{
"time": "",
"timems": "",
"action": "",
"eventType": "",
"uid": "",
"status": "",
"sdid": "",
"port": "",
"sourcePort": "",
"destinationPort": "",
"direction": "out",
"applicationprotocol": "",
"protocol": "",
"sourceDevice": {
"id": "",
"did": "",
"macaddress": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"time": "",
"devicelabel": "",
"typename": "",
"typelabel": ""
},
"destinationDevice": {
"longitude": "",
"latitude": "",
"city": "",
"country": "",
"countrycode": "",
"asn": "",
"region": "",
"ip": "",
"hostname": "",
"hostnamepopularity": "",
"connectionhostnamepopularity": "",
"domain": "",
"domainpopularity": "",
"connectiondomainpopularity": "",
"ippopularity": "",
"connectionippopularity": ""
},
"source": "",
"destination": ""
}
]
Output schema when you choose Full Device Details as false:
[
{
"time": "",
"timems": "",
"action": "",
"eventType": "",
"uid": "",
"sdid": "",
"ddid": "",
"port": "",
"sourcePort": "",
"destinationPort": "",
"direction": "",
"applicationprotocol": "",
"protocol": "",
"sourceDevice": {
"id": "",
"did": "",
"macaddress": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"time": "",
"devicelabel": "",
"typename": "",
"typelabel": ""
},
"destinationDevice": {
"id": "",
"did": "",
"macaddress": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"time": "",
"typename": "",
"typelabel": ""
},
"source": "",
"destination": ""
}
]
This is the default output schema:
[
{
"time": "",
"timems": "",
"action": "",
"eventType": "",
"uid": "",
"dns": {
"hostname": "",
"success": "",
"hostnamepopularity": "",
"internal": ""
},
"sdid": "",
"ddid": "",
"port": "",
"sourcePort": "",
"destinationPort": "",
"direction": "",
"applicationprotocol": "",
"protocol": "",
"sourceDevice": {
"id": "",
"did": "",
"macaddress": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"time": "",
"devicelabel": "",
"typename": "",
"typelabel": ""
},
"destinationDevice": {
"id": "",
"did": "",
"macaddress": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"time": "",
"typename": "",
"typelabel": ""
},
"source": "",
"destination": ""
}
]
| Parameter | Description |
|---|---|
| Policy Breach ID(PBID) | (Optional) Specify the Policy Breach ID to retrieve comments for the model breach with the specified ID from Darktrace. |
| Start Time | (Optional) Specify the start time from when you want to retrieve data from Darktrace. |
| End Time | (Optional) Specify the end time till when you want to retrieve data from Darktrace. |
| Count | (Optional) Specify the maximum number of comments to return. This only limits the number of comments within the current time frame. By default, it is set to 100.
NOTE: The 'Count' parameter is ignored when the 'Start' time parameter is used. |
The output contains the following populated JSON schema:
[
{
"time": "",
"pbid": "",
"username": "",
"message": "",
"pid": "",
"name": ""
}
]
| Parameter | Description |
|---|---|
| Device ID(DID) | Specify the identification number of a device modelled in the Darktrace system. |
| Action | Select the type of action to be created in the Darktrace system. You can choose from the following options:
|
| Duration | Specify the duration of the action in seconds. |
| Reason | (Optional) Specify a reason for selecting the action. |
The output contains the following populated JSON schema:
{
"code": ""
}
| Parameter | Description |
|---|---|
| Start Time | (Optional) Specify the start time from when you want to retrieve data from Darktrace. |
| End Time | (Optional) Specify the end time till when you want to retrieve data from Darktrace. |
| Response Data | (Optional) Specify the name of a top-level field or object, restricts the returned JSON to only that field or object. |
The output contains the following populated JSON schema:
{
"pendingCount": "",
"activeCount": "",
"pendingActionDevices": [],
"activeActionDevices": []
}
| Parameter | Description |
|---|---|
| Full Device Details | (Optional) Select to retrieve the full device detail objects for all devices referenced by data to return. |
| Include Cleared | (Optional) Select to retrieve all darktrace RESPOND actions including those already cleared. By default, it is cleared, i.e., set to false. |
| Include History | (Optional) Select to include additional history information about the action state, such as when it was created or extended. |
| Need Confirming | (Optional) Select to filter returned darktrace RESPOND actions by those that need human confirmation or do not need human confirmation. |
| Start Time | (Optional) Specify the start time from when you want to retrieve data from Darktrace. Start time of data to return in millisecond format, relative to midnight January 1st 1970 UTC. |
| End Time | (Optional) Specify the end time till when you want to retrieve data from Darktrace. End time of data to return in millisecond format, relative to midnight January 1st 1970 UTC. |
| From | (Optional) Specify the start time from when you want to retrieve data from Darktrace. Start time of data to return in YYYY-MM-DD HH:MM:SS format. Start time of data to return in YYYY-MM-DD HH:MM:SS format. |
| To | (Optional) Specify the end time from when you want to retrieve data from Darktrace. End time of data to return in YYYY-MM-DD HH:MM:SS format. End time of data to return in YYYY-MM-DD HH:MM:SS format. |
| Include Connections | (Optional) Select to add a connections object which returns connections blocked by a darktrace RESPOND action. |
| Response Data | (Optional) Specify the name of a top-level field or object, restricts the returned JSON to only that field or object. |
| PB ID | (Optional) Specify the ID of the model breach based on which you want to retrieve antigena from Darktrace. |
The output contains the following populated JSON schema:
{
"actions": [
{
"codeid": "",
"did": "",
"ip": "",
"action": "",
"manual": "",
"triggerer": "",
"pbid": "",
"model": "",
"modeluuid": "",
"start": "",
"expires": "",
"blocked": "",
"agemail": "",
"active": "",
"cleared": ""
}
],
"connections": [
{
"action": "",
"label": "",
"did": "",
"direction": "",
"ip": "",
"port": "",
"timems": "",
"time": ""
}
],
"devices": [
{
"did": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"firstseen": "",
"lastseen": "",
"os": "",
"typename": "",
"typelabel": "",
"tags": [
{
"tid": "",
"expiry": "",
"thid": "",
"name": "",
"restricted": "",
"data": {
"auto": "",
"color": "",
"description": ""
},
"isReferenced": ""
}
]
}
]
}
| Parameter | Description |
|---|---|
| Code ID | Specify the unique identifier for the RESPOND action whose antigena you want to update in Darktrace. |
| Activate | (Optional) Select to activate an action. Cannot be combined with Clear parameter value as True. |
| Clear | (Optional) Select to clear an action. Cannot be combined with Activate parameter value as True. |
| Reason | (Optional) Specify the reason for selecting the action. |
| Duration | (Optional) Specify how long the state change should apply for in seconds. For extensions, should contain the current duration plus the amount the action should be extended for. |
The output contains a non-dictionary value.
The Sample - Darktrace - 1.3.0 playbook collection comes bundled with the Darktrace connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Darktrace connector.
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.
Darktrace, which is Enterprise Immune System's flagship threat detection and defense capability, is based on unsupervised machine learning and probabilistic mathematics. Darktrace works by creating unique behavioral models for every user and device across the enterprises and analyzing the relationships between them.
This document provides information about the Darktrace connector, which facilitates automated interactions, with a Darktrace server using FortiSOAR™ playbooks. Add the Darktrace connector as a step in FortiSOAR™ playbooks and perform automated operations, such as adding or removing a domain, hostname, or IP address from Darktrace's internal watchlist.
Connector Version: 1.3.0
Authored By: Fortinet
Certified: No
Following enhancements have been made to the Darktrace connector in version 1.3.0:
Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command as a root user to install the connector:
yum install cyops-connector-darktrace
For the procedure to configure a connector, click here
In FortiSOAR™, on the Connectors page, click the Darktrace connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:
| Parameter | Description |
|---|---|
| Server URL | The URL of the Darktrace server to which you will connect and perform the automated operations. |
| API Public Token | The public token of the Darktrace server to which you will connect and perform the automated operations. |
| API Private Token | The private key of the Darktrace server to which you will connect and perform the automated operations. |
| Time difference (minutes) from Darktrace Server Time | Allows you to modify the current time passed (default=0) to the Darktrace API to allow for timezone differences, e.g., passing 29 will add 29 minutes to the time, and -29 will take off 29 minutes. NOTE: The maximum allowed time difference is 30 minutes. |
| Verify SSL | Specifies whether the SSL certificate for the server is to be verified. By default, this option is selected, i.e., set to true. |
You can use the following automated operations in playbooks and also use the annotations to access operations:
| Function | Description | Annotation and Category |
|---|---|---|
| Get Watch List | Retrieves a list of indicators from a watch list. | get_watchlist Investigation |
| Add To Watch List | Adds external domains, hostnames, or IP addresses to Darktrace's internal watch list. You can add multiple domains, hostnames, or IP addresses at a time, as comma-separated values or in a list format. | add_to_watchlist Containment |
| Remove From Watch List | Removes an external domain, hostname, or IP address from Darktrace's internal watch list. | remove_from_watchlist Remediation |
| Get Incidents | Retrieves a list of all incidents or specific incidents provided by AI Analyst events based on the input parameters you have specified. | get_incidents Investigation |
| Search Query | Retrieves 'Advanced Search' data that can be queried and got in JSON format from the Darktrace appliance based on the input parameters you have specified. | search_query Investigation |
| Get Incident Comments | Retrieves current comments on an AI Analyst event based on the UUID of the event you have specified. | get_comments Investigation |
| Acknowledge Breach | Allows breaches to be acknowledged programmatically, based on the policy breach ID (PBID) you have specified. | acknowledge_breach Investigation |
| Unacknowledge Breach | Allows breaches to be unacknowledged programmatically, based on the policy breach ID (PBID) you have specified. | unacknowledge_breach Investigation |
| Get Breach Details | Retrieve the details of the model breach based on the policy breach ID (PBID) you have specified. | get_breach_details Investigation |
| Get Model Breaches | Returns a time-sorted list of model breaches from Darktrace, based on the input parameters you have specified. | get_model_breaches Investigation |
| Get Models | Retrieves a list of all models that currently exist on the Threat Visualizer, including custom models and de-activated models based on the models' UUID or Policy ID (PID) you have specified. | get_models Investigation |
| Get Components | Retrieves a list of all component parts of defined models, identified by their component ID (CID). The CID is referenced in the data attribute for model breaches. | get_components Investigation |
| Get Devices | Retrieves a list of all devices identified by Darktrace or details of a specific device for the specified time window. If you specify a Device ID (DID), then the endpoint returns the information displayed in the UI pop-up while hovering over a device. | get_devices Investigation |
| Get Similar Devices | Retrieves a list of similar devices based on the Device ID (DID) of a specific device on the network. | get_similar_devices Investigation |
| Get External Endpoint Details | Retrieves the location, IP address, and (optionally) device connection information from Darktrace for external IPs and hostnames you have specified. | get_external_endpoint_details Investigation |
| Get Device Information | Retrieves the data used in the Connections Data view for a specific device that can be accessed from the Threat Visualizer omnisearch based on the Device ID and other input parameters you have specified. | get_device_information Investigation |
| Get Entity Details | Returns a time-sorted list of connections and events for a device or entity (such as a SaaS credential) from Darktrace based on the input parameters you have specified. | get_entity_details Investigation |
| Get Model Breach Comments | Returns all comments across all model breaches, or for a specific model breach from Darktrace based on the input parameters you have specified. | get_mb_comments Investigation |
| Create Manual Antigena | Creates a manual antigena in Darktrace using the device ID, action, and other input parameters you have specified. | create_manual_antigena Investigation |
| Get Antigena Summary | Retrieves an antigena summary from Darktrace based on the start time, end time, and other filter criteria you have specified. | get_antigena_summary Investigation |
| Get Antigena List | Retrieve a list of currently quarantined devices or Darktrace RESPOND Actions from Darktrace based on the device details, date time range, and other filter criteria that you have specified. | get_antigena Investigation |
| Update Antigena | Updates an antigena details in Darktrace based on the code ID, reason and other input parameters you have specified. | update_antigena Investigation |
None.
No output schema is available at this time.
| Parameter | Description |
|---|---|
| Domain/Hostname/IP Address (In CSV / In List) | Specify the domain(s), hostname(s), or IP address(es) that you want to add to Darktrace's internal watch list. You can add multiple domains, hostnames, or IP addresses at a time, using the CSV or list format. |
The output contains the following populated JSON schema:
{
"response": "",
"added": ""
}
| Parameter | Description |
|---|---|
| Domain/Hostname/IP Address | Specify the domain, hostname, or IP address that you want to remove from Darktrace's internal watch list. |
The output contains the following populated JSON schema:
{
"response": ""
}
| Parameter | Description |
|---|---|
| Include Acknowledged | (Optional) Select this option to include acknowledged events in the data retrieved from Darktrace. |
| Start Time | (Optional) Specify the start time from when you want to retrieve data from Darktrace, relative to midnight, January 1st, 1970 UTC. |
| End Time | (Optional) Specify the end time till when you want to retrieve data from Darktrace, relative to midnight January 1st, 1970 UTC. |
| Locale | (Optional) Select the Locale, i.e., the language for returned strings from Darktrace. Currently supported locales are de_DE (German), en_GB (English locale string UK), en_US (English US), es_ES (Spanish), es_419 (Spanish Latin America), fr_FR (French), ja_JP (Japanese), ko_KR (Korean), and pt_BR (Portuguese Brazil). |
| UUID | Specify the unique identifier of an AI Analyst event based on which you want to retrieve incidents from Darktrace. You can specify comma-separated values. |
| Merge Events | Select this option (True by default) to aggregate multiple child events (such as cross-network incidents) into a single event while retrieving data from Darktrace. |
The output contains the following populated JSON schema:
[
{
"summariser": "",
"acknowledged": "",
"pinned": "",
"createdAt": "",
"attackPhases": [],
"title": "",
"id": "",
"children": [],
"category": "",
"currentGroup": "",
"groupCategory": "",
"groupScore": "",
"groupPreviousGroups": [],
"activityId": "",
"groupingIds": [],
"groupByActivity": "",
"userTriggered": "",
"externalTriggered": "",
"aiaScore": "",
"summary": "",
"periods": [
{
"start": "",
"end": ""
}
],
"breachDevices": [
{
"identifier": "",
"hostname": "",
"ip": "",
"mac": "",
"subnet": "",
"did": "",
"sid": ""
}
],
"relatedBreaches": [
{
"modelName": "",
"pbid": "",
"threatScore": "",
"timestamp": ""
}
],
"details": [
[
{
"header": "",
"contents": [
{
"key": "",
"type": "",
"values": [
{
"start": "",
"end": ""
}
]
}
]
}
]
]
}
]
| Parameter | Description |
|---|---|
| Time Selection | Select the option of time selection to retrieve data from the Darktrace server. You can choose from the following options:
|
| Search Query | (Optional) Specify the 'Advanced Search' search query using which to search for data on the Darktrace server.
Note: Ensure that all double quotes are escaped. For example: @type:"ssl" AND @fields.dest_port:"443"
|
| Offset | (Optional) Specify the count of records to skip when retrieving results. The offset works with the 'Size' parameter to determine how many records to retrieve starting from the offset. |
| Size | (Optional) Specify the number of records to return in a single search. |
The output contains the following populated JSON schema:
{
"took": "",
"timed_out": "",
"_shards": {
"total": "",
"successful": "",
"skipped": "",
"failed": ""
},
"hits": {
"total": "",
"max_score": "",
"hits": [
{
"_index": "",
"_type": "",
"_id": "",
"_score": "",
"_source": {
"@fields": {
"orig_pkts": "",
"epochdate": "",
"orig_ttl": "",
"resp_bytes": "",
"conn_state_full": "",
"dest_port": "",
"conn_state": "",
"orig_bytes": "",
"resp_ip_bytes": "",
"history": "",
"source_port": "",
"proto": "",
"source_ip": "",
"resp_pkts": "",
"orig_ip_bytes": "",
"dest_ip": "",
"start_ts": "",
"missed_bytes_orig": "",
"uid": "",
"missed_bytes_resp": "",
"local_resp": "",
"local_orig": "",
"duration": ""
},
"@type": "",
"@timestamp": "",
"@message": "",
"@darktrace_probe": ""
},
"sort": []
}
]
},
"darktraceChildError": "",
"kibana": {
"index": [],
"per_page": "",
"time": {
"from": "",
"to": ""
},
"default_fields": []
}
}
| Parameter | Description |
|---|---|
| Incident ID | Specify the unique identifier for the AI Analyst event whose current comments you want to retrieve from Darktrace.
NOTE: Only one value is supported at a time, i.e., you can specify a single UUID only for a single operation. |
The output contains the following populated JSON schema:
{
"comments": [
{
"username": "",
"time": "",
"incident_id": "",
"message": ""
}
]
}
| Parameter | Description |
|---|---|
| Policy Breach ID(PBID) | Specify the Policy Breach ID that you want to acknowledge in Darktrace. |
The output contains the following populated JSON schema:
{
"response": ""
}
| Parameter | Description |
|---|---|
| Policy Breach ID(PBID) | Specify the Policy Breach ID that you want to unacknowledge in Darktrace. |
The output contains the following populated JSON schema:
{
"response": ""
}
| Parameter | Description |
|---|---|
| Policy Breach ID(PBID) | Specify the Policy Breach ID based on which you want to retrieve the details of the model breach from Darktrace. |
The output contains the following populated JSON schema:
{
"commentCount": "",
"pbid": "",
"time": "",
"creationTime": "",
"model": {
"then": {
"name": "",
"pid": "",
"phid": "",
"uuid": "",
"logic": {
"data": [
{
"cid": "",
"weight": ""
}
],
"targetScore": "",
"type": "",
"version": ""
},
"throttle": "",
"sharedEndpoints": "",
"actions": {
"alert": "",
"antigena": {},
"breach": "",
"model": "",
"setPriority": "",
"setTag": "",
"setType": ""
},
"tags": [],
"interval": "",
"delay": "",
"sequenced": "",
"active": "",
"modified": "",
"activeTimes": {
"devices": {},
"tags": {},
"type": "",
"version": ""
},
"autoUpdatable": "",
"autoUpdate": "",
"autoSuppress": "",
"description": "",
"behaviour": "",
"created": {
"by": ""
},
"edited": {
"by": ""
},
"version": "",
"priority": "",
"category": "",
"compliance": ""
},
"now": {
"name": "",
"pid": "",
"phid": "",
"uuid": "",
"logic": {
"data": [
{
"cid": "",
"weight": ""
}
],
"targetScore": "",
"type": "",
"version": ""
},
"throttle": "",
"sharedEndpoints": "",
"actions": {
"alert": "",
"antigena": {},
"breach": "",
"model": "",
"setPriority": "",
"setTag": "",
"setType": ""
},
"tags": [],
"interval": "",
"delay": "",
"sequenced": "",
"active": "",
"modified": "",
"activeTimes": {
"devices": {},
"tags": {},
"type": "",
"version": ""
},
"autoUpdatable": "",
"autoUpdate": "",
"autoSuppress": "",
"description": "",
"behaviour": "",
"created": {
"by": ""
},
"edited": {
"by": ""
},
"message": "",
"version": "",
"priority": "",
"category": "",
"compliance": ""
}
},
"triggeredComponents": [
{
"time": "",
"cbid": "",
"cid": "",
"chid": "",
"size": "",
"threshold": "",
"interval": "",
"logic": {
"data": {},
"version": ""
},
"metric": {
"mlid": "",
"name": "",
"label": ""
},
"triggeredFilters": [
{
"cfid": "",
"id": "",
"filterType": "",
"arguments": {
"value": ""
},
"comparatorType": "",
"trigger": {
"value": ""
}
}
]
}
],
"score": "",
"device": {
"did": "",
"macaddress": "",
"vendor": "",
"ip": "",
"sid": "",
"hostname": "",
"firstSeen": "",
"lastSeen": "",
"typename": "",
"typelabel": "",
"credentials": []
}
}
| Parameter | Description |
|---|---|
| Device ID(DID) | (Optional) Specify the identification number of a device modeled in the Darktrace system whose breach details you want to retrieve from Darktrace. |
| Start Time | (Optional) Specify the start time from when you want to retrieve data from Darktrace, relative to midnight January 1st, 1970 UTC |
| End Time | (Optional) Specify the end time till when you want to retrieve data from Darktrace, relative to midnight January 1st, 1970 UTC. |
| Include Acknowledged | (Optional) Select this option to include acknowledged breaches in the data retrieved from Darktrace. |
| Include Breach URL | (Optional) Select this option to return a URL for the model breach in the long form of the model breach data. |
| Policy Breach ID(PBID) | (Optional) Specify the Policy Breach ID if you want to return only the model breach with the specified PBID. |
| Policy ID(PID) | (Optional) Specify the Policy Breach ID if you want to return only the model breach with the specified PBID. |
| UUID | (Optional) Specify the UUID of the model if you want to return only the model breaches for the specified model. All models have a UUID and a PID. The UUID (universally unique identifier) is a 128-bit hexadecimal number. |
The output contains the following populated JSON schema:
[
{
"pbid": "",
"time": "",
"model": {
"now": {
"pid": "",
"name": "",
"phid": "",
"tags": [],
"uuid": "",
"delay": "",
"logic": {
"data": [
{
"cid": "",
"weight": ""
}
],
"type": "",
"version": "",
"targetScore": ""
},
"active": "",
"edited": {
"by": ""
},
"actions": {
"alert": "",
"model": "",
"breach": "",
"setTag": "",
"setType": "",
"antigena": {},
"setPriority": ""
},
"created": {
"by": ""
},
"defeats": [],
"message": "",
"version": "",
"category": "",
"interval": "",
"modified": "",
"priority": "",
"throttle": "",
"behaviour": "",
"sequenced": "",
"autoUpdate": "",
"compliance": "",
"activeTimes": {
"tags": {},
"type": "",
"devices": {},
"version": ""
},
"description": "",
"autoSuppress": "",
"autoUpdatable": "",
"sharedEndpoints": ""
},
"then": {
"pid": "",
"name": "",
"phid": "",
"tags": [],
"uuid": "",
"delay": "",
"logic": {
"data": [
{
"cid": "",
"weight": ""
}
],
"type": "",
"version": "",
"targetScore": ""
},
"active": "",
"edited": {
"by": ""
},
"actions": {
"alert": "",
"model": "",
"breach": "",
"setTag": "",
"setType": "",
"antigena": {},
"setPriority": ""
},
"created": {
"by": ""
},
"version": "",
"category": "",
"interval": "",
"modified": "",
"priority": "",
"throttle": "",
"behaviour": "",
"sequenced": "",
"autoUpdate": "",
"compliance": "",
"activeTimes": {
"tags": {},
"type": "",
"devices": {},
"version": ""
},
"description": "",
"autoSuppress": "",
"autoUpdatable": "",
"sharedEndpoints": ""
}
},
"score": "",
"device": {
"ip": "",
"did": "",
"ips": [
{
"ip": "",
"sid": "",
"time": "",
"timems": ""
}
],
"sid": "",
"vendor": "",
"hostname": "",
"lastSeen": "",
"typename": "",
"firstSeen": "",
"typelabel": "",
"macaddress": ""
},
"acknowledged": "",
"commentCount": "",
"creationTime": "",
"triggeredComponents": [
{
"cid": "",
"cbid": "",
"chid": "",
"size": "",
"time": "",
"logic": {},
"metric": {
"mlid": "",
"name": "",
"label": ""
},
"interval": "",
"threshold": "",
"triggeredFilters": [
{
"id": "",
"cfid": "",
"trigger": {
"value": ""
},
"arguments": {
"value": ""
},
"filterType": "",
"comparatorType": ""
}
]
}
]
}
]
| Parameter | Description |
|---|---|
| Get Models by | (Optional) Select the parameter using which you want to retrieve the list of all models that currently exist on the Threat Visualizer. You can choose from the following options:
|
The output contains the following populated JSON schema:
[
{
"name": "",
"pid": "",
"phid": "",
"uuid": "",
"logic": {
"data": [
{
"cid": "",
"weight": ""
}
],
"targetScore": "",
"type": "",
"version": ""
},
"throttle": "",
"sharedEndpoints": "",
"actions": {
"alert": "",
"antigena": {},
"breach": "",
"model": "",
"setPriority": "",
"setTag": "",
"setType": ""
},
"tags": [],
"interval": "",
"delay": "",
"sequenced": "",
"active": "",
"modified": "",
"activeTimes": {
"devices": {},
"tags": {},
"type": "",
"version": ""
},
"autoUpdatable": "",
"autoUpdate": "",
"autoSuppress": "",
"description": "",
"behaviour": "",
"created": {
"by": ""
},
"edited": {
"by": ""
},
"history": [
{
"modified": "",
"active": "",
"message": "",
"by": "",
"phid": ""
}
],
"message": "",
"version": "",
"priority": "",
"category": "",
"compliance": ""
}
]
| Parameter | Description |
|---|---|
| Component ID(CID) | (Optional) Specify the component ID (a unique identifier) of the model whose details you want to retrieve from Darktrace. |
The output contains the following populated JSON schema:
[
{
"cid": "",
"chid": "",
"mlid": "",
"threshold": "",
"interval": "",
"logic": {},
"filters": [
{
"id": "",
"cfid": "",
"cfhid": "",
"filtertype": "",
"comparator": "",
"arguments": {
"value": ""
}
}
],
"active": ""
}
]
| Parameter | Description |
|---|---|
| Device ID(DID) | (Optional) Specify the identification number of a device modeled in the Darktrace system whose details you want to retrieve from Darktrace. |
| IP | (Optional) Specify the IP address of the device model in the Darktrace system whose details you want to retrieve from Darktrace |
| Seen Since | (Optional) Specify the relative offset for activity, i.e., devices with activity in the specified time period are returned from Darktrace. The format is either a number representing the number of seconds before the current time or a number with a modifier such as second, minute, hour, day, or week (Minimum allowed value is 1 second). |
| MAC | (Optional) Specify the MAC address of the device whose details you want to retrieve from Darktrace. |
| Subnet ID(SID) | (Optional) Specify the identification number of a subnet modeled in the Darktrace system that contains the device whose details you want to retrieve from Darktrace. |
| Count | (Optional) Specify the maximum number of devices to return. This only limits the number of devices within the current time frame. |
| Include Tags | (Optional) Select this option to include tags applied to the device in the response. |
The output contains the following populated JSON schema:
Output schema when you choose Include Tags as true:
[
{
"id": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"did": "",
"sid": "",
"time": "",
"endtime": "",
"tags": [
{
"tid": "",
"expiry": "",
"thid": "",
"name": "",
"restricted": "",
"data": {
"auto": "",
"color": "",
"description": ""
},
"isReferenced": ""
}
],
"typename": "",
"typelabel": ""
}
]
Output schema when you choose Include Tags as false:
[
{
"id": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"did": "",
"sid": "",
"time": "",
"endtime": "",
"typename": "",
"typelabel": ""
}
]
| Parameter | Description |
|---|---|
| Device ID(DID) | Specify the Device ID (unique identifier) of a specific device on the network, based on which you want to retrieve similar devices from Darktrace. |
| Count | (Optional) Specify the maximum number of devices to return. This only limits the number of devices within the current time frame. |
| Full Device Details | (Optional) Select this option to return the full device detail objects for all devices referenced by data in the API response. |
The output contains the following populated JSON schema:
Output schema when you choose Full Device Details as true:
[
{
"did": "",
"score": "",
"macaddress": "",
"vendor": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"firstSeen": "",
"lastSeen": "",
"typename": "",
"typelabel": "",
"tags": [
{
"tid": "",
"expiry": "",
"thid": "",
"name": "",
"restricted": "",
"data": {
"auto": "",
"color": "",
"description": ""
},
"isReferenced": ""
}
]
}
]
Output schema when you choose Full Device Details as false:
[
{
"did": "",
"score": "",
"macaddress": "",
"vendor": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"firstSeen": "",
"lastSeen": "",
"typename": "",
"typelabel": ""
}
]
| Parameter | Description |
|---|---|
| Get Endpoints by | Select the parameter using which you want to get external endpoints details. You can choose from following options:
|
| Score | (Optional) Select this option to return rarity data for the endpoints in the response. |
| Devices | (Optional) Select this option to return a list of devices that have recently connected to the endpoint in the response. |
Output schema when you select:
truetrue
{
"ip": "",
"firsttime": "",
"country": "",
"asn": "",
"city": "",
"region": "",
"name": "",
"longitude": "",
"latitude": "",
"popularity": "",
"devices": [
{
"did": "",
"macaddress": "",
"vendor": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"firstSeen": "",
"lastSeen": "",
"typename": "",
"typelabel": ""
}
]
}
Output schema when:
truefalse
{
"ip": "",
"asn": "",
"city": "",
"name": "",
"region": "",
"country": "",
"devices": [
{
"ip": "",
"did": "",
"ips": [
{
"ip": "",
"sid": "",
"time": "",
"timems": ""
}
],
"sid": "",
"vendor": "",
"lastSeen": "",
"typename": "",
"firstSeen": "",
"typelabel": "",
"macaddress": ""
}
],
"latitude": "",
"firsttime": "",
"longitude": ""
}
Output schema when:
truefalse
{
"ip": "",
"firsttime": "",
"country": "",
"asn": "",
"city": "",
"region": "",
"name": "",
"longitude": "",
"latitude": "",
"popularity": ""
}
Output schema when:
falsefalse
{
"ip": "",
"firsttime": "",
"country": "",
"asn": "",
"city": "",
"region": "",
"name": "",
"longitude": "",
"latitude": ""
}
Output schema when:
truetruetrue
{
"hostname": "",
"firsttime": "",
"devices": [
{
"did": "",
"macaddress": "",
"vendor": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"firstSeen": "",
"lastSeen": "",
"devicelabel": "",
"typename": "",
"typelabel": ""
}
],
"ips": [
{
"ip": "",
"firsttime": "",
"lasttime": ""
}
],
"locations": [
{
"latitude": "",
"longitude": "",
"country": "",
"city": ""
}
],
"popularity": "",
"dgascore": ""
}
Output schema when:
truetruefalse
{
"hostname": "",
"firsttime": "",
"devices": [
{
"did": "",
"macaddress": "",
"vendor": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"firstSeen": "",
"lastSeen": "",
"devicelabel": "",
"typename": "",
"typelabel": ""
}
],
"ips": [
{
"ip": "",
"firsttime": "",
"lasttime": ""
}
],
"locations": [
{
"latitude": "",
"longitude": "",
"country": "",
"city": ""
}
]
}
Output schema when:
falsetruetrue
{
"hostname": "",
"firsttime": "",
"ips": [
{
"ip": "",
"firsttime": "",
"lasttime": ""
}
],
"locations": [
{
"latitude": "",
"longitude": "",
"country": "",
"city": ""
}
],
"popularity": "",
"dgascore": ""
}
Output schema when:
falsetruefalse
{
"hostname": "",
"firsttime": "",
"ips": [
{
"ip": "",
"firsttime": "",
"lasttime": ""
}
],
"locations": [
{
"latitude": "",
"longitude": "",
"country": "",
"city": ""
}
]
}
Output schema when:
truefalsefalse
{
"hostname": "",
"firsttime": "",
"devices": [
{
"did": "",
"macaddress": "",
"vendor": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"firstSeen": "",
"lastSeen": "",
"devicelabel": "",
"typename": "",
"typelabel": ""
}
]
}
Output schema when:
falsefalsetrue
{
"hostname": "",
"firsttime": "",
"popularity": "",
"dgascore": ""
}
Output schema when:
falsefalsetrue
{
"hostname": "",
"firsttime": "",
"popularity": "",
"dgascore": ""
}
If you choose Get Endpoints by as Hostname and Devices as false, then the output contains the following populated JSON schema:
{
"hostname": "",
"firsttime": ""
}
| Parameter | Description |
|---|---|
| Device ID(DID) | Specify the identification number of a device modeled in the Darktrace system whose details you want to retrieve from Darktrace. |
| Data Type | Select the type of data you want to retrieve for the specified device from Darktrace. You can choose from the following options:
|
| External Domain | (Optional) Specify the domain name based on which you want to filter external domains for devices whose details you want to retrieve from Darktrace. |
| Full Device Details | (Optional) Select this option to return the full device detail objects for all devices referenced by data in an API response. The use of this parameter alters the JSON structure of the API response for certain calls. |
| Show All Graph Data | (Optional) Select this option to return an entry for all time intervals in the graph data, including zero counts. |
| Similar Devices | (Optional) Specify the number of similar devices whose details you want to retrieve from Darktrace. This parameter returns data for the primary device and the specified number of similar devices. |
| Port | (Optional) Specify the port number if you want to restrict the returned connection data to the port you have specified. |
| Interval Hours | (Optional) Specify the size in hours used to group the returned time series data. |
The output contains the following populated JSON schema:
Output schema when you choose Show All Graph Data as true:
{
"deviceInfo": [
{
"did": "",
"similarityScore": "",
"graphData": [
{
"time": "",
"count": ""
}
],
"info": {
"totalUsed": "",
"totalServed": "",
"totalDevicesAndPorts": "",
"devicesAndPorts": [
{
"deviceAndPort": {
"direction": "",
"device": "",
"port": ""
},
"size": ""
}
],
"portsUsed": [
{
"port": "",
"size": "",
"firstTime": ""
}
],
"portsServed": [
{
"port": "",
"size": ""
}
],
"devicesUsed": [
{
"did": "",
"size": "",
"firstTime": ""
}
],
"devicesServed": [
{
"did": "",
"size": ""
}
]
}
}
]
}
Output schema when you choose Show All Graph Data as false:
{
"deviceInfo": [
{
"did": "",
"similarityScore": "",
"graphData": [],
"info": {
"totalUsed": "",
"totalServed": "",
"totalDevicesAndPorts": "",
"devicesAndPorts": [
{
"deviceAndPort": {
"direction": "",
"device": "",
"port": ""
},
"size": ""
}
],
"portsUsed": [
{
"port": "",
"size": "",
"firstTime": ""
}
],
"portsServed": [
{
"port": "",
"size": ""
}
],
"devicesUsed": [
{
"did": "",
"size": "",
"firstTime": ""
}
],
"devicesServed": [
{
"did": "",
"size": ""
}
]
}
}
]
}
This is the default output schema:
{
"deviceInfo": [
{
"did": "",
"similarityScore": "",
"graphData": [
{
"time": "",
"count": ""
}
],
"info": {
"totalUsed": "",
"totalServed": "",
"totalDevicesAndPorts": "",
"devicesAndPorts": [
{
"deviceAndPort": {
"direction": "",
"device": "",
"port": ""
},
"size": ""
}
],
"portsUsed": [
{
"port": "",
"size": "",
"firstTime": ""
}
],
"portsServed": [
{
"port": "",
"size": ""
}
],
"devicesUsed": [
{
"did": "",
"size": "",
"firstTime": ""
}
],
"devicesServed": [
{
"did": "",
"size": ""
}
]
}
}
]
}
| Parameter | Description |
|---|---|
| Device ID(DID) | Specify the identification number of a device modeled in the Darktrace system whose entity details you want to retrieve from Darktace |
| Application Protocol | (Optional) Specify the application protocol using which you want to filter data returned by this operation. |
| Destination Device ID(DDID) | (Optional) Specify the identification number of a destination device modeled in the Darktrace system using which you want to filter data returned by this operation. |
| Deduplicate | (Optional) Select this option to display only one equivalent connection per hour. |
| Port | (Optional) Specify the port number if you want to filter the returned data by source or destination port. |
| Start Time | (Optional) Specify the start time from when you want to retrieve data from Darktrace. |
| End Time | (Optional) Specify the end time till when you want to retrieve data from Darktrace. |
| Event Type | (Optional) Specifies a type of event whose details you want to retrieve from Darktrace. You can specify the following values: connection, unusualconnection, newconnection, notice, devicehistory, or modelbreach. |
| External Hostname | (Optional) Specify an external hostname whose details you want to retrieve from Darktace |
| Full Device Details | (Optional) Select this option to return the full device detail objects for all devices referenced by data in an API response. The use of this parameter alters the JSON structure of the API response for certain calls. |
| Offset | (Optional) Specify the count of records to skip when retrieving results. |
| Count | (Optional) Specify the maximum number of items to return.
NOTE: The 'Count' parameter is ignored when the 'Start' time parameter is used. |
The output contains the following populated JSON schema:
Output schema when you choose Full Device Details as true:
[
{
"time": "",
"timems": "",
"action": "",
"eventType": "",
"uid": "",
"status": "",
"sdid": "",
"port": "",
"sourcePort": "",
"destinationPort": "",
"direction": "out",
"applicationprotocol": "",
"protocol": "",
"sourceDevice": {
"id": "",
"did": "",
"macaddress": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"time": "",
"devicelabel": "",
"typename": "",
"typelabel": ""
},
"destinationDevice": {
"longitude": "",
"latitude": "",
"city": "",
"country": "",
"countrycode": "",
"asn": "",
"region": "",
"ip": "",
"hostname": "",
"hostnamepopularity": "",
"connectionhostnamepopularity": "",
"domain": "",
"domainpopularity": "",
"connectiondomainpopularity": "",
"ippopularity": "",
"connectionippopularity": ""
},
"source": "",
"destination": ""
}
]
Output schema when you choose Full Device Details as false:
[
{
"time": "",
"timems": "",
"action": "",
"eventType": "",
"uid": "",
"sdid": "",
"ddid": "",
"port": "",
"sourcePort": "",
"destinationPort": "",
"direction": "",
"applicationprotocol": "",
"protocol": "",
"sourceDevice": {
"id": "",
"did": "",
"macaddress": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"time": "",
"devicelabel": "",
"typename": "",
"typelabel": ""
},
"destinationDevice": {
"id": "",
"did": "",
"macaddress": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"time": "",
"typename": "",
"typelabel": ""
},
"source": "",
"destination": ""
}
]
This is the default output schema:
[
{
"time": "",
"timems": "",
"action": "",
"eventType": "",
"uid": "",
"dns": {
"hostname": "",
"success": "",
"hostnamepopularity": "",
"internal": ""
},
"sdid": "",
"ddid": "",
"port": "",
"sourcePort": "",
"destinationPort": "",
"direction": "",
"applicationprotocol": "",
"protocol": "",
"sourceDevice": {
"id": "",
"did": "",
"macaddress": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"time": "",
"devicelabel": "",
"typename": "",
"typelabel": ""
},
"destinationDevice": {
"id": "",
"did": "",
"macaddress": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"time": "",
"typename": "",
"typelabel": ""
},
"source": "",
"destination": ""
}
]
| Parameter | Description |
|---|---|
| Policy Breach ID(PBID) | (Optional) Specify the Policy Breach ID to retrieve comments for the model breach with the specified ID from Darktrace. |
| Start Time | (Optional) Specify the start time from when you want to retrieve data from Darktrace. |
| End Time | (Optional) Specify the end time till when you want to retrieve data from Darktrace. |
| Count | (Optional) Specify the maximum number of comments to return. This only limits the number of comments within the current time frame. By default, it is set to 100.
NOTE: The 'Count' parameter is ignored when the 'Start' time parameter is used. |
The output contains the following populated JSON schema:
[
{
"time": "",
"pbid": "",
"username": "",
"message": "",
"pid": "",
"name": ""
}
]
| Parameter | Description |
|---|---|
| Device ID(DID) | Specify the identification number of a device modelled in the Darktrace system. |
| Action | Select the type of action to be created in the Darktrace system. You can choose from the following options:
|
| Duration | Specify the duration of the action in seconds. |
| Reason | (Optional) Specify a reason for selecting the action. |
The output contains the following populated JSON schema:
{
"code": ""
}
| Parameter | Description |
|---|---|
| Start Time | (Optional) Specify the start time from when you want to retrieve data from Darktrace. |
| End Time | (Optional) Specify the end time till when you want to retrieve data from Darktrace. |
| Response Data | (Optional) Specify the name of a top-level field or object, restricts the returned JSON to only that field or object. |
The output contains the following populated JSON schema:
{
"pendingCount": "",
"activeCount": "",
"pendingActionDevices": [],
"activeActionDevices": []
}
| Parameter | Description |
|---|---|
| Full Device Details | (Optional) Select to retrieve the full device detail objects for all devices referenced by data to return. |
| Include Cleared | (Optional) Select to retrieve all darktrace RESPOND actions including those already cleared. By default, it is cleared, i.e., set to false. |
| Include History | (Optional) Select to include additional history information about the action state, such as when it was created or extended. |
| Need Confirming | (Optional) Select to filter returned darktrace RESPOND actions by those that need human confirmation or do not need human confirmation. |
| Start Time | (Optional) Specify the start time from when you want to retrieve data from Darktrace. Start time of data to return in millisecond format, relative to midnight January 1st 1970 UTC. |
| End Time | (Optional) Specify the end time till when you want to retrieve data from Darktrace. End time of data to return in millisecond format, relative to midnight January 1st 1970 UTC. |
| From | (Optional) Specify the start time from when you want to retrieve data from Darktrace. Start time of data to return in YYYY-MM-DD HH:MM:SS format. Start time of data to return in YYYY-MM-DD HH:MM:SS format. |
| To | (Optional) Specify the end time from when you want to retrieve data from Darktrace. End time of data to return in YYYY-MM-DD HH:MM:SS format. End time of data to return in YYYY-MM-DD HH:MM:SS format. |
| Include Connections | (Optional) Select to add a connections object which returns connections blocked by a darktrace RESPOND action. |
| Response Data | (Optional) Specify the name of a top-level field or object, restricts the returned JSON to only that field or object. |
| PB ID | (Optional) Specify the ID of the model breach based on which you want to retrieve antigena from Darktrace. |
The output contains the following populated JSON schema:
{
"actions": [
{
"codeid": "",
"did": "",
"ip": "",
"action": "",
"manual": "",
"triggerer": "",
"pbid": "",
"model": "",
"modeluuid": "",
"start": "",
"expires": "",
"blocked": "",
"agemail": "",
"active": "",
"cleared": ""
}
],
"connections": [
{
"action": "",
"label": "",
"did": "",
"direction": "",
"ip": "",
"port": "",
"timems": "",
"time": ""
}
],
"devices": [
{
"did": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"hostname": "",
"firstseen": "",
"lastseen": "",
"os": "",
"typename": "",
"typelabel": "",
"tags": [
{
"tid": "",
"expiry": "",
"thid": "",
"name": "",
"restricted": "",
"data": {
"auto": "",
"color": "",
"description": ""
},
"isReferenced": ""
}
]
}
]
}
| Parameter | Description |
|---|---|
| Code ID | Specify the unique identifier for the RESPOND action whose antigena you want to update in Darktrace. |
| Activate | (Optional) Select to activate an action. Cannot be combined with Clear parameter value as True. |
| Clear | (Optional) Select to clear an action. Cannot be combined with Activate parameter value as True. |
| Reason | (Optional) Specify the reason for selecting the action. |
| Duration | (Optional) Specify how long the state change should apply for in seconds. For extensions, should contain the current duration plus the amount the action should be extended for. |
The output contains a non-dictionary value.
The Sample - Darktrace - 1.3.0 playbook collection comes bundled with the Darktrace connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Darktrace connector.
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.