Darktrace
Darktrace is an AI-powered cybersecurity platform that autonomously detects and responds to cyber threats in real-time.
Darktrace is a leading cyber AI company that provides advanced threat detection and response capabilities. The Darktrace connector for Swimlane Turbine enables seamless integration with Darktrace's AI-driven security platform, allowing users to automate incident response, enrich security data, and gain comprehensive insights into network activities. By leveraging this integration, Swimlane Turbine users can enhance their security operations with real-time threat intelligence, streamline workflows, and improve overall incident management efficiency.
Prerequisites
Before you can use the Darktrace connector for Turbine, you'll need access to the Darktrace API. This requires the following:
- Darktrace API Authentication using the following parameters:
- URL: The endpoint URL for accessing the Darktrace API.
- API Token: A token used to authenticate API requests.
- Private Token: An additional token required for secure API communication.
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
Additional Documentation
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 to streamline incident response workflows.
Endpoint
- URL: /modelbreaches/{{pbid}}/acknowledge
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.pbid | number | Required | Parameters for the Acknowledge Event action |
Input Example
{"path_parameters":{"pbid":40974}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
response | string | Output field: response |
Output 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":"...
Add Comment to AI Analyst Event
Add a user-defined comment to a Darktrace AI Analyst Event using the specified incident ID and message.
Endpoint
- URL: /aianalyst/incident/comments
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.incident_id | string | Required | Parameters for the Add Comment to AI Analyst Event action |
message | string | Optional | Response message |
Input Example
{"parameters":{"incident_id":"58b1c336-01b2-4418-86f8-3a53b0856aaa"},"json_body":{"message":"Test Comment"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
comments | array | Output field: comments |
comments.username | string | Name of the resource |
comments.time | number | Time value |
comments.incident_id | string | Unique identifier |
comments.message | string | Response message |
Output 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';...
Add Comment to Model Breach
Add 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 |
|---|---|---|---|
path_parameters.pbid | number | Required | Parameters for the Add Comment to Model Breach action |
message | string | Optional | Response message |
Input Example
{"json_body":{"message":"This is Test Comment."},"path_parameters":{"pbid":49411}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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';...
Antigena Manual
Initiate manual Darktrace RESPOND/Network actions by specifying device ID, action type, duration, and reason.
Endpoint
- URL: /antigena/manual
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
did | number | Optional | Unique identifier |
action | string | Optional | Parameter for Antigena Manual |
duration | number | Optional | Parameter for Antigena Manual |
reason | string | Optional | Response reason phrase |
connections | array | Optional | Parameter for Antigena Manual |
connections.src | string | Optional | Parameter for Antigena Manual |
connections.dst | string | Optional | Parameter for Antigena Manual |
connections.port | number | Optional | Parameter for Antigena Manual |
Input Example
{"json_body":{"did":1234,"action":"connection","duration":120,"reason":"","connections":[{"src":"10.10.10.10","dst":"8.8.8.8","port":443}]}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
codeid | number | Unique identifier |
Output 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'...
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 |
|---|---|---|---|
parameters.endtime | number | Optional | Parameters for the Antigena Summary action |
parameters.starttime | number | Optional | Parameters for the Antigena Summary action |
parameters.responsedata | string | Optional | Parameters for the Antigena Summary action |
Input Example
{"parameters":{"endtime":100,"starttime":100,"responsedata":"string"}}
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 |
Output 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'...
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 |
|---|---|---|---|
parameters.additionalinfo | boolean | Optional | Return additional information about the endpoint. |
parameters.devices | boolean | Optional | Return a list of devices which have recently connected to the endpoint. |
parameters.hostname | string | Optional | Return data for this hostname. |
parameters.ip | string | Optional | Return data for this IP address. |
parameters.score | boolean | Optional | Return the popularity scores for external endpoints. |
Input Example
{"parameters":{"additionalinfo":true,"devices":true,"hostname":"www.darktrace.com","ip":"8.8.8.8","score":true}}
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 |
Output 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":...
Execute Advanced Search
Execute an advanced search in Darktrace using a base64-encoded query and export the results in JSON format.
Endpoint
- URL: /advancedsearch/api/search/{{base64_query}}
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.base64_query | string | Required | Parameters for the Execute Advanced Search action |
Input Example
{"path_parameters":{"base64_query":"eyJzZWFyY2giOiJAdHlwZTpjb25uIEFORCBAZmllbGRzLnByb3RvOnRjcCBBTkQgTk9UIEBmaWVsZHMuY29ubl9zdGF0ZTpcIlMwXCIgQU5EIE5PVCBAZmllbGRzLmNvbm5fc3RhdGU6XCJSRUpcIiBBTkQgKEBmaWVsZHMub3JpZ19wa3RzOjAgT1IgQGZpZWxkcy5yZXNwX3BrdHM6MCkgQU5EIChAZmllbGRzLmRlc3RfcG9ydDpcIjQ0M1wiIE9SIEBmaWVsZHMuZGVzdF9wb3J0OlwiODBcIikiLCJmaWVsZHMiOltdLCJvZmZzZXQiOjAsInRpbWVmcmFtZSI6IjQzMjAwIiwidGltZSI6eyJ1c2VyX2ludGVydmFsIjowfX0="}}
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 |
_shards.total | number | Output field: _shards.total |
_shards.successful | number | Whether the operation was successful |
_shards.skipped | number | Output field: _shards.skipped |
_shards.failed | number | Output field: _shards.failed |
hits | object | Output field: hits |
hits.total | number | Output field: hits.total |
hits.max_score | number | Score value |
hits.hits | array | Output field: hits.hits |
hits.hits._index | string | Output field: hits.hits._index |
hits.hits._type | string | Type of the resource |
hits.hits._id | string | Unique identifier |
hits.hits._score | object | Score value |
hits.hits._source | object | Output field: hits.hits._source |
hits.hits._source.@fields | object | Output field: hits.hits._source.@fields |
[email protected]_pkts | number | Output field: [email protected]_pkts |
hits.hits._source.@type | string | Type of the resource |
hits.hits._source.@timestamp | string | Output field: hits.hits._source.@timestamp |
hits.hits._source.@message | string | Response message |
hits.hits.sort | array | Output field: hits.hits.sort |
darktraceChildError | string | Error message if any |
Output 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'...
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 |
|---|---|---|---|
parameters.days | number | Optional | Number of days to query over. (Minimum value is 1, Maximum value is 30). |
Input Example
{"parameters":{"days":7}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
hold | object | Output field: hold |
hold.value | number | Value for the parameter |
moveToJunk | object | Output field: moveToJunk |
moveToJunk.value | number | Value for the parameter |
attachment_actions | object | Output field: attachment_actions |
attachment_actions.value | number | Value for the parameter |
link_actions | object | Output field: link_actions |
link_actions.value | number | Value for the parameter |
other | object | Output field: other |
other.value | number | Value for the parameter |
Output 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';...
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 |
|---|---|---|---|
parameters.incident_id | string | Required | Parameters for the Get AI Analyst Comments action |
Input Example
{"parameters":{"incident_id":"58b1c336-01b2-4418-86f8-3a53b0856aaa"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
comments | array | Output field: comments |
comments.username | string | Name of the resource |
comments.time | number | Time value |
comments.incident_id | string | Unique identifier |
comments.message | string | Response message |
Output 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';...
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 |
|---|---|---|---|
parameters.groupid | string | Optional | Parameters for the Get AI Analyst Events action |
parameters.uuid | string | Optional | Parameters for the Get AI Analyst Events action |
parameters.did | number | Optional | Parameters for the Get AI Analyst Events action |
parameters.excludedid | number | Optional | Parameters for the Get AI Analyst Events action |
parameters.sid | number | Optional | Parameters for the Get AI Analyst Events action |
parameters.excludesid | number | Optional | Parameters for the Get AI Analyst Events action |
parameters.master | number | Optional | Parameters for the Get AI Analyst Events action |
parameters.includeacknowledged | boolean | Optional | Parameters for the Get AI Analyst Events action |
parameters.includeallpinned | boolean | Optional | Parameters for the Get AI Analyst Events action |
parameters.includeonlypinned | boolean | Optional | Parameters for the Get AI Analyst Events action |
parameters.includeincidenteventurl | boolean | Optional | Parameters for the Get AI Analyst Events action |
parameters.locale | string | Optional | Parameters for the Get AI Analyst Events action |
parameters.endtime | string | Optional | Parameters for the Get AI Analyst Events action |
parameters.starttime | string | Optional | Parameters for the Get AI Analyst Events action |
parameters.groupcompliance | boolean | Optional | Parameters for the Get AI Analyst Events action |
parameters.groupsuspicious | boolean | Optional | Parameters for the Get AI Analyst Events action |
parameters.groupcritical | boolean | Optional | Parameters for the Get AI Analyst Events action |
parameters.maxscore | number | Optional | Parameters for the Get AI Analyst Events action |
parameters.minscore | number | Optional | Parameters for the Get AI Analyst Events action |
parameters.maxgroupscore | number | Optional | Parameters for the Get AI Analyst Events action |
parameters.mingroupscore | number | Optional | Parameters for the Get AI Analyst Events action |
parameters.saasonly | boolean | Optional | Parameters for the Get AI Analyst Events action |
Input Example
{"parameters":{"groupid":"g04a3f36e-4u8w-v9dh-x6lb-894778cf9633","uuid":"04a3f36e-4u8w-v9dh-x6lb-894778cf9633","did":123,"excludedid":123,"sid":123,"excludesid":123,"master":123,"includeacknowledged":true,"includeallpinned":true,"includeonlypinned":true,"includeincidenteventurl":true,"locale":"en_US","endtime":"1646611200000","starttime":"1646611200000","groupcompliance":true,"groupsuspicious":true,"groupcritical":true,"maxscore":50,"minscore":10,"maxgroupscore":40,"mingroupscore":10,"saasonly":true}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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...
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 |
|---|---|---|---|
parameters.groupid | string | Optional | Parameters for the Get AI Analyst Groups action |
parameters.uuid | string | Optional | Parameters for the Get AI Analyst Groups action |
parameters.did | number | Optional | Parameters for the Get AI Analyst Groups action |
parameters.excludedid | number | Optional | Parameters for the Get AI Analyst Groups action |
parameters.sid | number | Optional | Parameters for the Get AI Analyst Groups action |
parameters.excludesid | number | Optional | Parameters for the Get AI Analyst Groups action |
parameters.master | number | Optional | Parameters for the Get AI Analyst Groups action |
parameters.includeacknowledged | boolean | Optional | Parameters for the Get AI Analyst Groups action |
parameters.includeallpinned | boolean | Optional | Parameters for the Get AI Analyst Groups action |
parameters.includeonlypinned | boolean | Optional | Parameters for the Get AI Analyst Groups action |
parameters.includegroupurl | boolean | Optional | Parameters for the Get AI Analyst Groups action |
parameters.locale | string | Optional | Parameters for the Get AI Analyst Groups action |
parameters.endtime | string | Optional | Parameters for the Get AI Analyst Groups action |
parameters.starttime | string | Optional | Parameters for the Get AI Analyst Groups action |
parameters.compliance | boolean | Optional | Parameters for the Get AI Analyst Groups action |
parameters.suspicious | boolean | Optional | Parameters for the Get AI Analyst Groups action |
parameters.critical | boolean | Optional | Parameters for the Get AI Analyst Groups action |
parameters.maxscore | number | Optional | Parameters for the Get AI Analyst Groups action |
parameters.minscore | number | Optional | Parameters for the Get AI Analyst Groups action |
parameters.saasonly | boolean | Optional | Parameters for the Get AI Analyst Groups action |
Input Example
{"parameters":{"groupid":"g04a3f36e-4u8w-v9dh-x6lb-894778cf9633","uuid":"04a3f36e-4u8w-v9dh-x6lb-894778cf9633","did":123,"excludedid":123,"sid":123,"excludesid":123,"master":123,"includeacknowledged":true,"includeallpinned":true,"includeonlypinned":true,"includegroupurl":true,"locale":"en_US","endtime":"1646611200000","starttime":"1646611200000","compliance":true,"suspicious":true,"critical":true,"maxscore":50,"minscore":10,"saasonly":true}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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...
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 |
|---|---|---|---|
parameters.fulldevicedetails | boolean | Optional | Parameters for the Get Antigena RESPOND Details action |
parameters.includecleared | boolean | Optional | Parameters for the Get Antigena RESPOND Details action |
parameters.includehistory | boolean | Optional | Parameters for the Get Antigena RESPOND Details action |
parameters.needconfirming | boolean | Optional | Parameters for the Get Antigena RESPOND Details action |
parameters.endtime | number | Optional | Parameters for the Get Antigena RESPOND Details action |
parameters.starttime | number | Optional | Parameters for the Get Antigena RESPOND Details action |
parameters.from | string | Optional | Parameters for the Get Antigena RESPOND Details action |
parameters.to | string | Optional | Parameters for the Get Antigena RESPOND Details action |
parameters.includeconnections | boolean | Optional | Parameters for the Get Antigena RESPOND Details action |
parameters.responsedata | string | Optional | Parameters for the Get Antigena RESPOND Details action |
parameters.pbid | number | Optional | Parameters for the Get Antigena RESPOND Details action |
Input Example
{"parameters":{"fulldevicedetails":false,"includecleared":false,"includehistory":false,"needconfirming":false,"endtime":100,"starttime":100,"from":"string","to":"string","includeconnections":false,"responsedata":"string","pbid":10}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
actions | array | Output field: actions |
actions.codeid | number | Unique identifier |
actions.did | number | Unique identifier |
actions.ip | string | Output field: actions.ip |
actions.action | string | Output field: actions.action |
actions.manual | boolean | Output field: actions.manual |
actions.triggerer | string | Output field: actions.triggerer |
actions.label | string | Output field: actions.label |
actions.detail | string | Output field: actions.detail |
actions.score | number | Score value |
actions.pbid | number | Unique identifier |
actions.model | string | Output field: actions.model |
actions.modeluuid | string | Unique identifier |
actions.start | number | Output field: actions.start |
actions.expires | number | Output field: actions.expires |
actions.blocked | boolean | Output field: actions.blocked |
actions.agemail | boolean | Output field: actions.agemail |
actions.active | boolean | Output field: actions.active |
actions.cleared | boolean | Output field: actions.cleared |
connections | array | Output field: connections |
connections.action | string | Output field: connections.action |
connections.label | string | Output field: connections.label |
connections.did | number | Unique identifier |
Output 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';...
Get API Data
Retrieve specific 'datatype' information from the Darktrace API using path parameters for system configuration.
Endpoint
- URL: /{{datatype}}/sourcedevicetypes
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.datatype | string | Required | Parameters for the Get API Data action |
Input Example
{"path_parameters":{"datatype":"filtertypes"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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"...
Get Audit Events
Retrieve audit events from Darktrace for a specified 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 |
|---|---|---|---|
parameters.start | number | Required | Unix timestamp start of the range to return audit events for. |
parameters.end | number | Required | Unix timestamp end of the range to return audit events for. |
parameters.limit | number | Optional | Maximum number of events to return (Minimum 1, Maximum 50). |
parameters.offset | number | Optional | Number of events to offset by for pagination (Minimum 0). |
parameters.excludeDarktrace | string | Optional | String 'true' or 'false' for whether to exclude events for the 'darktrace' user from the response. |
parameters.excludeSystem | string | Optional | String 'true' or 'false' for whether to exclude events for the 'system' user from the response. |
parameters.account | string | Optional | String account name to return events for. |
parameters.eventType | string | Optional | Event type to return. Accepts either the string label or the type ID integer. |
Input Example
{"parameters":{"start":123,"end":123,"limit":20,"offset":123,"excludeDarktrace":"string","excludeSystem":"string","account":"string","eventType":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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';...
Get Comments
Retrieve user comments on Darktrace model breaches to gain insights into security events.
Endpoint
- URL: /mbcomments
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.count | number | Optional | Specifies the maximum number of items to return. |
parameters.endtime | string | Optional | End time of data to return in millisecond format, relative to midnight January 1st 1970 UTC. |
parameters.pbid | number | Optional | ID for a model breach. |
parameters.starttime | string | Optional | Start time of data to return in millisecond format, relative to midnight January 1st 1970 UTC. |
Input Example
{"parameters":{"count":30,"endtime":"1704282955000","pbid":10,"starttime":"1704196555000"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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":...
Get Components
Retrieve component parts of defined models from Darktrace to facilitate 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 |
Output 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","servertim...
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 |
|---|---|---|---|
parameters.dashKey | string | Optional | Accepts direction and shorthand Tag ID. Multiple keys can be comma seperated. Maximum of 5 allowed. |
parameters.days | number | Optional | Number of days to return data for. (Minimum value is 1, Maximum value is 30). |
Input Example
{"parameters":{"dashKey":"inbound,outbound","days":7}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
resp | object | Output field: resp |
resp.inbound | object | Output field: resp.inbound |
resp.inbound.1721887200000 | object | Output field: resp.inbound.1721887200000 |
resp.inbound.1721887200000.dtime | number | Time value |
resp.inbound.1721887200000.volume | number | Output field: resp.inbound.1721887200000.volume |
resp.inbound.1721887200000.n_held | number | Output field: resp.inbound.1721887200000.n_held |
resp.inbound.1721887200000.n_junk | number | Output field: resp.inbound.1721887200000.n_junk |
resp.inbound.1721887200000.n_other_actions | number | Output field: resp.inbound.1721887200000.n_other_actions |
resp.inbound.1721887200000.n_last_period | number | Output field: resp.inbound.1721887200000.n_last_period |
resp.inbound.1721908800000 | object | Output field: resp.inbound.1721908800000 |
resp.inbound.1721908800000.dtime | number | Time value |
resp.inbound.1721908800000.volume | number | Output field: resp.inbound.1721908800000.volume |
resp.inbound.1721908800000.n_held | number | Output field: resp.inbound.1721908800000.n_held |
resp.inbound.1721908800000.n_junk | number | Output field: resp.inbound.1721908800000.n_junk |
resp.inbound.1721908800000.n_other_actions | number | Output field: resp.inbound.1721908800000.n_other_actions |
resp.inbound.1721908800000.n_last_period | number | Output field: resp.inbound.1721908800000.n_last_period |
resp.inbound.1721930400000 | object | Output field: resp.inbound.1721930400000 |
resp.inbound.1721930400000.dtime | number | Time value |
resp.inbound.1721930400000.volume | number | Output field: resp.inbound.1721930400000.volume |
resp.inbound.1721930400000.n_held | number | Output field: resp.inbound.1721930400000.n_held |
resp.inbound.1721930400000.n_junk | number | Output field: resp.inbound.1721930400000.n_junk |
resp.inbound.1721930400000.n_other_actions | number | Output field: resp.inbound.1721930400000.n_other_actions |
resp.inbound.1721930400000.n_last_period | number | Output field: resp.inbound.1721930400000.n_last_period |
Output Example
{"resp":{"inbound":{"1721887200000":{},"1721908800000":{},"1721930400000":{},"1721952000000":{},"1721973600000":{},"1721995200000":{},"1722016800000":{},"1722038400000":{},"1722060000000":{},"1722081600000":{},"1722103200000":{},"1722124800000":{},"1722146400000":{},"1722168000000":{},"1722189600000":{}},"outbound":{"1721887200000":{},"1721908800000":{},"1721930400000":{},"1721952000000":{},"1721973600000":{},"1721995200000":{},"1722016800000":{},"1722038400000":{},"1722060000000":{},"1722081600...
Get Data Loss
Retrieve Data Loss Prevention (DLP) statistics for users, sorted by total breach count in Darktrace.
Endpoint
- URL: /agemail/api/v1.0/dash/data_loss
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.days | number | Optional | Number of days to return data for. (Minimum 1, Maximum 30). |
parameters.limit | number | Optional | Number of items to return. (Minimum 1, Maximum 100). |
Input Example
{"parameters":{"days":7,"limit":5}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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';...
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 |
|---|---|---|---|
parameters.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. |
parameters.count | number | Optional | Max number of items to return. |
parameters.ddid | number | Optional | Identification number of a destination device modelled in the Darktrace system to restrict data to. |
parameters.deduplicate | boolean | Optional | Display only one equivalent connection per hour. |
parameters.destinationport | number | Optional | This filter can be used to filter the returned data by destination port. |
parameters.did | number | Optional | Identification number of a device modelled in the Darktrace system. |
parameters.externalhostname | string | Required | Specifies an hostname to return details for. |
parameters.eventtype | string | Optional | Specifies an hostname to return details for. |
parameters.from | string | Optional | Start time of data to return in YYYY-MM-DD HH:MM:SS format. |
parameters.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. |
parameters.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. |
parameters.msg | string | Optional | Specifies the value of the message field in notice events to return details for. Typically used to specify user credential strings. |
parameters.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. |
parameters.pbid | number | Optional | ID for a model breach. |
parameters.port | number | Optional | This filter can be used to filter the returned data by source or destination port. |
parameters.protocol | string | Optional | This filter can be used to filter the returned data by IP protocol. See /enums for the list of protocols. |
parameters.sourceport | number | Optional | This filter can be used to filter the returned data by source port. |
parameters.endtime | string | Optional | End time of data to return in millisecond format, relative to midnight January 1st 1970 UTC. |
parameters.starttime | string | Optional | Start time of data to return in millisecond format, relative to midnight January 1st 1970 UTC. |
parameters.to | string | Optional | End time of data to return in YYYY-MM-DD HH:MM:SS format. |
parameters.uid | string | Optional | Specifies a connection UID to return. |
Input Example
{"parameters":{"application_protocol":"SMB","count":50,"ddid":2,"deduplicate":false,"destinationport":443,"did":3,"externalhostname":"google.com","eventtype":"unusualconnection","from":"2014-12-01T01:00:00","fulldevicedetails":true,"intext":"internal","msg":"USER123","odid":1,"pbid":6,"port":443,"protocol":"TCP","sourceport":443,"endtime":"1704282955000","starttime":"1704196555000","to":"2014-12-01T01:00:00","uid":"CcdXo43n8B75cdYyI5"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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":...
Get Device Info
Retrieve detailed connectivity and activity data for a device in Darktrace using the unique device ID (did).
Endpoint
- URL: /deviceinfo
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.datatype | string | Optional | Parameters for the Get Device Info action |
parameters.did | number | Required | Identification number of a device modelled in the Darktrace system. |
parameters.externaldomain | string | Optional | Restrict external data to an particular domain name. |
parameters.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. |
parameters.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. |
parameters.showallgraphdata | boolean | Optional | Return an entry for all time intervals in the graph data, including zero counts. |
parameters.similardevices | number | Optional | Return data for the primary device and this number of similar devices. |
Input Example
{"parameters":{"datatype":"Return data for either connections, data size out or data size in.","did":1,"externaldomain":"Restrict external data to an particular domain name.","fulldevicedetails":true,"odid":2,"showallgraphdata":false,"similardevices":5}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
deviceInfo | array | Output field: deviceInfo |
deviceInfo.did | number | Unique identifier |
deviceInfo.similarityScore | number | Score value |
deviceInfo.domain | string | Output field: deviceInfo.domain |
deviceInfo.graphData | array | Response data |
deviceInfo.graphData.file_name | string | Response data |
deviceInfo.graphData.file | string | Response data |
deviceInfo.info | object | Output field: deviceInfo.info |
deviceInfo.info.totalUsed | number | Output field: deviceInfo.info.totalUsed |
deviceInfo.info.totalServed | number | Output field: deviceInfo.info.totalServed |
deviceInfo.info.totalDevicesAndPorts | number | Output field: deviceInfo.info.totalDevicesAndPorts |
deviceInfo.info.devicesAndPorts | array | Output field: deviceInfo.info.devicesAndPorts |
deviceInfo.info.devicesAndPorts.file_name | string | Name of the resource |
deviceInfo.info.devicesAndPorts.file | string | Output field: deviceInfo.info.devicesAndPorts.file |
deviceInfo.info.portsUsed | array | Output field: deviceInfo.info.portsUsed |
deviceInfo.info.portsUsed.file_name | string | Name of the resource |
deviceInfo.info.portsUsed.file | string | Output field: deviceInfo.info.portsUsed.file |
deviceInfo.info.portsServed | array | Output field: deviceInfo.info.portsServed |
deviceInfo.info.portsServed.file_name | string | Name of the resource |
deviceInfo.info.portsServed.file | string | Output field: deviceInfo.info.portsServed.file |
deviceInfo.info.devicesUsed | array | Output field: deviceInfo.info.devicesUsed |
deviceInfo.info.devicesUsed.file_name | string | Name of the resource |
deviceInfo.info.devicesUsed.file | string | Output field: deviceInfo.info.devicesUsed.file |
Output 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":...
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 |
|---|---|---|---|
parameters.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. |
parameters.ip | string | Optional | Return data for this IP address. |
parameters.iptime | string | Optional | Return the device which had the IP at a given time |
parameters.mac | string | Optional | Return the device with this MAC address. |
Input Example
{"parameters":{"seensince":"14days","ip":"8.8.8.8","iptime":"2019-01-01T12:00:00","mac":"11:22:33:44:55:66"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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"...
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 |
|---|---|---|---|
path_parameters.uuid | string | Required | UUID of the email. |
parameters.dtime | number | Optional | Approximate Timestamp of the email. Optional but will increase speed of the response. |
Input Example
{"path_parameters":{"uuid":"12345678-1234-1234-1234-123456789abc"},"parameters":{"dtime":123}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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';...
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 |
data_body.page | number | Required | The Page Number (starting at 0) to choose. |
data_body.itemsPerPage | number | Required | Number of items to be returned per page. Maximum is 50. |
data_body.timeFrom | number | Required | Unix timestamp (Seconds or Millisends) to start the search from. |
data_body.timeTo | number | Required | Unix timestamp (Seconds or Millisends) to search until. |
data_body.query | object | Required | Object containing the filters to apply. |
data_body.query.criteriaList | array | Required | Response data |
data_body.query.criteriaList.apiFilter | string | Required | ApiFilter to apply. See /resources/filters. |
data_body.query.criteriaList.value | string | Required | Value to compare against. Not required if the type is flag (flag is True or not present). |
data_body.query.criteriaList.operator | string | Required | Response data |
data_body.query.mode | string | Optional | Mode to apply the filters in - either 'and' or 'or'. |
Input Example
{"data_body":{"page":0,"itemsPerPage":20,"timeFrom":1677159576,"timeTo":1677245976,"query":{"criteriaList":[{"apiFilter":"Email.Antigena Email Anomaly","value":"50","operator":">"},{"apiFilter":"Recipient.Email","value":"[email protected]","operator":"="}],"mode":"and"}}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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';...
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 |
Output 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 's...
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 |
|---|---|---|---|
parameters.start_time | string | Required | Start of time range. |
parameters.end_time | string | Required | End of time range. |
parameters.include_ack | boolean | Required | Include acknowledged incidents in output. |
Input Example
{"parameters":{"start_time":"-1days","end_time":"now","include_ack":true}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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"...
Get Intelfeed
Retrieve the latest threat intelligence information from Darktrace Intelfeed.
Endpoint
- URL: /intelfeed
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.addentry | string | Optional | Parameters for the Get Intelfeed action |
parameters.add_list | array | Optional | Parameters for the Get Intelfeed action |
parameters.description | string | Optional | Parameters for the Get Intelfeed action |
parameters.expiry | string | Optional | Parameters for the Get Intelfeed action |
parameters.fulldetails | string | Optional | Parameters for the Get Intelfeed action |
parameters.hostname | string | Optional | Parameters for the Get Intelfeed action |
parameters.removeall | string | Optional | Parameters for the Get Intelfeed action |
parameters.remove_entry | string | Optional | Parameters for the Get Intelfeed action |
parameters.source | string | Optional | Parameters for the Get Intelfeed action |
parameters.sources | string | Optional | Parameters for the Get Intelfeed action |
Input Example
{"parameters":{"addentry":"www.badmalware.com","add_list":["www.badmalware.com,www.mymalware.com"],"description":"This is a description","expiry":"2020-12-31T12:00:00","fulldetails":"true","hostname":"true","removeall":"false","remove_entry":"www.badmalware.com","source":"GOOGLE","sources":"true"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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":"...
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 |
|---|---|---|---|
parameters.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. |
parameters.breachtimes | boolean | Optional | Return additional information for the model breach times for the device. |
parameters.ddid | number | Optional | Identification number of a destination device modelled in the Darktrace system to restrict data to. |
parameters.destinationport | number | Optional | This filter can be used to filter the returned data by destination port. |
parameters.did | number | Optional | Identification number of a device modelled in the Darktrace system. |
parameters.from | string | Optional | Start time of data to return in YYYY-MM-DD HH:MM:SS format. |
parameters.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. |
parameters.interval | number | Optional | Time interval size in seconds. The maximum value for any minute in interval is returned. |
parameters.metric | string | Optional | Name of a metric. See /metrics for the full list of current metrics. |
parameters.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. |
parameters.port | number | Optional | This filter can be used to filter the returned data by source or destination port. |
parameters.protocol | string | Optional | This filter can be used to filter the returned data by IP protocol. See /enums for the list of protocols. |
parameters.sourceport | number | Optional | This filter can be used to filter the returned data by source port. |
parameters.starttime | string | Optional | Start time of data to return in millisecond format, relative to midnight January 1st 1970 UTC |
parameters.endtime | string | Optional | Start time of data to return in millisecond format, relative to midnight January 1st 1970 UTC |
Input Example
{"parameters":{"application_protocol":"SMB","breachtimes":true,"ddid":2,"destinationport":443,"did":2,"from":"2014-12-01T01:00:00","fulldevicedetails":true,"interval":3600,"metric":"connections","odid":2,"port":443,"protocol":"TCP","sourceport":22,"starttime":"1704196555000","endtime":"1704282955000"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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"...
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 |
|---|---|---|---|
parameters.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. |
parameters.destinationport | number | Optional | This filter can be used to filter the returned data by destination port. |
parameters.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. |
parameters.did | number | Optional | Identification number of a device modelled in the Darktrace system. |
parameters.ip | string | Optional | Return data for this IP address. |
parameters.from | string | Optional | Start time of data to return in YYYY-MM-DD HH:MM:SS format. |
parameters.to | string | Optional | End time of data to return in YYYY-MM-DD HH:MM:SS format. |
parameters.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. |
parameters.metric | string | Optional | Name of a metric. See /metrics for the full list of current metrics. |
parameters.port | number | Optional | This filter can be used to filter the returned data by source or destination port. |
parameters.protocol | string | Optional | This filter can be used to filter the returned data by IP protocol. See /enums for the list of protocols. |
parameters.sourceport | number | Optional | This filter can be used to filter the returned data by source port. |
parameters.starttime | string | Optional | Start time of data to return in millisecond format, relative to midnight January 1st 1970 UTC. |
parameters.endtime | string | Optional | End time of data to return in millisecond format, relative to midnight January 1st 1970 UTC. |
Input Example
{"parameters":{"application_protocol":"SMB","destinationport":443,"intext":"internal","did":2,"ip":"8.8.8.8","from":"2023-12-01T01:00:00","to":"2023-12-01T01:00:00","fulldevicedetails":true,"metric":"connections","port":443,"protocol":"TCP","sourceport":22,"starttime":"1704196555000","endtime":"1704282955000"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
statistics | array | Output field: statistics |
statistics.Views | array | Output field: statistics.Views |
statistics.Views.View | string | Output field: statistics.Views.View |
statistics.Views.in | boolean | Output field: statistics.Views.in |
statistics.Views.out | boolean | Output field: statistics.Views.out |
statistics.Connection Status | array | Status value |
statistics.Connection Status.Connections | string | Status value |
statistics.Connection Status.in | boolean | Status value |
statistics.Connection Status.out | boolean | Status value |
statistics.applicationprotocols | array | Output field: statistics.applicationprotocols |
statistics.applicationprotocols.file_name | string | Name of the resource |
statistics.applicationprotocols.file | string | Output field: statistics.applicationprotocols.file |
subnets | array | Output field: subnets |
subnets.file_name | string | Name of the resource |
subnets.file | string | Output field: subnets.file |
devices | array | Output field: devices |
devices.file_name | string | Name of the resource |
devices.file | string | Output field: devices.file |
metric | object | Output field: metric |
metric.mlid | number | Unique identifier |
metric.name | string | Name of the resource |
metric.label | string | Output field: metric.label |
metric.units | string | Output field: metric.units |
Output 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"...
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 |
|---|---|---|---|
parameters.count | number | Optional | Parameters for the Get Similar Devices action |
parameters.did | number | Optional | Identification number of a device modelled in the Darktrace system. |
Input Example
{"parameters":{"count":20,"did":2}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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":"...
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 |
|---|---|---|---|
parameters.include_children | boolean | Optional | Return information for child instances, probes and sensors. |
Input Example
{"parameters":{"include_children":false}}
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 |
Output 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"...
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 |
|---|---|---|---|
parameters.seensince | string | Optional | Parameters for the Get Subnets action |
Input Example
{"parameters":{"seensince":"7days"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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":...
Get Tags
Retrieve 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 |
Output 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"...
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 |
|---|---|---|---|
parameters.days | number | Optional | Number of days to return data for. (Minimum 1, Maximum 30). |
parameters.limit | number | Optional | Number of items to return. (Minimum 1, Maximum 100). |
Input Example
{"parameters":{"days":30,"limit":100}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
object | Output field: [email protected] | |
[email protected]_emails | number | Output field: [email protected]_emails |
[email protected]_emails | number | Output field: [email protected]_emails |
[email protected]_last_period | number | Output field: [email protected]_last_period |
[email protected]_last_week | number | Output field: [email protected]_last_week |
number | Output field: [email protected] | |
[email protected]_links | number | Output field: [email protected]_links |
[email protected]_attachments | number | Output field: [email protected]_attachments |
Output 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'...
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 |
Output 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';...
List Endpoint Details
Retrieve detailed information on endpoints, including location, IP address, and device connection data for external IPs and hostnames.
Endpoint
- URL: /endpointdetails
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.additionalinfo | boolean | Optional | Return additional information about the endpoint. |
parameters.devices | boolean | Optional | Return a list of devices which have recently connected to the endpoint. |
parameters.score | boolean | Optional | Return rarity data for this endpoint. |
parameters.hostname | string | Optional | Return data for this hostname. |
parameters.ip | string | Optional | Return data for this ip address. |
parameters.responsedata | string | Optional | When given the name of a top-level field or object, restricts the returned JSON to only that field or object. |
Input Example
{"parameters":{"additionalinfo":true,"devices":true,"score":true,"hostname":"www.google.com","ip":"8.8.8.8","responsedata":"devices"}}
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 |
devices.did | number | Unique identifier |
devices.macaddress | string | Output field: devices.macaddress |
devices.vendor | string | Output field: devices.vendor |
devices.ip | string | Output field: devices.ip |
devices.ips | array | Output field: devices.ips |
devices.ips.ip | string | Output field: devices.ips.ip |
devices.ips.timems | number | Output field: devices.ips.timems |
devices.ips.time | string | Time value |
Output 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';...
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 |
Output 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...
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 |
|---|---|---|---|
parameters.deviceattop | boolean | Optional | Return the device JSON object as a value of the top level object rather than within each matched component. |
parameters.did | number | Optional | Identification number of a device modelled in the Darktrace system. |
parameters.starttime | string | Optional | Start time of data to return in millisecond format, relative to midnight January 1st 1970 UTC |
parameters.endtime | string | Optional | End time of data to return in millisecond format, relative to midnight January 1st 1970 UTC. |
parameters.from | string | Optional | Start time of data to return in YYYY-MM-DD HH:MM:SS format. |
parameters.to | string | Optional | End time of data to return in YYYY-MM-DD HH:MM:SS format |
parameters.historicmodelonly | boolean | Optional | Return the JSON for the historic version of the model details only, rather than both the historic and current definition. |
parameters.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. |
parameters.includeacknowledged | boolean | Optional | Include acknowledged breaches in the data |
parameters.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. |
parameters.pbid | number | Optional | ID for a model breach |
parameters.pid | number | Optional | Only return model breaches for the specified model |
parameters.uuid | string | Optional | Specifies a connection UID to return. |
Input Example
{"parameters":{"deviceattop":true,"did":1,"starttime":"1704196555000","endtime":"1704282955000","from":"2023-12-12T00:00:00","to":"2024-01-03T00:00:00","historicmodelonly":false,"includebreachurl":true,"includeacknowledged":false,"minimal":false,"pbid":1,"pid":1,"uuid":""}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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"...
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 |
Output 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","servertim...
List Similar Devices
Retrieve 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 |
|---|---|---|---|
parameters.did | number | Optional | Parameters for the List Similar Devices action |
parameters.count | number | Optional | Specifies the maximum number of items to return. |
parameters.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. |
parameters.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. |
parameters.responsedata | string | Optional | When given the name of a top-level field or object, restricts the returned JSON to only that field or object. |
Input Example
{"parameters":{"did":123,"count":10,"fulldevicedetails":true,"token":"example","responsedata":"devices"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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';...
Post Action
Execute a specified action on an email in Darktrace using its UUID, subject to user permissions. Requires path parameters and data body.
Endpoint
- URL: /agemail/api/v1.0/emails/{{uuid}}/action
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.uuid | string | Required | UUID of the email. |
parameters.dtime | number | Optional | Approximate Timestamp of the email. Optional but will increase speed of the response. |
data_body | object | Required | Response data |
data_body.action | string | Required | Action to take on the email. Either 'hold', 'release' or if requested 'approve_release' / 'reject_release'. |
data_body.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. |
data_body.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. |
Input Example
{"data_body":{"action":"hold","recipients":["[email protected]"],"returnEmail":false}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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';...
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 |
Output Example
{"tag_id":"aa","name":"Automatic Response","status":"info","description":"An email that has been automatically produced as a result of a received email. T...","category":"Content"}
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 |
Output 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'...
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 |
|---|---|---|---|
path_parameters.uuid | string | Required | UUID of the email. |
Input Example
{"path_parameters":{"uuid":"12345678-1234-1234-1234-123456789abc"}}
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 |
rcpts.rcpt_to | string | Output field: rcpts.rcpt_to |
rcpts.rcpt_status | string | Status value |
rcpts.tags | array | Output field: rcpts.tags |
rcpts.is_read | boolean | Output field: rcpts.is_read |
rcpts.rcpt_actions_taken | array | Output field: rcpts.rcpt_actions_taken |
rcpts.action_status | boolean | Status value |
rcpts.is_group_email | boolean | Output field: rcpts.is_group_email |
rcpts.summary | array | Output field: rcpts.summary |
Output 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';...
Unacknowledge Event
Revert the acknowledgment status of an AI Analyst event in Darktrace using the specified UUID path parameter.
Endpoint
- URL: /modelbreaches/{{pbid}}/unacknowledge
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.pbid | number | Required | Parameters for the Unacknowledge Event action |
Input Example
{"path_parameters":{"pbid":40974}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
response | string | Output field: response |
Output 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":"...
Unlock a Link
Reverse a previous lock to enable 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 |
|---|---|---|---|
parameters.url | string | Optional | The link to unlock. |
Input Example
{"parameters":{"url":"https://example.com/api/resource"}}
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 |
Output 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';...
Update Antigena RESPOND State
Modify or activate Darktrace RESPOND actions using the provided 'codeid'.
Endpoint
- URL: /antigena
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
codeid | number | Optional | 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 |
Input Example
{"json_body":{"codeid":123,"activate":true,"duration":100,"reason":"string","clear":true}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output 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';...
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 | 523 |
content-security-policy | HTTP response header: content-security-policy | default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob data: URIs data: |
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 |
cross-origin-resource-policy | HTTP response header: cross-origin-resource-policy | same-origin |
date | The date and time at which the message was originated | Mon, 05 Feb 2024 10:25:21 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.053 |
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 |
x-robots-tag | HTTP response header: x-robots-tag | noindex, noindex |
x-webkit-csp | HTTP response header: x-webkit-csp | default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob data: URIs data: |
x-xss-protection | HTTP response header: x-xss-protection | 1; mode=block |