Darktrace

Supported versions

Supported Cortex XSOAR versions: 6.0.0 and later.

Darktrace is a Cyber AI platform for threat detection and response across cloud, email, industrial, and the network. This integration was integrated and tested with version 4.1.0 of Darktrace

Configure Darktrace on Cortex XSOAR#

  1. Navigate to Settings > Integrations > Servers & Services.
  2. Search for Darktrace.
  3. Click Add instance to create and configure a new integration instance.
ParameterDescriptionRequired
urlServer URL (e.g. https://example.net\)True
isFetchFetch incidentsFalse
insecureTrust any certificate (not secure)False
proxyUse system proxy settingsFalse
public_api_tokenPublic API TokenTrue
private_api_tokenPrivate API TokenTrue
min_scoreMinimum ScoreTrue
max_alertsMaximum Model Breaches per FetchFalse
first_fetchFirst fetch timeFalse
  1. Click Test to validate the URLs, token, and connection.

Commands#

You can execute these commands from the Demisto CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

darktrace-get-breach#


Darktrace-get-breach returns a model breach based on its model breach id (pbid)

Base Command#

darktrace-get-breach

Input#

Argument NameDescriptionRequired
pbidModel breach IDRequired

Context Output#

PathTypeDescription
Darktrace.ModelBreach.pbidNumberModel breach ID
Darktrace.ModelBreach.timeDateModel breach generated time.
Darktrace.ModelBreach.commentCountNumberNumber of comments on the model breach
Darktrace.ModelBreach.scoreNumberScore of Darktrace model breach (0 to 1)
Darktrace.ModelBreach.device.didNumberDarktrace device ID of Device that breached the model
Darktrace.ModelBreach.device.macaddressStringMAC address of the device involved in the model breach (if applicable)
Darktrace.ModelBreach.device.vendorStringVendor of the device involved in the model breach (if applicable)
Darktrace.ModelBreach.device.ipStringIP of the device involved in the model breach (if applicable)
Darktrace.ModelBreach.device.hostnameStringHostname of the device involved in the model breach (if applicable)
Darktrace.ModelBreach.device.devicelabelStringDevice label of the device involved in the model breach (if applicable)
Darktrace.ModelBreach.model.nameStringDarktrace model that was breached
Darktrace.ModelBreach.model.pidNumberModel ID of the model that was breached
Darktrace.ModelBreach.model.uuidStringModel UUID of the model that was breached
Darktrace.ModelBreach.model.tagsUnknownList of model tags for the model that was breached
Darktrace.ModelBreach.model.priorityNumberPriority of the model that was breached (0 to 5)
Darktrace.ModelBreach.model.descriptionStringDarktrace model description

Command Example#

!darktrace-get-breach pbid=95

Context Example#

{
"Darktrace": {
"ModelBreach": {
"commentCount": 0,
"device": {
"devicelabel": "Kelly's Laptop",
"did": 823,
"hostname": "sf-l-kjohnson",
"ip": "172.31.32.146",
"macaddress": "06:42:04:c2:b0:48",
"vendor": "HP"
},
"model": {
"description": "A device is connecting to watched domains or IP addresses. The watch list can be edited from the main GUI menu, Intel sub-menu, under the icon Watched Domains.\\n\\nAction: Review the domain and IP being connected to.",
"name": "Compromise::Watched Domain",
"pid": 762,
"priority": 5,
"tags": ["AP: C2 Comms"],
"uuid": "3338210a-8979-4a1b-8039-63ca8addf166"
},
"pbid": 95,
"score": 1,
"time": "2020-10-08T21:11:21.000Z"
}
}
}

Human Readable Output#

Darktrace Model Breach 95#

commentCountdevicemodelpbidscoretime
0did: 823
macaddress: 0a:df:4b:52:64:7a
vendor: HP
ip: 172.31.32.146
hostname: ip-172-31-32-146
devicelabel: Kelly's Laptop
name: Compromise::Watched Domain
pid: 762
uuid: 3338210a-8979-4a1b-8039-63ca8addf166
tags: [AP: C2 Comms]
priority: 5
description: A device is connecting to watched domains or IP addresses. The watch list can be edited from the main GUI menu, Intel sub-menu, under the icon Watched Domains.
9512020-10-08T21:11:21.000Z

darktrace-get-comments#


Returns the comments on a model breach based on its model breach id (pbid)

Base Command#

darktrace-get-comments

Input#

Argument NameDescriptionRequired
pbidModel Breach IDRequired

Context Output#

PathTypeDescription
Darktrace.ModelBreach.commentsUnknownArray of the comments on the model breach

Command Example#

!darktrace-get-comments pbid=46

Context Example#

{
"Darktrace": {
"ModelBreach": {
"comments": [
{
"message": "Flag for follow-up",
"pbid": 46,
"pid": 210,
"time": "2020-10-08T21:11:21.000Z",
"username": "user.one"
},
{
"message": "Activity has been remediated",
"pbid": 46,
"pid": 210,
"time": "2020-10-08T23:11:21.000Z",
"username": "user.two"
}
]
}
}
}

Human Readable Output#

Darktrace Model Breach 46 Comments#

messagepbidpidtimeusername
Flag for follow-up462102020-10-08T21:11:21.000Zuser.one
Activity has been remediated462102020-10-08T23:11:21.000Zuser.two

darktrace-acknowledge#


Acknowledge a model breach as specified by Model Breach ID

Base Command#

darktrace-acknowledge

Input#

Argument NameDescriptionRequired
pbidModel Breach IDRequired

Context Output#

PathTypeDescription
Darktrace.ModelBreach.acknowledgedStringWhether the model breach is acknowledged in Darktrace
Darktrace.ModelBreach.pbidNumberModel breach ID

Command Example#

!darktrace-acknowledge pbid=111

Context Example#

{
"Darktrace": {
"ModelBreach": {
"acknowledged": true,
"pbid": 111
}
}
}

Human Readable Output#

Model Breach 111 Acknowledged#

response
Successfully acknowledged.

darktrace-unacknowledge#


Unacknowledges a model breach as specified by Model Breach ID

Base Command#

darktrace-unacknowledge

Input#

Argument NameDescriptionRequired
pbidDarktrace model breach IDRequired

Context Output#

PathTypeDescription
Darktrace.ModelBreach.acknowledgedStringWhether the model breach is acknowledged
Darktrace.ModelBreach.pbidNumberModel breach ID

Command Example#

!darktrace-unacknowledge pbid=111

Context Example#

{
"Darktrace": {
"ModelBreach": {
"acknowledged": false,
"pbid": 111
}
}
}

Human Readable Output#

Model Breach 111 Unacknowledged#

response
Successfully unacknowledged.

darktrace-list-similar-devices#


Returns a list of similar devices to a device specified by Darktrace DID

Base Command#

darktrace-list-similar-devices

Input#

Argument NameDescriptionRequired
didDarktrace Device IDRequired
max_resultsMaximum number of results to returnRequired

Context Output#

PathTypeDescription
Darktrace.SimilarDevices.didNumberDarktrace Device ID of the device with the similar devices.
Darktrace.SimilarDevices.devicesUnknownList of similar devices and their available information

Command Example#

!darktrace-list-similar-devices did=1 max_results=2

Context Example#

{
"Darktrace": {
"SimilarDevices": {
"devices": [
{
"did": 823,
"firstSeen": "2020-08-07T00:06:40.000Z",
"hostname": "ip-172-31-32-146",
"ip": "172.31.32.146",
"ips": [
{
"ip": "172.31.32.146",
"sid": 114,
"time": "2020-09-14 06:00:00",
"timems": 1600063200000
}
],
"lastSeen": "2020-09-14T06:23:38.000Z",
"macaddress": "0a:df:4b:52:64:7a",
"score": 99,
"sid": 114,
"typelabel": "Server",
"typename": "server",
"vendor": ""
},
{
"did": 3,
"firstSeen": "2020-06-09T19:19:32.000Z",
"ip": "172.31.16.1",
"ips": [
{
"ip": "172.31.16.1",
"sid": 1,
"time": "2020-09-11 18:00:00",
"timems": 1599847200000
}
],
"lastSeen": "2020-09-11T18:58:00.000Z",
"score": 100,
"sid": 1,
"typelabel": "Server",
"typename": "server"
}
],
"did": 1
}
}
}

Human Readable Output#

List of similar devices to device:1:#

didfirstSeenhostnameipipslastSeenmacaddressscoresidtypelabeltypenamevendor
8232020-08-07T00:06:40.000Zip-172-31-32-146172.31.32.146{'ip': '172.31.32.146', 'timems': 1600063200000, 'time': '2020-09-14 06:00:00', 'sid': 114}2020-09-14T06:23:38.000Z0a:df:4b:52:64:7a99114Serverserver
32020-06-09T19:19:32.000Z172.31.16.1{'ip': '172.31.16.1', 'timems': 1599847200000, 'time': '2020-09-11 18:00:00', 'sid': 1}2020-09-11T18:58:00.000Z1001Serverserver

darktrace-get-external-endpoint-details#


Returns details collected by Darktrace about external IP addresses or hostnames.

Base Command#

darktrace-get-external-endpoint-details

Input#

Argument NameDescriptionRequired
endpoint_typeType of endpoint: IP or hostnameRequired
endpoint_valueIP or hostname to look upRequired
devicesBoolean: Include devices that have recently connected to the endpointOptional
additional_infoBoolean: Return additional info about the devicesOptional
scoreBoolean: Return rarity data for this endpointOptional

Context Output#

PathTypeDescription
Darktrace.ExternalEndpointDetailsUnknownReturned information about the external endpoint

Command Example#

!darktrace-get-external-endpoint-details endpoint_type=hostname endpoint_value=cats.com additional_info=true devices=true score=true

Context Example#

{
"Darktrace": {
"ExternalEndpointDetails": {
"devices": [],
"dgascore": 0,
"firsttime": "2020-08-07T04:47:23.000Z",
"hostname": "cats.com",
"ips": [],
"locations": [],
"popularity": 0
}
}
}

Human Readable Output#

Hostname: cats.com details#

devicesdgascorefirsttimehostnameipslocationspopularity
02020-08-07T04:47:23.000Zcats.com0

darktrace-get-device-connection-info#


Returns the graphable data used in the "Connections Data" view for a specific device that can be accessed from the Threat Visualizer omnisearch in Darktrace. Data returned covers a 4 week period. Parameters are further documented at https://customerportal.darktrace.com/product-guides/main/api-deviceinfo-request. It is recommended to run the command to check the relevant fields in context.

Base Command#

darktrace-get-device-connection-info

Input#

Argument NameDescriptionRequired
didDarktrace Device IDRequired
data_typeSpecify whether to return data for either connections (co), data size out (sizeout) or data size in (sizein).Required
external_domainRestrict external data to a particular domain name.Optional
destination_didDarktrace Device DID of destination device to restrict data to.Optional
show_all_graph_dataReturn an entry for all time intervals in the graph data, including zero counts. (Not recommended)Optional
num_similar_devicesReturn data for the primary device and this number of similar devices.Optional
full_device_detailsReturn the full device detail objects for all devices referenced by data in an API response. Use of this parameter will alter the JSON structure of the API response for certain calls.Optional

Context Output#

PathTypeDescription
Darktrace.DeviceConnectionInfoUnknownGraphable data used in the "Connections Data" view for a specific device that can be accessed from the Threat Visualizer omnisearch in Darktrace. Data returned covers a 4 week period. Parameters are further documented at https://customerportal.darktrace.com/product-guides/main/api-deviceinfo-request. It is recommended to run the command to check the relevant fields in context.

Command Example#

!darktrace-get-device-connection-info did=1 data_type=co

Context Example#

{
"Darktrace": {
"DeviceConnectionInfo": {
"deviceInfo": [
{
"did": 1,
"graphData": [
{
"count": 390,
"time": 1598302800000
},
{
"count": 7,
"time": 1598306400000
},
{
"count": 94,
"time": 1598652000000
},
{
"count": 88,
"time": 1598990400000
},
{
"count": 25,
"time": 1598994000000
},
{
"count": 16,
"time": 1598997600000
},
{
"count": 15,
"time": 1599001200000
},
{
"count": 25,
"time": 1599004800000
},
{
"count": 13,
"time": 1599008400000
},
{
"count": 14,
"time": 1599012000000
},
{
"count": 13,
"time": 1599015600000
},
{
"count": 14,
"time": 1599019200000
},
{
"count": 18,
"time": 1599022800000
},
{
"count": 14,
"time": 1599026400000
},
{
"count": 13,
"time": 1599030000000
},
{
"count": 14,
"time": 1599033600000
},
{
"count": 13,
"time": 1599037200000
},
{
"count": 19,
"time": 1599040800000
},
{
"count": 13,
"time": 1599044400000
},
{
"count": 14,
"time": 1599048000000
},
{
"count": 624,
"time": 1599051600000
},
{
"count": 187,
"time": 1599055200000
},
{
"count": 169,
"time": 1599663600000
},
{
"count": 363,
"time": 1599667200000
},
{
"count": 329,
"time": 1599670800000
},
{
"count": 324,
"time": 1599674400000
},
{
"count": 332,
"time": 1599678000000
},
{
"count": 340,
"time": 1599681600000
},
{
"count": 334,
"time": 1599685200000
},
{
"count": 328,
"time": 1599688800000
},
{
"count": 340,
"time": 1599692400000
},
{
"count": 330,
"time": 1599696000000
},
{
"count": 332,
"time": 1599699600000
},
{
"count": 325,
"time": 1599703200000
},
{
"count": 344,
"time": 1599706800000
},
{
"count": 328,
"time": 1599710400000
},
{
"count": 338,
"time": 1599714000000
},
{
"count": 76,
"time": 1599750000000
},
{
"count": 336,
"time": 1599753600000
},
{
"count": 334,
"time": 1599757200000
},
{
"count": 334,
"time": 1599760800000
},
{
"count": 329,
"time": 1599764400000
},
{
"count": 342,
"time": 1599768000000
},
{
"count": 329,
"time": 1599771600000
},
{
"count": 336,
"time": 1599775200000
},
{
"count": 332,
"time": 1599778800000
},
{
"count": 332,
"time": 1599782400000
},
{
"count": 329,
"time": 1599786000000
},
{
"count": 328,
"time": 1599789600000
},
{
"count": 332,
"time": 1599793200000
},
{
"count": 341,
"time": 1599796800000
},
{
"count": 326,
"time": 1599800400000
},
{
"count": 330,
"time": 1599804000000
},
{
"count": 332,
"time": 1599807600000
},
{
"count": 334,
"time": 1599811200000
},
{
"count": 335,
"time": 1599814800000
},
{
"count": 333,
"time": 1599818400000
},
{
"count": 326,
"time": 1599822000000
},
{
"count": 328,
"time": 1599825600000
},
{
"count": 333,
"time": 1599829200000
},
{
"count": 335,
"time": 1599832800000
},
{
"count": 339,
"time": 1599836400000
},
{
"count": 351,
"time": 1599840000000
},
{
"count": 325,
"time": 1599843600000
},
{
"count": 329,
"time": 1599847200000
},
{
"count": 328,
"time": 1599850800000
}
],
"info": {
"devicesAndPorts": [
{
"deviceAndPort": {
"device": 2,
"direction": "out",
"port": 53
},
"size": 24
},
{
"deviceAndPort": {
"device": 0,
"direction": "out",
"port": 53
},
"size": 19
},
{
"deviceAndPort": {
"device": -5,
"direction": "out",
"port": 80
},
"size": 12
},
{
"deviceAndPort": {
"device": 0,
"direction": "out",
"port": 123
},
"size": 11
},
{
"deviceAndPort": {
"device": -3,
"direction": "out",
"port": "5001 - 10000"
},
"size": 10
},
{
"deviceAndPort": {
"device": 3,
"direction": "out",
"port": 67
},
"size": 9
},
{
"deviceAndPort": {
"device": 0,
"direction": "out",
"port": 443
},
"size": 4
},
{
"deviceAndPort": {
"device": -6,
"direction": "out",
"port": 1514
},
"size": 4
},
{
"deviceAndPort": {
"device": 0,
"direction": "out",
"port": 80
},
"size": 3
},
{
"deviceAndPort": {
"device": -4,
"direction": "out",
"port": "5001 - 10000"
},
"size": 1
},
{
"deviceAndPort": {
"device": -4,
"direction": "out",
"port": 3289
},
"size": 1
},
{
"deviceAndPort": {
"device": -4,
"direction": "out",
"port": 1124
},
"size": 1
},
{
"deviceAndPort": "others",
"size": 1
}
],
"devicesServed": [],
"devicesUsed": [
{
"did": 0,
"firstTime": 1591729360000,
"size": 37
},
{
"did": 2,
"firstTime": 1591729360000,
"size": 25
},
{
"did": -5,
"firstTime": 1591730027000,
"size": 12
},
{
"did": -3,
"firstTime": 1591729360000,
"size": 10
},
{
"did": 3,
"firstTime": 1591730311000,
"size": 9
},
{
"did": -6,
"firstTime": 1591730311000,
"size": 4
},
{
"did": -4,
"firstTime": 1591729360000,
"size": 2
},
{
"did": "others",
"size": 1
}
],
"portsServed": [],
"portsUsed": [
{
"firstTime": 1591729360000,
"port": 53,
"size": 44
},
{
"firstTime": 1591729360000,
"port": 80,
"size": 15
},
{
"firstTime": 1592496475000,
"port": "5001 - 10000",
"size": 11
},
{
"firstTime": 1591730311000,
"port": 123,
"size": 11
},
{
"firstTime": 1591730311000,
"port": 67,
"size": 9
},
{
"firstTime": 1592952598000,
"port": 1514,
"size": 4
},
{
"firstTime": 1591729361000,
"port": 443,
"size": 4
},
{
"firstTime": 1592497916000,
"port": 3289,
"size": 1
},
{
"port": "others",
"size": 1
}
],
"totalDevicesAndPorts": 1589,
"totalServed": 0,
"totalUsed": 1589
},
"similarityScore": 100
}
]
}
}
}

Human Readable Output#

Results for device id: 1#

deviceInfo
{'did': 1, 'similarityScore': 100, 'graphData': [{'time': 1598302800000, 'count': 390}, {'time': 1598306400000, 'count': 7}, {'time': 1598652000000, 'count': 94}, {'time': 1598990400000, 'count': 88}, {'time': 1598994000000, 'count': 25}, {'time': 1598997600000, 'count': 16}, {'time': 1599001200000, 'count': 15}, {'time': 1599004800000, 'count': 25}, {'time': 1599008400000, 'count': 13}, {'time': 1599012000000, 'count': 14}, {'time': 1599015600000, 'count': 13}, {'time': 1599019200000, 'count': 14}, {'time': 1599022800000, 'count': 18}, {'time': 1599026400000, 'count': 14}, {'time': 1599030000000, 'count': 13}, {'time': 1599033600000, 'count': 14}, {'time': 1599037200000, 'count': 13}, {'time': 1599040800000, 'count': 19}, {'time': 1599044400000, 'count': 13}, {'time': 1599048000000, 'count': 14}, {'time': 1599051600000, 'count': 624}, {'time': 1599055200000, 'count': 187}, {'time': 1599663600000, 'count': 169}, {'time': 1599667200000, 'count': 363}, {'time': 1599670800000, 'count': 329}, {'time': 1599674400000, 'count': 324}, {'time': 1599678000000, 'count': 332}, {'time': 1599681600000, 'count': 340}, {'time': 1599685200000, 'count': 334}, {'time': 1599688800000, 'count': 328}, {'time': 1599692400000, 'count': 340}, {'time': 1599696000000, 'count': 330}, {'time': 1599699600000, 'count': 332}, {'time': 1599703200000, 'count': 325}, {'time': 1599706800000, 'count': 344}, {'time': 1599710400000, 'count': 328}, {'time': 1599714000000, 'count': 338}, {'time': 1599750000000, 'count': 76}, {'time': 1599753600000, 'count': 336}, {'time': 1599757200000, 'count': 334}, {'time': 1599760800000, 'count': 334}, {'time': 1599764400000, 'count': 329}, {'time': 1599768000000, 'count': 342}, {'time': 1599771600000, 'count': 329}, {'time': 1599775200000, 'count': 336}, {'time': 1599778800000, 'count': 332}, {'time': 1599782400000, 'count': 332}, {'time': 1599786000000, 'count': 329}, {'time': 1599789600000, 'count': 328}, {'time': 1599793200000, 'count': 332}, {'time': 1599796800000, 'count': 341}, {'time': 1599800400000, 'count': 326}, {'time': 1599804000000, 'count': 330}, {'time': 1599807600000, 'count': 332}, {'time': 1599811200000, 'count': 334}, {'time': 1599814800000, 'count': 335}, {'time': 1599818400000, 'count': 333}, {'time': 1599822000000, 'count': 326}, {'time': 1599825600000, 'count': 328}, {'time': 1599829200000, 'count': 333}, {'time': 1599832800000, 'count': 335}, {'time': 1599836400000, 'count': 339}, {'time': 1599840000000, 'count': 351}, {'time': 1599843600000, 'count': 325}, {'time': 1599847200000, 'count': 329}, {'time': 1599850800000, 'count': 328}], 'info': {'totalUsed': 1589, 'totalServed': 0, 'totalDevicesAndPorts': 1589, 'devicesAndPorts': [{'deviceAndPort': {'direction': 'out', 'device': 2, 'port': 53}, 'size': 24}, {'deviceAndPort': {'direction': 'out', 'device': 0, 'port': 53}, 'size': 19}, {'deviceAndPort': {'direction': 'out', 'device': -5, 'port': 80}, 'size': 12}, {'deviceAndPort': {'direction': 'out', 'device': 0, 'port': 123}, 'size': 11}, {'deviceAndPort': {'direction': 'out', 'device': -3, 'port': '5001 - 10000'}, 'size': 10}, {'deviceAndPort': {'direction': 'out', 'device': 3, 'port': 67}, 'size': 9}, {'deviceAndPort': {'direction': 'out', 'device': 0, 'port': 443}, 'size': 4}, {'deviceAndPort': {'direction': 'out', 'device': -6, 'port': 1514}, 'size': 4}, {'deviceAndPort': {'direction': 'out', 'device': 0, 'port': 80}, 'size': 3}, {'deviceAndPort': {'direction': 'out', 'device': -4, 'port': '5001 - 10000'}, 'size': 1}, {'deviceAndPort': {'direction': 'out', 'device': -4, 'port': 3289}, 'size': 1}, {'deviceAndPort': {'direction': 'out', 'device': -4, 'port': 1124}, 'size': 1}, {'deviceAndPort': 'others', 'size': 1}], 'portsUsed': [{'port': 53, 'size': 44, 'firstTime': 1591729360000}, {'port': 80, 'size': 15, 'firstTime': 1591729360000}, {'port': '5001 - 10000', 'size': 11, 'firstTime': 1592496475000}, {'port': 123, 'size': 11, 'firstTime': 1591730311000}, {'port': 67, 'size': 9, 'firstTime': 1591730311000}, {'port': 1514, 'size': 4, 'firstTime': 1592952598000}, {'port': 443, 'size': 4, 'firstTime': 1591729361000}, {'port': 3289, 'size': 1, 'firstTime': 1592497916000}, {'port': 'others', 'size': 1}], 'portsServed': [], 'devicesUsed': [{'did': 0, 'size': 37, 'firstTime': 1591729360000}, {'did': 2, 'size': 25, 'firstTime': 1591729360000}, {'did': -5, 'size': 12, 'firstTime': 1591730027000}, {'did': -3, 'size': 10, 'firstTime': 1591729360000}, {'did': 3, 'size': 9, 'firstTime': 1591730311000}, {'did': -6, 'size': 4, 'firstTime': 1591730311000}, {'did': -4, 'size': 2, 'firstTime': 1591729360000}, {'did': 'others', 'size': 1}], 'devicesServed': []}}

darktrace-get-device-identity-info#


Gets device identity information based on label, tag, type, hostname, ip, mac, vendor and os. It is recommended to run the command to check the relevant fields in context.

Base Command#

darktrace-get-device-identity-info

Input#

Argument NameDescriptionRequired
max_resultsMax number of devices to return. Default is 50.Optional
order_byOrders the response by the specified filter. Default value is lastSeen.Optional
orderSets the sort order for returned devices as ascending (asc) or descending (desc). Default is ascending.Optional
queryA string search. Can query all fields or take a specific field to filter. The query parameter can take a string directly to search all key/value pairs (.e.g query="value") or be limited to a certain data type (.e.g query="label:test"). Fields to filter on are:
- label
- tag
- type
- hostname
- ip
- mac
- vendor
- os
Required

Context Output#

PathTypeDescription
Darktrace.DeviceIdentityInfoUnknownInformation about the device’s identity. It is recommended to run the command to check the relevant fields in context.

Command Example#

!darktrace-get-device-identity-info query=osSensor

Context Example#

{
"Darktrace": {
"DeviceIdentityInfo": {
"devices": [
{
"devicelabel": "Kelly's Laptop",
"did": 10,
"firstSeen": "2020-06-09T19:02:50.000Z",
"hostname": "ip-172-31-17-246",
"ip": "172.31.17.246",
"ips": [
{
"ip": "172.31.17.246",
"sid": 1,
"time": "2020-09-11 19:00:00",
"timems": 1599850800000
}
],
"lastSeen": "2020-09-11T18:22:30.000Z",
"macaddress": "06:39:01:c2:b0:48",
"sid": 1,
"tags": [
{
"data": {
"auto": false,
"color": 110,
"description": "",
"visibility": "Public"
},
"expiry": 0,
"isReferenced": true,
"name": "Internet Facing System",
"restricted": false,
"thid": 54,
"tid": 54
},
{
"data": {
"auto": false,
"color": 181,
"description": "",
"visibility": "Public"
},
"expiry": 0,
"isReferenced": false,
"name": "SF Office",
"restricted": false,
"thid": 90,
"tid": 90
}
],
"typelabel": "Server",
"typename": "server",
"vendor": ""
}
],
"displayedCount": 1,
"totalCount": 1
}
}
}

Human Readable Output#

Results for query: osSensor (1 results displayed of 1 which match the query)#

devicelabeldidfirstSeenhostnameipipslastSeenmacaddresssidtagstypelabeltypenamevendor
Kelly's Laptop102020-06-09T19:02:50.000Zip-172-31-17-246172.31.17.246{'ip': '172.31.17.246', 'timems': 1599850800000, 'time': '2020-09-11 19:00:00', 'sid': 1}2020-09-11T18:22:30.000Z06:39:01:c2:b0:481{'tid': 54, 'expiry': 0, 'thid': 54, 'name': 'Internet Facing System', 'restricted': False, 'data': {'auto': False, 'color': 110, 'description': '', 'visibility': 'Public'}, 'isReferenced': True},
{'tid': 90, 'expiry': 0, 'thid': 90, 'name': 'SF Office', 'restricted': False, 'data': {'auto': False, 'color': 181, 'description': '', 'visibility': 'Public'}, 'isReferenced': False}
Serverserver

darktrace-get-entity-details#


Returns a time sorted list of connections and events for a device or an entity such as a user credential.

Base Command#

darktrace-get-entity-details

Input#

Argument NameDescriptionRequired
max_resultsMaximum number of items to return. Default is 50.Optional
offsetStarting index to return results from (for example offset=20 with max_results=50 will bring results from index 20 to index 70)Optional
queryComma-separated list of values to filter by.

Examples:
query="did=1,count=100,eventtype=unusualconnection"
query="pdid=1,from=2014-12-01T12:00:00,to=2014-12-02T12:00:00"
query="msg=USER123"

Possible values:
- applicationprotocol
- count
- ddid: Identification number of a destination device modelled in the Darktrace system to restrict data to
- deduplicate: Display only one equivalent connection per hour. (true/false)
- destinationport: This filter can be used to filter the returned data by destination port.
- did: Identification number of a device modelled in the Darktrace system.
- endtime: End time of data to return in millisecond format, relative to midnight January 1st 1970 UTC.
- eventtype: Specifies an type of event to return details for. (connection/unusualconnection/newconnection/notice/devicehistory/modelbreach/userdetails)
- externalhostname: Specifies an hostname to return details for.
- sourceport: This filter can be used to filter the returned data by source port.
- starttime: Start time of data to return in millisecond format, relative to midnight January 1st 1970 UTC.
- to: End time of data to return in YYYY-MM-DD HH:MM:SS format
- uid: Specifies a connection UID to return. (Example: CcdXo43n8B75cdYyI5)
- from: Start time of data to return in YYYY-MM-DD HH:MM:SS format.
- fulldevicedetails: Returns the full device detail objects for all devices referenced by data in an API response.
- intext: This filter can be used to filter the returned data to that which interacts with external sources and destinations, or is restricted to internal. (internal/external)
- msg: Specifies the value of the message field in notice events to return details for. Typically used to specify user credential strings.
- odid: Identification number of a device modelled in the Darktrace system to restrict data to. Typically used with ddid and odid to specify device pairs regardless of source/destination.
- pbid: ID for a model breach
- port: This filter can be used to filter the returned data by source or destination port.
- protocol

For more info on this query visit: https://<your-Darktrace-server-url>/apihelp ('details' tab)
Required

Context Output#

PathTypeDescription
Darktrace.EntityDetailsUnknownList of entities and their details. Each entity might have different keys. It is recommended to run the command once to check the relevant outputs in context.

Command Example#

!darktrace-get-entity-details query=did=1,count=10 offset=5

Context Example#

{
"Darktrace": {
"EntityDetails": [
{
"action": "connection",
"applicationprotocol": "SSH",
"ddid": 10,
"destination": "Kelly's Laptop",
"destinationDevice": {
"devicelabel": "Kelly's Laptop",
"did": 10,
"hostname": "ip-172-31-17-246",
"id": 1,
"ip": "172.31.17.246",
"ips": [
{
"ip": "172.31.17.246",
"sid": 1,
"time": "2020-09-11 19:00:00",
"timems": 1599850800000
}
],
"macaddress": "06:39:01:c2:b0:48",
"sid": 1,
"time": "1591729370000",
"typelabel": "Server",
"typename": "server"
},
"destinationPort": 22,
"direction": "in",
"eventType": "connection",
"port": 22,
"protocol": "TCP",
"source": "222.186.15.62",
"sourceDevice": {
"asn": "AS23650 AS Number for CHINANET jiangsu province backbone",
"connectionippopularity": "0",
"country": "China",
"countrycode": "CN",
"ip": "222.186.15.62",
"ippopularity": "0",
"latitude": 34.772,
"longitude": 113.727,
"region": "Asia"
},
"sourcePort": 17815,
"status": "ongoing",
"time": "2020-09-11 19:42:21",
"timems": 1599853341264,
"uid": "CJDfGwAT7fVxNJd01"
},
{
"action": "connection",
"applicationprotocol": "SSH",
"ddid": 10,
"destination": "Kelly's Laptop",
"destinationDevice": {
"devicelabel": "Kelly's Laptop",
"did": 10,
"hostname": "ip-172-31-17-246",
"id": 1,
"ip": "172.31.17.246",
"ips": [
{
"ip": "172.31.17.246",
"sid": 1,
"time": "2020-09-11 19:00:00",
"timems": 1599850800000
}
],
"macaddress": "06:39:01:c2:b0:48",
"sid": 1,
"time": "1591729370000",
"typelabel": "Server",
"typename": "server"
},
"destinationPort": 22,
"direction": "in",
"eventType": "connection",
"port": 22,
"protocol": "TCP",
"source": "222.186.15.62",
"sourceDevice": {
"asn": "AS23650 AS Number for CHINANET jiangsu province backbone",
"connectionippopularity": "0",
"country": "China",
"countrycode": "CN",
"ip": "222.186.15.62",
"ippopularity": "0",
"latitude": 34.772,
"longitude": 113.727,
"region": "Asia"
},
"sourcePort": 17815,
"time": "2020-09-11 19:42:14",
"timems": 1599853334254,
"uid": "CJDfGwAT7fVxNJd01"
},
{
"action": "connection",
"applicationprotocol": "Unknown",
"ddid": 10,
"destination": "Kelly's Laptop",
"destinationDevice": {
"devicelabel": "Kelly's Laptop",
"did": 10,
"hostname": "ip-172-31-17-246",
"id": 1,
"ip": "172.31.17.246",
"ips": [
{
"ip": "172.31.17.246",
"sid": 1,
"time": "2020-09-11 19:00:00",
"timems": 1599850800000
}
],
"macaddress": "06:39:01:c2:b0:48",
"sid": 1,
"time": "1591729370000",
"typelabel": "Server",
"typename": "server"
},
"destinationPort": 443,
"direction": "in",
"eventType": "connection",
"port": 443,
"protocol": "TCP",
"source": "62.113.227.26",
"sourceDevice": {
"asn": "AS47447 23media GmbH",
"connectionippopularity": "0",
"country": "Germany",
"countrycode": "DE",
"ip": "62.113.227.26",
"ippopularity": "0",
"latitude": 51.299,
"longitude": 9.491,
"region": "Europe"
},
"sourcePort": 28228,
"status": "failed",
"time": "2020-09-11 19:41:23",
"timems": 1599853283240,
"uid": "CQ4hu824CoXul9KV01"
},
{
"action": "connection",
"applicationprotocol": "Unknown",
"ddid": 10,
"destination": "Kelly's Laptop",
"destinationDevice": {
"devicelabel": "Kelly's Laptop",
"did": 10,
"hostname": "ip-172-31-17-246",
"id": 1,
"ip": "172.31.17.246",
"ips": [
{
"ip": "172.31.17.246",
"sid": 1,
"time": "2020-09-11 19:00:00",
"timems": 1599850800000
}
],
"macaddress": "06:39:01:c2:b0:48",
"sid": 1,
"time": "1591729370000",
"typelabel": "Server",
"typename": "server"
},
"destinationPort": 443,
"direction": "in",
"eventType": "connection",
"port": 443,
"protocol": "TCP",
"source": "62.113.227.26",
"sourceDevice": {
"asn": "AS47447 23media GmbH",
"connectionippopularity": "0",
"country": "Germany",
"countrycode": "DE",
"ip": "62.113.227.26",
"ippopularity": "0",
"latitude": 51.299,
"longitude": 9.491,
"region": "Europe"
},
"sourcePort": 54518,
"status": "failed",
"time": "2020-09-11 19:41:03",
"timems": 1599853263230,
"uid": "CWYWpz2KmHrsjNGO01"
},
{
"action": "notice",
"destination": "Kelly's Laptop",
"destinationDevice": {
"devicelabel": "Kelly's Laptop",
"did": 10,
"hostname": "ip-172-31-17-246",
"id": 1,
"ip": "172.31.17.246",
"ips": [
{
"ip": "172.31.17.246",
"sid": 1,
"time": "2020-09-11 19:00:00",
"timems": 1599850800000
}
],
"macaddress": "06:39:01:c2:b0:48",
"sid": 1,
"time": "1591729370000",
"typelabel": "Server",
"typename": "server"
},
"destinationPort": 22,
"details": "2073 bytes delivered in connection and 0 bytes undelivered.",
"direction": "in",
"eventType": "notice",
"mlid": 328,
"msg": "Unable to determine login failure or success from encrypted traffic.",
"nid": 35987,
"source": "13.85.152.27",
"sourceDevice": {
"asn": "AS8075 MICROSOFT-CORP-MSN-AS-BLOCK",
"city": "San Antonio",
"country": "United States",
"countrycode": "US",
"ip": "13.85.152.27",
"ippopularity": "0",
"latitude": 29.422,
"longitude": -98.493,
"region": "North America"
},
"time": "2020-09-11 19:40:48",
"timems": 1599853248000,
"type": "SSH::Undetermined_Encryption_Step",
"uid": "CMEAtvytG16vv0X01"
}
]
}
}

Human Readable Output#

Results:#

actionapplicationprotocolddiddestinationdestinationDevicedestinationPortdirectioneventTypeportprotocolsourcesourceDevicesourcePortstatustimetimemsuid
connectionSSH10Kelly's Laptopid: 1
did: 1
macaddress: 06:39:01:c2:b0:48
ip: 172.31.17.246
ips: {'ip': '172.31.17.246', 'timems': 1599850800000, 'time': '2020-09-11 19:00:00', 'sid': 1}
sid: 1
hostname: ip-172-31-17-246
time: 1591729370000
devicelabel: Kelly's Laptop
typename: server
typelabel: Server
22inconnection22TCP222.186.15.62longitude: 113.727
latitude: 34.772
country: China
countrycode: CN
asn: AS23650 AS Number for CHINANET jiangsu province backbone
region: Asia
ip: 222.186.15.62
ippopularity: 0
connectionippopularity: 0
17815ongoing2020-09-11 19:42:211599853341264CJDfGwAT7fVxNJd01
connectionSSH10Kelly's Laptopid: 1
did: 1
macaddress: 06:39:01:c2:b0:48
ip: 172.31.17.246
ips: {'ip': '172.31.17.246', 'timems': 1599850800000, 'time': '2020-09-11 19:00:00', 'sid': 1}
sid: 1
hostname: ip-172-31-17-246
time: 1591729370000
devicelabel: Kelly's Laptop
typename: server
typelabel: Server
22inconnection22TCP222.186.15.62longitude: 113.727
latitude: 34.772
country: China
countrycode: CN
asn: AS23650 AS Number for CHINANET jiangsu province backbone
region: Asia
ip: 222.186.15.62
ippopularity: 0
connectionippopularity: 0
178152020-09-11 19:42:141599853334254CJDfGwAT7fVxNJd01
connectionUnknown10Kelly's Laptopid: 1
did: 1
macaddress: 06:39:01:c2:b0:48
ip: 172.31.17.246
ips: {'ip': '172.31.17.246', 'timems': 1599850800000, 'time': '2020-09-11 19:00:00', 'sid': 1}
sid: 1
hostname: ip-172-31-17-246
time: 1591729370000
devicelabel: Kelly's Laptop
typename: server
typelabel: Server
443inconnection443TCP62.113.227.26longitude: 9.491
latitude: 51.299
country: Germany
countrycode: DE
asn: AS47447 23media GmbH
region: Europe
ip: 62.113.227.26
ippopularity: 0
connectionippopularity: 0
28228failed2020-09-11 19:41:231599853283240CQ4hu824CoXul9KV01
connectionUnknown10Kelly's Laptopid: 1
did: 1
macaddress: 06:39:01:c2:b0:48
ip: 172.31.17.246
ips: {'ip': '172.31.17.246', 'timems': 1599850800000, 'time': '2020-09-11 19:00:00', 'sid': 1}
sid: 1
hostname: ip-172-31-17-246
time: 1591729370000
devicelabel: Kelly's Laptop
typename: server
typelabel: Server
443inconnection443TCP62.113.227.26longitude: 9.491
latitude: 51.299
country: Germany
countrycode: DE
asn: AS47447 23media GmbH
region: Europe
ip: 62.113.227.26
ippopularity: 0
connectionippopularity: 0
54518failed2020-09-11 19:41:031599853263230CWYWpz2KmHrsjNGO01
noticeKelly's Laptopid: 1
did: 1
macaddress: 06:39:01:c2:b0:48
ip: 172.31.17.246
ips: {'ip': '172.31.17.246', 'timems': 1599850800000, 'time': '2020-09-11 19:00:00', 'sid': 1}
sid: 1
hostname: ip-172-31-17-246
time: 1591729370000
devicelabel: Kelly's Laptop
typename: server
typelabel: Server
22innotice13.85.152.27longitude: -98.493
latitude: 29.422
city: San Antonio
country: United States
countrycode: US
asn: AS8075 MICROSOFT-CORP-MSN-AS-BLOCK
region: North America
ip: 13.85.152.27
ippopularity: 0
2020-09-11 19:40:481599853248000CMEAtvytG16vv0X01