Darktrace

the darktrace connector enables seamless integration with swimlane turbine, providing access to darktrace's autonomous cyber defense capabilities and rich data insights darktrace is a leader in cyber ai and autonomous response technology, providing real time threat detection and automated incident response the darktrace turbine connector enables users to integrate darktrace's advanced security analytics and ai capabilities directly into swimlane's low code security automation platform this integration empowers security teams to streamline their workflows, rapidly acknowledge events, add comments to ai analyst events, initiate manual respond actions, and gain operational insights with comprehensive reporting enhance your security posture by leveraging darktrace's telemetry within swimlane turbine to automate responses and accelerate incident resolution prerequisites to effectively utilize the darktrace connector with swimlane turbine, ensure you have the following prerequisites darktrace api authentication with the following parameters url the endpoint url for the darktrace api api token your unique token to authenticate requests to the darktrace api private token a secondary token used for enhanced security measures during authentication capabilities the darktrace integration provides the following capabilities acknowledge event add comment to ai analyst event add comment to model breach antigena manual antigena summary endpoint details execute advanced search get action summary get ai analyst comments get ai analyst events get ai analyst groups get api data get audit events get antigena respond details get comments and so on documentation find full guide on the darktrace api under product guides after login to darktace portal https //partnerportal darktrace com/login configurations darktrace api authentication darktrace api authentication configuration parameters parameter description type required url server url address string required api token api token string required private token private token string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions acknowledge event acknowledge breaches in darktrace using the specified pbid, aiding in streamlining incident response workflows endpoint url /modelbreaches/{{pbid}}/acknowledge method post input argument name type required description pbid number required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase response string output field response example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 13 feb 2024 15 20 16 gmt", "content type" "application/json; charset=utf 8", "content length" "35", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 021", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" { "response" "success" } } ] add comment to ai analyst event adds a user defined comment to a darktrace ai analyst event using the specified incident id endpoint url /aianalyst/incident/comments method post input argument name type required description incident id string required unique identifier message string required response message output parameter type description status code number http status code of the response reason string response reason phrase comments array output field comments username string name of the resource time number time value incident id string unique identifier message string response message example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 02 jul 2024 15 06 00 gmt", "content type" "application/json; charset=utf 8", "content length" "28", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style s ", "cache control" "no store", "servertime" "0 001", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin" }, "reason" "ok", "json body" { "comments" \[] } } ] add comment to model breach adds a user defined comment to a specific darktrace model breach using the provided pbid and message endpoint url /modelbreaches/{{pbid}}/comments method post input argument name type required description pbid number required unique identifier message string required response message output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 02 jul 2024 13 16 44 gmt", "content type" "application/json; charset=utf 8", "content length" "10", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style s ", "cache control" "no store", "servertime" "0 002", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin" }, "reason" "ok", "json body" \[ {}, {} ] } ] antigena manual initiate manual darktrace respond/network actions specifying device id, action type, duration, and reason endpoint url /antigena/manual method post input argument name type required description did number required unique identifier action string required parameter for antigena manual duration number required parameter for antigena manual reason string required response reason phrase connections array optional parameter for antigena manual src string optional parameter for antigena manual dst string optional parameter for antigena manual port number optional parameter for antigena manual output parameter type description status code number http status code of the response reason string response reason phrase codeid number unique identifier example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "fri, 07 jun 2024 06 26 58 gmt", "content type" "text/html; charset=utf 8", "transfer encoding" "chunked", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style s ", "etag" "w/\\"caf zr7v0xd0z1id25xkegro1wq2tzu\\"", "vary" "accept encoding", "content encoding" "gzip", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" { "codeid" 12345 } } ] antigena summary provides an overview of active and pending darktrace respond actions for operational insights endpoint url /antigena/summary method get input argument name type required description endtime number optional time value starttime number optional time value responsedata string optional response data output parameter type description status code number http status code of the response reason string response reason phrase pendingcount number count value activecount number count value pendingactiondevices array output field pendingactiondevices activeactiondevices array output field activeactiondevices example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "fri, 07 jun 2024 06 26 58 gmt", "content type" "text/html; charset=utf 8", "transfer encoding" "chunked", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style s ", "etag" "w/\\"caf zr7v0xd0z1id25xkegro1wq2tzu\\"", "vary" "accept encoding", "content encoding" "gzip", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" { "pendingcount" 8, "activecount" 29, "pendingactiondevices" \[], "activeactiondevices" \[] } } ] endpoint details retrieve detailed information for specified external ip addresses and hostnames using darktrace endpoint url /endpointdetails method get input argument name type required description additionalinfo boolean optional return additional information about the endpoint devices boolean optional return a list of devices which have recently connected to the endpoint hostname string optional return data for this hostname ip string optional return data for this ip address score boolean optional return the popularity scores for external endpoints output parameter type description status code number http status code of the response reason string response reason phrase ip string output field ip firsttime number time value country string output field country asn string output field asn city string output field city region string output field region name string name of the resource longitude number output field longitude latitude number output field latitude ipage number output field ipage iptime string time value example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 06 feb 2024 08 49 38 gmt", "content type" "application/json; charset=utf 8", "content length" "186", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 015", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" { "ip" "8 8 8 8", "firsttime" 1599010423000, "country" "united states", "asn" "as15169 google", "city" "", "region" "north america", "name" "", "longitude" 97 822, "latitude" 37 751, "ipage" 108198955, "iptime" "2020 09 02 01 33 43" } } ] execute advanced search executes an advanced search in darktrace with a base64 encoded query, exporting the results in json format endpoint url /advancedsearch/api/search/{{base64 query}} method get input argument name type required description base64 query string required parameter for execute advanced search output parameter type description status code number http status code of the response reason string response reason phrase took number output field took timed out boolean output field timed out shards object output field shards total number output field total successful number whether the operation was successful skipped number output field skipped failed number output field failed hits object output field hits total number output field total max score number score value hits array output field hits index string output field index type string type of the resource id string unique identifier score object score value source object output field source @fields object output field @fields orig pkts number output field orig pkts @type string type of the resource @timestamp string output field @timestamp @message string response message sort array output field sort darktracechilderror string error message if any example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 02 jul 2024 13 23 15 gmt", "content type" "application/json; charset=utf 8", "content length" "297", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style s ", "cache control" "no store", "servertime" "0 481", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin" }, "reason" "ok", "json body" { "took" 0, "timed out" false, " shards" {}, "hits" {}, "darktracechilderror" "18 135 140 174,54 155 33 146 erebus pull mode vsensor", "kibana" {} } } ] get action summary retrieve a categorized breakdown of actions taken within darktrace for quick analysis and review endpoint url /agemail/api/v1 0/dash/action summary method get input argument name type required description days number optional number of days to query over (minimum value is 1, maximum value is 30) output parameter type description status code number http status code of the response reason string response reason phrase hold object output field hold value number value for the parameter movetojunk object output field movetojunk value number value for the parameter attachment actions object output field attachment actions value number value for the parameter link actions object output field link actions value number value for the parameter other object output field other value number value for the parameter example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "thu, 01 aug 2024 09 08 55 gmt", "content type" "application/json; charset=utf 8", "content length" "91", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "default src 'self'; script src 'self'; style src 'self' 'unsafe inline'; img src ", "cache control" "no store", "servertime" "0 099", "content encoding" "deflate", "vary" "accept encoding", "etag" "w/\\"7f dqogrc23nz2qnzr8v1jrcqwbjx4\\"" }, "reason" "ok", "json body" { "hold" {}, "movetojunk" {}, "attachment actions" {}, "link actions" {}, "other" {} } } ] get ai analyst comments retrieve comments associated with a specific ai analyst event in darktrace using the provided incident id endpoint url /aianalyst/incident/comments method get input argument name type required description incident id string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase comments array output field comments username string name of the resource time number time value incident id string unique identifier message string response message example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 02 jul 2024 14 56 00 gmt", "content type" "application/json; charset=utf 8", "content length" "28", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style s ", "cache control" "no store", "servertime" "0 002", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin" }, "reason" "ok", "json body" { "comments" \[] } } ] get ai analyst events retrieve anomalies or network activities investigated by cyber ai analyst within darktrace endpoint url /aianalyst/incidentevents method get input argument name type required description groupid string optional unique identifier uuid string optional unique identifier did number optional unique identifier excludedid number optional unique identifier sid number optional unique identifier excludesid number optional unique identifier master number optional parameter for get ai analyst events includeacknowledged boolean optional parameter for get ai analyst events includeallpinned boolean optional parameter for get ai analyst events includeonlypinned boolean optional parameter for get ai analyst events includeincidenteventurl boolean optional url endpoint for the request locale string optional parameter for get ai analyst events endtime string optional time value starttime string optional time value groupcompliance boolean optional parameter for get ai analyst events groupsuspicious boolean optional parameter for get ai analyst events groupcritical boolean optional parameter for get ai analyst events maxscore number optional score value minscore number optional score value maxgroupscore number optional score value mingroupscore number optional score value saasonly boolean optional parameter for get ai analyst events output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 02 jul 2024 14 02 40 gmt", "content type" "application/json; charset=utf 8", "content length" "3410", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style s ", "cache control" "no store", "servertime" "0 486", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin" }, "reason" "ok", "json body" \[ { "summariser" "httpagentsummary", "acknowledged" false, "pinned" true, "createdat" 1646162137536, "attackphases" \[ 2 ], "mitretactics" \[ "command and control" ], "title" "possible http command and control", "id" "58b1c336 01b2 4418 86f8 3a53b0856aaa", "children" \[ "58b1c336 01b2 4418 86f8 3a53b0856aaa" ], "category" null, "currentgroup" null, "groupcategory" null, "groupscore" null, "grouppreviousgroups" null, "activityid" "da39a3ee", "groupingids" \[ "9e6a55b6" ], "groupbyactivity" false, "usertriggered" false, "externaltriggered" false, "aiascore" 41 915465465599745, "summary" "the device wef windomain local was observed making an http connection to the rare external endpoint 35 178 78 199, without a user agent header \n\nthe lack of this header suggests that this activity was initiated by a standalone software process as opposed to a web browser \n\nif such behaviour is unexpected, further investigation may be required to determine if this activity represents malicious command and control as opposed to legitimate telemetry of some form ", "periods" \[ { "start" 1646155303577, "end" 1646155303577 } ], "sender" null, "breachdevices" \[ { "identifier" "wef windomain local", "hostname" "wef windomain local", "ip" "192 168 1 3", "mac" "06 7b 81 5d 4b 5c", "subnet" null, "did" 18, "sid" 3 } ], "relatedbreaches" \[ { "modelname" "device / suspicious domain", "pbid" 1777, "threatscore" 33, "timestamp" 1646158351000 } ], "details" \[ \[ { "header" "device making suspicious connections", "contents" \[ { "key" null, "type" "device", "values" \[ { "identifier" "wef windomain local", "hostname" "wef windomain local", "ip" "192 168 1 3", "mac" "06 7b 81 5d 4b 5c", "subnet" null, "did" 18, "sid" 3 } ] }, { "key" "username observed prior to activity", get ai analyst groups retrieve incident groupings from darktrace, detailing the constituent events for each group endpoint url /aianalyst/groups method get input argument name type required description groupid string optional unique identifier uuid string optional unique identifier did number optional unique identifier excludedid number optional unique identifier sid number optional unique identifier excludesid number optional unique identifier master number optional parameter for get ai analyst groups includeacknowledged boolean optional parameter for get ai analyst groups includeallpinned boolean optional parameter for get ai analyst groups includeonlypinned boolean optional parameter for get ai analyst groups includegroupurl boolean optional url endpoint for the request locale string optional parameter for get ai analyst groups endtime string optional time value starttime string optional time value compliance boolean optional parameter for get ai analyst groups suspicious boolean optional parameter for get ai analyst groups critical boolean optional parameter for get ai analyst groups maxscore number optional score value minscore number optional score value saasonly boolean optional parameter for get ai analyst groups output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 02 jul 2024 14 21 53 gmt", "content type" "application/json; charset=utf 8", "content length" "2506", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style s ", "cache control" "no store", "servertime" "0 046", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin" }, "reason" "ok", "json body" \[ {}, {} ] } ] get antigena respond details retrieve comprehensive analysis and reporting details on current and historical darktrace respond/network actions endpoint url /antigena method get input argument name type required description fulldevicedetails boolean optional parameter for get antigena respond details includecleared boolean optional parameter for get antigena respond details includehistory boolean optional parameter for get antigena respond details needconfirming boolean optional parameter for get antigena respond details endtime number optional time value starttime number optional time value from string optional parameter for get antigena respond details to string optional parameter for get antigena respond details includeconnections boolean optional parameter for get antigena respond details responsedata string optional response data pbid number optional unique identifier output parameter type description status code number http status code of the response reason string response reason phrase actions array output field actions codeid number unique identifier did number unique identifier ip string output field ip action string output field action manual boolean output field manual triggerer string output field triggerer label string output field label detail string output field detail score number score value pbid number unique identifier model string output field model modeluuid string unique identifier start number output field start expires number output field expires blocked boolean output field blocked agemail boolean output field agemail active boolean output field active cleared boolean output field cleared connections array output field connections action string output field action label string output field label did number unique identifier example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "fri, 07 jun 2024 06 17 24 gmt", "content type" "application/json; charset=utf 8", "content length" "10", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style s ", "cache control" "no store", "servertime" "0 001", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin" }, "reason" "ok", "json body" { "actions" \[], "connections" \[], "devices" \[] } } ] get api data retrieve specific 'datatype' information from the darktrace api, utilizing path parameters to aid in system configuration endpoint url /{{datatype}}/sourcedevicetypes method get input argument name type required description datatype string required response data output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 06 feb 2024 07 01 54 gmt", "content type" "application/json; charset=utf 8", "content length" "2928", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 002", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" \[ {}, {} ] } ] get audit events retrieve audit events from darktrace for a given time range using 'start' and 'end' parameters permissions required audit log endpoint url /agemail/api/v1 0/system/audit/events method get input argument name type required description start number required unix timestamp start of the range to return audit events for end number required unix timestamp end of the range to return audit events for limit number optional maximum number of events to return (minimum 1, maximum 50) offset number optional number of events to offset by for pagination (minimum 0) excludedarktrace string optional string 'true' or 'false' for whether to exclude events for the 'darktrace' user from the response excludesystem string optional string 'true' or 'false' for whether to exclude events for the 'system' user from the response account string optional string account name to return events for eventtype string optional event type to return accepts either the string label or the type id integer output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "thu, 01 aug 2024 09 09 55 gmt", "content type" "application/json; charset=utf 8", "content length" "91", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "default src 'self'; script src 'self'; style src 'self' 'unsafe inline'; img src ", "cache control" "no store", "servertime" "0 087", "content encoding" "deflate", "vary" "accept encoding", "etag" "w/\\"7f dqogrc23nz2qnzr8v1jrcqwbjx4\\"" }, "reason" "ok", "json body" \[ {}, {} ] } ] get comments retrieves user comments on darktrace model breaches, providing insights into security events endpoint url /mbcomments method get input argument name type required description count number optional specifies the maximum number of items to return endtime string optional end time of data to return in millisecond format, relative to midnight january 1st 1970 utc pbid number optional id for a model breach starttime string optional start time of data to return in millisecond format, relative to midnight january 1st 1970 utc output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 06 feb 2024 10 43 51 gmt", "content type" "application/json; charset=utf 8", "content length" "147", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 013", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" \[ {} ] } ] get components retrieves component parts of defined models from darktrace, facilitating data referencing in model breaches endpoint url /components method get output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "mon, 05 feb 2024 10 25 21 gmt", "content type" "application/json; charset=utf 8", "content length" "940675", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 310", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" \[ {} ] } ] get dashboard statistics retrieve timeseries statistics from darktrace dashboards, filtering by direction and tag ids endpoint url /agemail/api/v1 0/dash/dash stats method get input argument name type required description dashkey string optional accepts direction and shorthand tag id multiple keys can be comma seperated maximum of 5 allowed days number optional number of days to return data for (minimum value is 1, maximum value is 30) output parameter type description status code number http status code of the response reason string response reason phrase resp object output field resp inbound object output field inbound 1721887200000 object output field 1721887200000 dtime number time value volume number output field volume n held number output field n held n junk number output field n junk n other actions number output field n other actions n last period number output field n last period 1721908800000 object output field 1721908800000 dtime number time value volume number output field volume n held number output field n held n junk number output field n junk n other actions number output field n other actions n last period number output field n last period 1721930400000 object output field 1721930400000 dtime number time value volume number output field volume n held number output field n held n junk number output field n junk n other actions number output field n other actions n last period number output field n last period example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "resp" {} } } ] get data loss retrieve data loss prevention (dlp) statistics for users, sorted by total breach count endpoint url /agemail/api/v1 0/dash/data loss method get input argument name type required description days number optional number of days to return data for (minimum 1, maximum 30) limit number optional number of items to return (minimum 1, maximum 100) output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "thu, 01 aug 2024 10 18 24 gmt", "content type" "application/json; charset=utf 8", "content length" "10", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "default src 'self'; script src 'self'; style src 'self' 'unsafe inline'; img src ", "cache control" "no store", "servertime" "0 088", "content encoding" "deflate", "vary" "accept encoding", "etag" "w/\\"2 vygp6pvfo4rvsftpoiwecreyic8\\"" }, "reason" "ok", "json body" {} } ] get details retrieves a time sorted list of connections and events for a specified device or entity in darktrace using the 'externalhostname' parameter endpoint url /details method get input argument name type required description application protocol string optional this filter can be used to filter the returned data by application protocol see /enums (api data task) for the list of application protocols count number optional max number of items to return ddid number optional identification number of a destination device modelled in the darktrace system to restrict data to deduplicate boolean optional display only one equivalent connection per hour destinationport number optional this filter can be used to filter the returned data by destination port did number optional identification number of a device modelled in the darktrace system externalhostname string required specifies an hostname to return details for eventtype string optional specifies an hostname to return details for from string optional start time of data to return in yyyy mm dd hh\ mm \ ss format fulldevicedetails boolean optional returns 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 intext string optional returns 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 msg string optional specifies the value of the message field in notice events to return details for typically used to specify user credential strings odid number optional identification number of a device modelled in the darktrace system to restrict data to typically used with ddid and odid to specifiy device pairs regardless of source/destination pbid number optional id for a model breach port number optional this filter can be used to filter the returned data by source or destination port protocol string optional this filter can be used to filter the returned data by ip protocol see /enums for the list of protocols sourceport number optional this filter can be used to filter the returned data by source port endtime string optional end time of data to return in millisecond format, relative to midnight january 1st 1970 utc starttime string optional start time of data to return in millisecond format, relative to midnight january 1st 1970 utc to string optional end time of data to return in yyyy mm dd hh\ mm \ ss format uid string optional specifies a connection uid to return output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 06 feb 2024 07 38 27 gmt", "content type" "application/json; charset=utf 8", "content length" "682", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 252", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" \[ {} ] } ] get device info retrieve detailed connectivity and activity data for a device in darktrace using the unique device id endpoint url /deviceinfo method get input argument name type required description datatype string optional response data did number required identification number of a device modelled in the darktrace system externaldomain string optional restrict external data to an particular domain name fulldevicedetails boolean optional returns 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 odid number optional identification number of a device modelled in the darktrace system to restrict data to typically used with ddid and odid to specifiy device pairs regardless of source/destination showallgraphdata boolean optional return an entry for all time intervals in the graph data, including zero counts similardevices number optional return data for the primary device and this number of similar devices output parameter type description status code number http status code of the response reason string response reason phrase deviceinfo array output field deviceinfo did number unique identifier similarityscore number score value domain string output field domain graphdata array response data file name string name of the resource file string output field file info object output field info totalused number output field totalused totalserved number output field totalserved totaldevicesandports number output field totaldevicesandports devicesandports array output field devicesandports file name string name of the resource file string output field file portsused array output field portsused file name string name of the resource file string output field file portsserved array output field portsserved file name string name of the resource file string output field file devicesused array output field devicesused file name string name of the resource file string output field file example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 06 feb 2024 08 44 58 gmt", "content type" "application/json; charset=utf 8", "content length" "173", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 001", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" { "deviceinfo" \[] } } ] get devices retrieve a comprehensive list of devices with detailed information as identified by darktrace endpoint url /devices method get input argument name type required description seensince string optional relative offset for activity devices with activity in the specified time period are returned the format is either a number representing a number of seconds before the current time, or a number with a modifier such as day or week ip string optional return data for this ip address iptime string optional return the device which had the ip at a given time mac string optional return the device with this mac address output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "mon, 05 feb 2024 10 09 21 gmt", "content type" "application/json; charset=utf 8", "content length" "1926", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 003", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" \[ { "id" 6, "did" 6, "sid" 6, "time" 1599009216000, "endtime" 1707103496000, "devicelabel" "internal traffic", "typename" "networkrange", "typelabel" "network range" }, { "id" 5, "did" 5, "sid" 5, "time" 1599009216000, "endtime" 1703259070000, "devicelabel" "link local traffic", "typename" "networkrange", "typelabel" "network range" }, { "id" 3, "did" 3, "sid" 3, "time" 1599009216000, "endtime" 1703259070000, "devicelabel" "internal multicast traffic", "typename" "networkrange", "typelabel" "network range" } ] } ] get email by uuid retrieve a summary of an email from darktrace using the provided unique identifier (uuid) endpoint url /agemail/api/v1 0/emails/{{uuid}} method get input argument name type required description uuid string required uuid of the email dtime number optional approximate timestamp of the email optional but will increase speed of the response output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "thu, 01 aug 2024 09 09 55 gmt", "content type" "application/json; charset=utf 8", "content length" "91", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "default src 'self'; script src 'self'; style src 'self' 'unsafe inline'; img src ", "cache control" "no store", "servertime" "0 087", "content encoding" "deflate", "vary" "accept encoding", "etag" "w/\\"7f dqogrc23nz2qnzr8v1jrcqwbjx4\\"" }, "reason" "ok", "json body" {} } ] get email search search for emails within darktrace using specified criteria and filters; requires a data body input endpoint url /agemail/api/v1 0/emails/search method post input argument name type required description data body object required response data page number required the page number (starting at 0) to choose itemsperpage number required number of items to be returned per page maximum is 50 timefrom number required unix timestamp (seconds or millisends) to start the search from timeto number required unix timestamp (seconds or millisends) to search until query object required object containing the filters to apply criterialist array required parameter for get email search apifilter string required apifilter to apply see /resources/filters value string required value to compare against not required if the type is flag (flag is true or not present) operator string required parameter for get email search mode string optional mode to apply the filters in either 'and' or 'or' output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "wed, 10 jul 2024 09 46 34 gmt", "content type" "application/json; charset=utf 8", "content length" "33", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style s ", "cache control" "no store", "servertime" "0 001", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin" }, "reason" "ok", "json body" \[ {} ] } ] get filters obtain a comprehensive list of available filters and their values for the darktrace /emails/search endpoint endpoint url /agemail/api/v1 0/resources/filters method get output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "fri, 02 aug 2024 08 22 33 gmt", "content type" "application/json; charset=utf 8", "content length" "1418", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "default src 'self';base uri 'self';block all mixed content;font src 'self' https ", "cache control" "no store", "servertime" "0 089", "content encoding" "deflate", "etag" "w/\\"1183 ud9gcpmr7aizll5ed3o1q3gzak8\\"", "x permitted cross domain policies" "none" }, "reason" "ok", "json body" \[ { "label" "recipient email", "type" "text free", "description" "the recipient of the email", "possiblevalues" null, "min" null, "max" null, "supportedoperators" \[ "=", "!=", " " ] }, { "label" "header other message id", "type" "text free", "description" "the content of the message id header for the email ", "possiblevalues" null, "min" null, "max" null, "supportedoperators" \[ "=", "!=", " " ] }, { "label" "header from email", "type" "text free", "description" "the email address present in the from header, also known as the header from address this will usually be the address displayed in a user's email client ", "possiblevalues" null, "min" null, "max" null, "supportedoperators" \[ "=", "!=", " " ] } ] } ] get incidents retrieve a list of incidents from darktrace based on time range and acknowledgment status, using 'start time', 'end time', and 'include ack' endpoint url /aianalyst/incidents method get input argument name type required description start time string required start of time range end time string required end of time range include ack boolean required include acknowledged incidents in output output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 06 feb 2024 08 54 41 gmt", "content type" "application/json; charset=utf 8", "content length" "4248", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 306", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" \[ {} ] } ] get intelfeed retrieve the latest threat intelligence information from darktrace intelfeed endpoint url /intelfeed method get input argument name type required description addentry string optional parameter for get intelfeed add list array optional parameter for get intelfeed description string optional parameter for get intelfeed expiry string optional parameter for get intelfeed fulldetails string optional parameter for get intelfeed hostname string optional name of the resource removeall string optional parameter for get intelfeed remove entry string optional parameter for get intelfeed source string optional parameter for get intelfeed sources string optional parameter for get intelfeed output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 13 feb 2024 15 50 31 gmt", "content type" "application/json; charset=utf 8", "content length" "67", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 000", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" \[ "cisco xdr automation", "default", "test" ] } ] get metric data retrieve time series values for metrics related to a device, enabling graph creation within darktrace endpoint url /metricdata method get input argument name type required description application protocol string optional this filter can be used to filter the returned data by application protocol see /enums (api data task) for the list of application protocols breachtimes boolean optional return additional information for the model breach times for the device ddid number optional identification number of a destination device modelled in the darktrace system to restrict data to destinationport number optional this filter can be used to filter the returned data by destination port did number optional identification number of a device modelled in the darktrace system from string optional start time of data to return in yyyy mm dd hh\ mm \ ss format fulldevicedetails boolean optional returns 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 interval number optional time interval size in seconds the maximum value for any minute in interval is returned metric string optional name of a metric see /metrics for the full list of current metrics odid number optional identification number of a device modelled in the darktrace system to restrict data to typically used with ddid and odid to specifiy device pairs regardless of source/destination port number optional this filter can be used to filter the returned data by source or destination port protocol string optional this filter can be used to filter the returned data by ip protocol see /enums for the list of protocols sourceport number optional this filter can be used to filter the returned data by source port starttime string optional start time of data to return in millisecond format, relative to midnight january 1st 1970 utc endtime string optional start time of data to return in millisecond format, relative to midnight january 1st 1970 utc output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 06 feb 2024 15 19 47 gmt", "content type" "application/json; charset=utf 8", "content length" "3656", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 004", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" \[ {} ] } ] get network info retrieve a summary of metric data detailing device interactions and communication patterns within the network endpoint url /network method get input argument name type required description application protocol string optional this filter can be used to filter the returned data by application protocol see /enums (api data task) for the list of application protocols destinationport number optional this filter can be used to filter the returned data by destination port intext string optional returns 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 did number optional identification number of a device modelled in the darktrace system ip string optional return data for this ip address from string optional start time of data to return in yyyy mm dd hh\ mm \ ss format to string optional end time of data to return in yyyy mm dd hh\ mm \ ss format fulldevicedetails boolean optional returns 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 metric string optional name of a metric see /metrics for the full list of current metrics port number optional this filter can be used to filter the returned data by source or destination port protocol string optional this filter can be used to filter the returned data by ip protocol see /enums for the list of protocols sourceport number optional this filter can be used to filter the returned data by source port starttime string optional start time of data to return in millisecond format, relative to midnight january 1st 1970 utc endtime string optional end time of data to return in millisecond format, relative to midnight january 1st 1970 utc output parameter type description status code number http status code of the response reason string response reason phrase statistics array output field statistics views array output field views view string output field view in boolean output field in out boolean output field out connection status array status value connections string output field connections in boolean output field in out boolean output field out applicationprotocols array output field applicationprotocols file name string name of the resource file string output field file subnets array output field subnets file name string name of the resource file string output field file devices array output field devices file name string name of the resource file string output field file metric object output field metric mlid number unique identifier name string name of the resource label string output field label units string output field units example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "wed, 07 feb 2024 07 37 43 gmt", "content type" "application/json; charset=utf 8", "content length" "1329", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 053", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" { "statistics" \[], "subnets" \[], "devices" \[], "metric" {}, "connections" \[] } } ] get similar devices retrieve a list of devices with similar characteristics or behaviors to a specified device in darktrace endpoint url /similardevices method get input argument name type required description count number optional count value did number optional identification number of a device modelled in the darktrace system output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "wed, 07 feb 2024 08 57 34 gmt", "content type" "application/json; charset=utf 8", "content length" "10", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 001", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" \[ {} ] } ] get status retrieve current system health and operational metrics from darktrace for status monitoring endpoint url /status method get input argument name type required description include children boolean optional return information for child instances, probes and sensors output parameter type description status code number http status code of the response reason string response reason phrase excesstraffic boolean output field excesstraffic time string time value installed string output field installed mobileappconfigured boolean output field mobileappconfigured version string output field version ipaddress string output field ipaddress modelsupdated string output field modelsupdated modelpackageversion string output field modelpackageversion bundleversion string output field bundleversion bundledate string date value bundleinstalleddate string date value metadata object response data maximumossensors number output field maximumossensors hostname string name of the resource uuid string unique identifier inoculation boolean output field inoculation applianceoscode string output field applianceoscode license string output field license saasconnectorlicense string output field saasconnectorlicense antigenasaaslicense string output field antigenasaaslicense syslogtlssha1fingerprint string output field syslogtlssha1fingerprint syslogtlssha256fingerprint string output field syslogtlssha256fingerprint antigenanetworkenabled boolean output field antigenanetworkenabled example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "wed, 07 feb 2024 09 27 02 gmt", "content type" "application/json; charset=utf 8", "content length" "1976", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "cache control" "no store", "servertime" "0 074", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block", "strict transport security" "max age=31536000; includesubdomains;" }, "reason" "ok", "json body" { "excesstraffic" false, "time" "2024 02 07 09 27", "installed" "2020 09 02", "mobileappconfigured" false, "version" "6 1 30 (9e601e4e)", "ipaddress" "10 140 11 114", "modelsupdated" "2024 02 07 05 40 30", "modelpackageversion" "6 0 23 4438 20240207051038 g040ca7", "bundleversion" "61061", "bundledate" "2024 01 25 18 51 32", "bundleinstalleddate" "2024 02 02 10 23 23", "metadata" null, "maximumossensors" 255, "hostname" "usw1 54655 01", "uuid" "0fb2ed67 98ab 4cc8 afcc e4cca104d430" } } ] get subnets obtain a detailed list of identified subnets from darktrace without the need for additional input parameters endpoint url /subnets method get input argument name type required description seensince string optional parameter for get subnets output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "wed, 07 feb 2024 09 45 05 gmt", "content type" "application/json; charset=utf 8", "content length" "523", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 001", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" \[ {} ] } ] get tags retrieves comprehensive details for all tags in the darktrace ecosystem, including metadata and associated information endpoint url /tags method get output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 06 feb 2024 10 08 13 gmt", "content type" "application/json; charset=utf 8", "content length" "4137", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 001", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" \[ {} ] } ] get user anomaly retrieve user anomaly statistics from darktrace, ranked by anomaly level to identify potential threats endpoint url /agemail/api/v1 0/dash/user anomaly method get input argument name type required description days number optional number of days to return data for (minimum 1, maximum 30) limit number optional number of items to return (minimum 1, maximum 100) output parameter type description status code number http status code of the response reason string response reason phrase leeroy jenkins\@storosta com object output field leeroy jenkins\@storosta com mailto\ leeroy jenkins\@storosta com n emails number output field n emails total emails number output field total emails n last period number output field n last period n last week number output field n last week percentage number output field percentage n links number output field n links n attachments number output field n attachments example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "thu, 01 aug 2024 10 33 08 gmt", "content type" "application/json; charset=utf 8", "content length" "133", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "default src 'self'; script src 'self'; style src 'self' 'unsafe inline'; img src ", "cache control" "no store", "servertime" "0 114", "content encoding" "deflate", "vary" "accept encoding", "etag" "w/\\"9a vtyvz6yldg1dmpswiubye+/zr5u\\"" }, "reason" "ok", "json body" { "leeroy jenkins\@storosta com" {} } } ] get valid audit event types retrieve a list of valid audit event types from darktrace, verifying audit log permissions endpoint url /agemail/api/v1 0/system/audit/eventtypes method get output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "thu, 01 aug 2024 09 09 55 gmt", "content type" "application/json; charset=utf 8", "content length" "91", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "default src 'self'; script src 'self'; style src 'self' 'unsafe inline'; img src ", "cache control" "no store", "servertime" "0 087", "content encoding" "deflate", "vary" "accept encoding", "etag" "w/\\"7f dqogrc23nz2qnzr8v1jrcqwbjx4\\"" }, "reason" "ok", "json body" \[ {}, {} ] } ] list endpoint details retrieve detailed information on endpoints, such as location, ip address, and device connection data for external ips and hostnames endpoint url /endpointdetails method get input argument name type required description additionalinfo boolean optional return additional information about the endpoint devices boolean optional return a list of devices which have recently connected to the endpoint score boolean optional return rarity data for this endpoint hostname string optional return data for this hostname ip string optional return data for this ip address responsedata string optional when given the name of a top level field or object, restricts the returned json to only that field or object output parameter type description status code number http status code of the response reason string response reason phrase ip string output field ip firsttime number time value country string output field country asn string output field asn city string output field city region string output field region name string name of the resource longitude number output field longitude latitude number output field latitude subnetlabel string output field subnetlabel subnetid string unique identifier subnetnetwork string output field subnetnetwork ipage number output field ipage iptime string time value devices array output field devices did number unique identifier macaddress string output field macaddress vendor string output field vendor ip string output field ip ips array output field ips ip string output field ip timems number output field timems time string time value example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 02 jul 2024 13 34 06 gmt", "content type" "application/json; charset=utf 8", "content length" "62", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style s ", "cache control" "no store", "servertime" "0 011", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin" }, "reason" "ok", "json body" { "ip" "172 217 169 36", "firsttime" 1528807105000, "country" "united states", "asn" "as15169 google llc", "city" "", "region" "north america", "name" "", "longitude" 97 822, "latitude" 37 751, "subnetlabel" "", "subnetid" "19", "subnetnetwork" "10 160 14 0/24", "ipage" 120916756, "iptime" "2020 09 02 01 33 43", "devices" \[] } } ] list metrics retrieve a comprehensive list of available metrics from the darktrace system for analysis and monitoring endpoint url /metrics method get output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 06 feb 2024 10 34 27 gmt", "content type" "application/json; charset=utf 8", "content length" "18804", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 019", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" \[ {} ] } ] list model breaches retrieve detailed information on identified model breaches within the darktrace ecosystem endpoint url /modelbreaches method get input argument name type required description deviceattop boolean optional return the device json object as a value of the top level object rather than within each matched component did number optional identification number of a device modelled in the darktrace system starttime string optional start time of data to return in millisecond format, relative to midnight january 1st 1970 utc endtime string optional end time of data to return in millisecond format, relative to midnight january 1st 1970 utc from string optional start time of data to return in yyyy mm dd hh\ mm \ ss format to string optional end time of data to return in yyyy mm dd hh\ mm \ ss format historicmodelonly boolean optional return the json for the historic version of the model details only, rather than both the historic and current definition includebreachurl boolean optional return a url for the model breach in the long form of the model breach data, this requires that the fqdn configuration parameter is set includeacknowledged boolean optional include acknowledged breaches in the data minimal boolean optional reduce the amount of data returned for the api call this parameter defaults to false when any of the starttime, from, pid, uuid, pbid or did parameters are used pbid number optional id for a model breach pid number optional only return model breaches for the specified model uuid string optional specifies a connection uid to return output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "wed, 07 feb 2024 07 25 14 gmt", "content type" "application/json; charset=utf 8", "content length" "1601", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 005", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" \[ {} ] } ] list models retrieve a list of darktrace models for reference in analyzing model breach data endpoint url /models method get output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "wed, 07 feb 2024 07 28 00 gmt", "content type" "application/json; charset=utf 8", "content length" "332557", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 091", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" \[ {} ] } ] list similar devices retrieves a list of devices with similar characteristics to a specified device within the darktrace network endpoint url /similardevices method get input argument name type required description did number optional unique identifier count number optional specifies the maximum number of items to return fulldevicedetails boolean optional returns 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 token string optional takes a token value returned by a system notice about a change in similar devices for a specified device will return the old and new list of devices responsedata string optional when given the name of a top level field or object, restricts the returned json to only that field or object output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 02 jul 2024 13 43 24 gmt", "content type" "application/json; charset=utf 8", "content length" "10", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style s ", "cache control" "no store", "servertime" "0 002", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin" }, "reason" "ok", "json body" \[ {} ] } ] post action executes a specified action on an email within darktrace, identified by its uuid, subject to user permissions endpoint url /agemail/api/v1 0/emails/{{uuid}}/action method post input argument name type required description uuid string required uuid of the email dtime number optional approximate timestamp of the email optional but will increase speed of the response data body object required response data action string required action to take on the email either 'hold', 'release' or if requested 'approve release' / 'reject release' recipients array required list of recipient email addresses to perform the action on for hold, these must be a subset of the original recipients of the email returnemail boolean optional boolean to say whether to return the email object as emaildetails format or not after the action is taken if true, will wait up to 5 seconds for the release output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "sun, 04 aug 2024 16 06 16 gmt", "content type" "application/json; charset=utf 8", "content length" "10", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "default src 'self'; script src 'self'; style src 'self' 'unsafe inline'; img src ", "cache control" "no store", "servertime" "0 107", "content encoding" "deflate", "vary" "accept encoding", "etag" "w/\\"2 l9fw4vuo7kr8cvblt4zamcqxz0w\\"" }, "reason" "ok", "json body" {} } ] return information about all tags retrieve comprehensive details on all tags within darktrace, including associated permissions and email logs endpoint url /agemail/api/v1 0/resources/tags method get output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" \[] } ] return information about darktrace/email actions retrieve detailed information about email related actions within the darktrace platform endpoint url /agemail/api/v1 0/resources/actions method get output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "fri, 02 aug 2024 08 15 05 gmt", "content type" "application/json; charset=utf 8", "content length" "544", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "default src 'self'; script src 'self'; style src 'self' 'unsafe inline'; img src ", "cache control" "no store", "servertime" "1 045", "content encoding" "deflate", "vary" "accept encoding", "etag" "w/\\"8d8 z2zfe/t+cjz4r/25pvugaxuckxc\\"" }, "reason" "ok", "json body" \[ { "action" "hold", "description" "hold message, optionally sending messages to sender and/or recipient(s)", "readable name" "hold message" }, { "action" "movetojunk", "description" null, "readable name" "move to junk" }, { "action" "addbanner", "description" "add banner", "readable name" "add banner" } ] } ] return the raw body of this email retrieve the raw body of an email from darktrace using the provided unique identifier (uuid) endpoint url /agemail/api/v1 0/emails/{{uuid}}/download method get input argument name type required description uuid string required uuid of the email output parameter type description status code number http status code of the response reason string response reason phrase uuid string unique identifier direction string output field direction dtime string time value dtime unix number output field dtime unix header from string output field header from header from email string output field header from email header from personla string output field header from personla header subject string output field header subject in progress boolean output field in progress n links number output field n links n attachments number output field n attachments model score number score value campaign id string unique identifier rcpts array output field rcpts rcpt to string output field rcpt to rcpt status string status value tags array output field tags is read boolean output field is read rcpt actions taken array output field rcpt actions taken action status boolean status value is group email boolean output field is group email summary array output field summary example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "thu, 01 aug 2024 09 09 55 gmt", "content type" "application/json; charset=utf 8", "content length" "91", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "default src 'self'; script src 'self'; style src 'self' 'unsafe inline'; img src ", "cache control" "no store", "servertime" "0 087", "content encoding" "deflate", "vary" "accept encoding", "etag" "w/\\"7f dqogrc23nz2qnzr8v1jrcqwbjx4\\"" }, "reason" "ok", "json body" { "uuid" "string", "direction" "string", "dtime" "string", "dtime unix" 0, "header from" "string", "header from email" "string", "header from personla" "string", "header subject" "string", "in progress" true, "n links" 0, "n attachments" 0, "model score" 0, "campaign id" "string", "rcpts" \[] } } ] unacknowledge event reverts the acknowledgment status of an ai analyst event in darktrace using the specified uuid endpoint url /modelbreaches/{{pbid}}/unacknowledge method post input argument name type required description pbid number required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase response string output field response example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "tue, 13 feb 2024 15 23 21 gmt", "content type" "application/json; charset=utf 8", "content length" "35", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style ", "cache control" "no store", "servertime" "0 024", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin", "x xss protection" "1; mode=block" }, "reason" "ok", "json body" { "response" "success" } } ] unlock a link reverses a previous lock, enabling access to a link initially restricted by darktrace endpoint url /agemail/api/v1 0/admin/decode link method get input argument name type required description url string optional the link to unlock output parameter type description status code number http status code of the response reason string response reason phrase link string output field link displayhash string output field displayhash example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "thu, 01 aug 2024 09 09 55 gmt", "content type" "application/json; charset=utf 8", "content length" "91", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "default src 'self'; script src 'self'; style src 'self' 'unsafe inline'; img src ", "cache control" "no store", "servertime" "0 087", "content encoding" "deflate", "vary" "accept encoding", "etag" "w/\\"7f dqogrc23nz2qnzr8v1jrcqwbjx4\\"" }, "reason" "ok", "json body" { "link" "string", "displayhash" "string" } } ] update antigena respond state modifies or activates darktrace respond actions by using the provided 'codeid' endpoint url /antigena method post input argument name type required description codeid number required unique identifier activate boolean optional parameter for update antigena respond state duration number optional parameter for update antigena respond state reason string optional response reason phrase clear boolean optional parameter for update antigena respond state output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "server" "nginx", "date" "fri, 07 jun 2024 06 23 27 gmt", "content type" "application/json; charset=utf 8", "content length" "10", "cross origin embedder policy" "require corp", "cross origin opener policy" "same origin allow popups", "cross origin resource policy" "same origin", "x robots tag" "noindex, noindex", "permissions policy" "accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), ", "content security policy" "script src 'self';img src 'self' data blob data uris;media src 'self';style s ", "cache control" "no store", "servertime" "0 001", "content encoding" "deflate", "vary" "accept encoding", "x frame options" "sameorigin" }, "reason" "ok", "json body" \[] } ] response headers header description example cache control directives for caching mechanisms no store content encoding http response header content encoding gzip content length the length of the response body in bytes 1418 content security policy http response header content security policy default src 'self';base uri 'self';block all mixed content;font src 'self' https data ;form action 'self';frame ancestors 'self';img src 'self' data ;object src 'none';script src 'self';script src attr 'none';style src 'self' https 'unsafe inline';upgrade insecure requests content type the media type of the resource text/html; charset=utf 8 cross origin embedder policy http response header cross origin embedder policy require corp cross origin opener policy http response header cross origin opener policy same origin allow popups cross origin resource policy http response header cross origin resource policy same origin date the date and time at which the message was originated thu, 01 aug 2024 09 09 55 gmt etag an identifier for a specific version of a resource w/"8d8 z2zfe/t+cjz4r/25pvugaxuckxc" expect ct http response header expect ct max age=0 origin agent cluster http response header origin agent cluster ?1 permissions policy http response header permissions policy accelerometer=(), autoplay= , camera=(), display capture=(), encrypted media=(), fullscreen=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=() referrer policy http response header referrer policy same origin server information about the software used by the origin server nginx servertime http response header servertime 0 310 strict transport security http response header strict transport security max age=31536000; includesubdomains; transfer encoding http response header transfer encoding chunked vary http response header vary accept encoding x content security policy http response header x content security policy default src 'self'; script src 'self'; style src 'self' 'unsafe inline'; img src 'self' data blob data uris data x content type options http response header x content type options nosniff x dns prefetch control http response header x dns prefetch control off x download options http response header x download options noopen x frame options http response header x frame options sameorigin x permitted cross domain policies http response header x permitted cross domain policies none