Darktrace v1.2.0

About the connector

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.

Version information

Connector Version: 1.2.0

FortiSOAR™ Version Tested on: 7.2.0-914

Darktrace version tested on: 5.2.11 (a6d707)

Authored By: Fortinet

Certified: Yes

Release Notes for version 1.2.0

Following enhancements have been made to the Darktrace Connector in version 1.2.0:

• Added following actions and playbooks
  • Search Query
  • Get Incidents
  • Get Incident Comments
  • Acknowledge Breach
  • Unacknowledge Breach
  • Get Breach Details
  • Get Models
  • Get Components
  • Get Devices
  • Get Similar Devices
  • Get External Endpoint Details
  • Get Device Information
  • Get Entity Details
  • Get Model Breaches
  • Get Model Breach Comments

Installing the connector

Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.

You can also use the following yum command as a root user to install connectors from an SSH session:
yum install cyops-connector-darktrace

Prerequisites to configuring the connector

• You must have the URL of the Darktrace server to which you will connect and perform the automated operations and the API public and private key to access that server.
• The FortiSOAR™ server should have outbound connectivity to port 443 on the Darktrace server.

Minimum Permissions Required

• Not Applicable

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the Darktrace connector card. On the connector popup, click the Configurations tab to enter the required configuration details:

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations

operation: Add To Watch List

Input parameters

Output

The JSON output returns a Success message if the Domain(s), hostname(s), or IP address(es), is added to the Darktrace's internal watch list, or an Error message containing the reason for failure.

The output contains the following populated JSON schema:
{
"response": "",
"added": ""
}

operation: Remove From Watch List

Input parameters

Output

The JSON output returns a Success message if the Domain, hostname, or IP address, is removed from the Darktrace's internal watch list, or an Error message containing the reason for failure.

The output contains the following populated JSON schema:
{
"response": ""
}

operation: Get Watch List

Input parameters

None.

Output

The JSON output returns a list of indicators from a watch list.

No output schema is available at this time.

operation: Get Incidents

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list, i.e., a list of all incidents provided by AI Analyst events, is returned.

Output

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": ""
}
]
}
]
}
]
]
}

operation: Search Query

Input parameters

Output

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": []
}
}

operation: Get Incident Comments

Input parameters

Output

The output contains the following populated JSON schema:
{
"comments": [
{
"username": "",
"time": "",
"incident_id": "",
"message": ""
}
]
}

operation: Acknowledge Breach

Input parameters

Output

The output contains the following populated JSON schema:
{
"response": ""
}

operation: Unacknowledge Breach

Input parameters

Output

The output contains the following populated JSON schema:
{
"response": ""
}

operation: Get Breach Details

Input parameters

Output

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": []
}
}

operation: Get Model Breaches

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list, i.e., a list of all model breaches, is returned.

Output

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": ""
}
]
}
]
}

operation: Get Models

Input parameters

Output

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": ""
}

operation: Get Components

Input parameters

Output

The output contains the following populated JSON schema:
{
"cid": "",
"chid": "",
"mlid": "",
"threshold": "",
"interval": "",
"logic": {},
"filters": [
{
"id": "",
"cfid": "",
"cfhid": "",
"filtertype": "",
"comparator": "",
"arguments": {
"value": ""
}
}
],
"active": ""
}

operation: Get Devices

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list, i.e., a list of all devices identified by Darktrace, is returned.

Output

The output contains the following populated JSON schema:
{
"id": "",
"did": "",
"sid": "",
"time": "",
"endtime": "",
"devicelabel": "",
"typename": "",
"typelabel": ""
}

operation: Get Similar Devices

Input parameters

Output

No output schema is available at this time.

operation: Get External Endpoint Details

Input parameters

Output

The output contains the following populated JSON schema:

Output schema when you choose "" as "IP Address":
{
"ip": "",
"firsttime": "",
"country": "",
"asn": "",
"city": "",
"region": "",
"name": "",
"longitude": "",
"latitude": "",
"devices": [
{
"did": "",
"macaddress": "",
"vendor": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"firstSeen": "",
"lastSeen": "",
"os": "",
"typename": "",
"typelabel": ""
}
]
}

Output schema when you choose "" as "IP Address":
{
"ip": "",
"firsttime": "",
"country": "",
"asn": "",
"city": "",
"region": "",
"name": "",
"longitude": "",
"latitude": ""
}

Output schema when you choose "" as "Hostname":
{
"hostname": "",
"firsttime": "",
"devices": [
{
"did": "",
"macaddress": "",
"vendor": "",
"ip": "",
"ips": [
{
"ip": "",
"timems": "",
"time": "",
"sid": ""
}
],
"sid": "",
"firstSeen": "",
"lastSeen": "",
"os": "",
"typename": "",
"typelabel": ""
}
]
}

Output schema when you choose "" as "Hostname":
{
"hostname": "",
"firsttime": ""
}

operation: Get Device Information

Input parameters

Output

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": ""
}
]
}
}
]
}

operation: Get Entity Details

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Output

The output contains the following populated JSON schema:
{
"uid": "",
"ddid": "",
"port": "",
"sdid": "",
"time": "",
"graph": "",
"action": "",
"source": "",
"timems": "",
"protocol": "",
"direction": "",
"eventType": "",
"graphtitle": "",
"sourcePort": "",
"destination": "",
"sourceDevice": {
"id": "",
"ip": "",
"did": "",
"ips": [
{
"ip": "",
"sid": "",
"time": "",
"timems": ""
}
],
"sid": "",
"time": "",
"hostname": "",
"typename": "",
"typelabel": "",
"macaddress": ""
},
"destinationPort": "",
"destinationDevice": {
"id": "",
"ip": "",
"did": "",
"ips": [
{
"ip": "",
"sid": "",
"time": "",
"timems": ""
}
],
"sid": "",
"time": "",
"typename": "",
"typelabel": ""
},
"applicationprotocol": ""
}

operation: Get Model Breach Comments

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list, i.e., comments across all model breaches, is returned.

Output

The output contains the following populated JSON schema:
{
"time": "",
"pbid": "",
"username": "",
"message": "",
"pid": "",
"name": ""
}

Included playbooks

The Sample - Darktrace - 1.2.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^TM after importing the Darktrace connector.

• Acknowledge Breach
• Add To Watch List
• Get Incident Comments
• Get Breach Details
• Get Components
• Get Device Information
• Get Devices
• Get Entity Details
• Get External Endpoint Details
• Get Incidents
• Get Model Breach Comments
• Get Model Breaches
• Get Models
• Get Similar Devices
• Get Watch List
• Remove From Watch List
• Search Query
• Unacknowledge Breach

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.