Dragos

Dragos is an industrial cybersecurity platform that provides threat detection and response capabilities for critical infrastructure.

Dragos is a leading platform for industrial control systems (ICS) and operational technology (OT) cybersecurity. It provides comprehensive incident response and asset management capabilities. By integrating Dragos with Swimlane Turbine, users can automate incident response, manage assets efficiently, and enhance security operations. This integration allows for seamless interaction with Dragos' robust features, enabling users to create and manage cases, zones, and vulnerability detection rules, as well as retrieve detailed reports and notifications.

Prerequisites

Before you can use the Dragos connector for Turbine, you'll need access to the Dragos API. This requires the following:

HTTP Basic authentication using the following parameters:

URL: The endpoint URL for accessing Dragos API.

API Key ID: Unique identifier for API key authentication.

API Secret Key: Secret key associated with the API Key ID for secure access.

Asset Setup

This connector requires following assets:

API Key ID

API Secret Key ID

Steps to generate the API Key ID and Secret ID in the Dragos is as below:

Click + Add New API Key

The Generate New API Key box expands.

In the Name field, add the name of the API Key being added, for example My External App .

Click GENERATE KEY, and a message box appears.

NOTE: This message box contains the updated name, the ID, and the Secret. Use the Copy Icon to copy the Secret.

WARNING: This is the only time the secret is displayed. Once this message box is closed, there is no way to retrieve the secret. If the secret his lost, then the API Key must be deleted and a new API Key assigned.

Click OK and the API Key is configured.

Capabilities

This connector provides the following capabilities:

Create Note

Create Zone

Delete Note

Delete Vulnerability Detection Rule

Delete Zone

Fetch Single Case

Get a Page of Notifications

Get Asset History Events

Get Assets

Get Communications Summary

Get Notification Details

Get Page Vulnerabilities

Get Page Vulnerability Detection Rules

Get Page Vulnerability Detections

Get Report Data ... and so on

Notes

NotificationRead permission allow reading of notifications(not including system notifications).

NotificationSystemType permission allow reading of system notifications.

To get Detector ID in action Get Results from Detector ID , run action Get Notification Details.

Additional Documentation

Dragos Connector Documentation

Dragos API Documentation

Configurations

Dragos API Authentication

Authenticates using API Key as Username and API Secret as Password.

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
username	API Key ID	string	Required
password	API Secret Key	string	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Create Note

Add a note to an open case in Dragos where the user is an admin, author, assignee, or watcher. Requires 'case_id' and 'message'.

Endpoint

URL: /cases/cases/{{case_id}}/notes

Method: POST

Input

Argument Name	Type	Required	Description
path_parameters.case_id	number	Required	Parameters for the Create Note action
message	string	Optional	Response message

Input Example

{"json_body":{"message":"note created"},"path_parameters":{"case_id":1}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
caseId	number	Unique identifier
generated	boolean	Output field: generated
author	string	Output field: author
message	string	Response message
referenceType	object	Type of the resource
referenceId	object	Unique identifier
createdAt	string	Output field: createdAt
updatedAt	string	Output field: updatedAt

Output Example

{"status_code":200,"response_headers":{"Alt-Svc":"h3=\":443\"; ma=2592000","Cache-Control":"max-age=0, private, must-revalidate","Content-Type":"application/json; charset=utf-8","Etag":"W/\"b1a427116345f8a069b8a1640cada731\"","Server":"Caddy","X-Content-Type-Options":"nosniff","X-Frame-Options":"SAMEORIGIN","X-Identity-Id":"61bf8f1c-2679-4e84-8c25-3ffa85b15099","X-Privileges":"analytic:read,asset:map,asset:read,asset:write,auth:identity:read,baseline:read,...","X-Request-Id":"je1jvv-1vh13pp7fa21...

Create Zone

Initiate a new zone creation in Dragos, triggering asset re-zoning with the specified configuration. Requires JSON body input for the 'create' parameter.

Endpoint

URL: /assets/api/v4/createZone

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Optional	HTTP headers for the request
headers.X-Username	string	Optional	Username of requester. Not needed if accessing via Gateway Service.
headers.X-Privileges	string	Optional	Comma-separated privilege IDs of requester. Not needed if accessing via Gateway Service.
create	object	Optional	Parameter for Create Zone
create.name	string	Required	Name of the resource
create.description	string	Optional	Parameter for Create Zone
create.colorHex	string	Optional	Parameter for Create Zone
create.criteria	object	Required	Parameter for Create Zone
create.criteria.idOrOldIdIn	array	Optional	Filters assets by IDs (or old IDs from pre-merge).
create.criteria.attributesMatches	object	Optional	Filters assets by having attribute(s) with matching values.
create.criteria.attributesMatches.property1	object	Optional	Parameter for Create Zone
create.criteria.attributesMatches.property1.type	string	Optional	Type of the resource
create.criteria.attributesMatches.property2	object	Optional	Parameter for Create Zone
create.criteria.attributesMatches.property2.type	string	Optional	Type of the resource
create.criteria.addressSelector	object	Optional	Filters assets by address criteria.
create.criteria.addressSelector.idIn	array	Optional	Unique identifier
create.criteria.addressSelector.typeIn	array	Optional	Type of the resource
create.criteria.addressSelector.networkIdIn	array	Optional	Unique identifier
create.criteria.addressSelector.collectorSelector	object	Optional	Parameter for Create Zone
create.criteria.addressSelector.collectorSelector.customerId	string	Optional	Unique identifier
create.criteria.addressSelector.collectorSelector.midpointId	string	Optional	Unique identifier
create.criteria.addressSelector.collectorSelector.collectorId	string	Optional	Unique identifier
create.criteria.addressSelector.collectorSelector.anyOf	array	Optional	Parameter for Create Zone
create.criteria.addressSelector.collectorSelector.allOf	array	Optional	Parameter for Create Zone
create.criteria.addressSelector.collectorSelector.not	object	Optional	Parameter for Create Zone

Input Example

{"headers":{"X-Username":"X-Username","X-Privileges":"analytic:read,asset:map,asset:read"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
name	string	Name of the resource
description	string	Output field: description
colorHex	string	Output field: colorHex
criteria	object	Output field: criteria
criteria.idOrOldIdIn	array	Unique identifier
criteria.attributesMatches	object	Output field: criteria.attributesMatches
criteria.attributesMatches.property1	object	Output field: criteria.attributesMatches.property1
criteria.attributesMatches.property1.type	string	Type of the resource
criteria.attributesMatches.property2	object	Output field: criteria.attributesMatches.property2
criteria.attributesMatches.property2.type	string	Type of the resource
criteria.addressSelector	object	Output field: criteria.addressSelector
criteria.addressSelector.idIn	array	Unique identifier
criteria.addressSelector.typeIn	array	Type of the resource
criteria.addressSelector.networkIdIn	array	Unique identifier
criteria.addressSelector.collectorSelector	object	Output field: criteria.addressSelector.collectorSelector
criteria.addressSelector.collectorSelector.customerId	string	Unique identifier
criteria.addressSelector.collectorSelector.midpointId	string	Unique identifier
criteria.addressSelector.collectorSelector.collectorId	string	Unique identifier
criteria.addressSelector.collectorSelector.anyOf	array	Output field: criteria.addressSelector.collectorSelector.anyOf
criteria.addressSelector.collectorSelector.allOf	array	Output field: criteria.addressSelector.collectorSelector.allOf
criteria.addressSelector.collectorSelector.not	object	Output field: criteria.addressSelector.collectorSelector.not
criteria.addressSelector.valueMatches	object	Value for the parameter

Output Example

{"status_code":200,"response_headers":{},"reason":"Success","json_body":{"id":0,"name":"string","description":"string","colorHex":"#000000","criteria":{"idOrOldIdIn":[],"attributesMatches":{},"addressSelector":{},"createdAtBefore":"2019-08-24T14:15:22Z","createdAtAfter":"2019-08-24T14:15:22Z","lastSeenAtBefore":"2019-08-24T14:15:22Z","lastSeenAtAfter":"2019-08-24T14:15:22Z","textSearch":"string","isDeleted":true,"anyOf":[],"allOf":[],"not":{}},"coordinates":{"x":0,"y":0,"width":0,"height":0},"gr...

Delete Note

Remove a specific note from an open case in Dragos using the correct case and note IDs with appropriate user permissions.

Endpoint

URL: /cases/cases/{{case_id}}/notes/{{note_id}}

Method: DELETE

Input

Argument Name	Type	Required	Description
path_parameters.case_id	number	Required	Parameters for the Delete Note action
path_parameters.note_id	number	Required	Parameters for the Delete Note action

Input Example

{"path_parameters":{"case_id":1,"note_id":1}}

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":{},"reason":"OK","json_body":{}}

Delete Vulnerability Detection Rule

Remove a specified vulnerability detection rule from Dragos, requiring 'VulnerabilityDetectionRuleDelete' privilege.

Endpoint

URL: /vulnerabilities/api/v1/vulnerability/detection/rules/delete

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Optional	HTTP headers for the request
headers.X-Username	string	Optional	Username of requester. Not needed if accessing via Gateway Service.
headers.X-Privileges	string	Optional	Comma-separated privilege IDs of requester. Not needed if accessing via Gateway Service.
uuid	string	Optional	Unique identifier

Input Example

{"json_body":{"uuid":"string"},"headers":{"X-Username":"X-Username","X-Privileges":"analytic:read,asset:map,asset:read"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":202,"response_headers":{},"reason":"Accepted","json_body":{}}

Delete Zone

Remove a specified zone from Dragos and re-zone associated assets. Requires the 'id' of the zone.

Endpoint

URL: /assets/api/v4/deleteZone

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Optional	HTTP headers for the request
headers.X-Username	string	Optional	Username of requester. Not needed if accessing via Gateway Service.
headers.X-Privileges	string	Optional	Comma-separated privilege IDs of requester. Not needed if accessing via Gateway Service.
id	number	Optional	Unique identifier

Input Example

{"json_body":{"id":0},"headers":{"X-Username":"X-Username","X-Privileges":"analytic:read,asset:map,asset:read"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
name	string	Name of the resource
description	string	Output field: description
colorHex	string	Output field: colorHex
criteria	object	Output field: criteria
criteria.idOrOldIdIn	array	Unique identifier
criteria.attributesMatches	object	Output field: criteria.attributesMatches
criteria.attributesMatches.property1	object	Output field: criteria.attributesMatches.property1
criteria.attributesMatches.property1.type	string	Type of the resource
criteria.attributesMatches.property2	object	Output field: criteria.attributesMatches.property2
criteria.attributesMatches.property2.type	string	Type of the resource
criteria.addressSelector	object	Output field: criteria.addressSelector
criteria.addressSelector.idIn	array	Unique identifier
criteria.addressSelector.typeIn	array	Type of the resource
criteria.addressSelector.networkIdIn	array	Unique identifier
criteria.addressSelector.collectorSelector	object	Output field: criteria.addressSelector.collectorSelector
criteria.addressSelector.collectorSelector.customerId	string	Unique identifier
criteria.addressSelector.collectorSelector.midpointId	string	Unique identifier
criteria.addressSelector.collectorSelector.collectorId	string	Unique identifier
criteria.addressSelector.collectorSelector.anyOf	array	Output field: criteria.addressSelector.collectorSelector.anyOf
criteria.addressSelector.collectorSelector.allOf	array	Output field: criteria.addressSelector.collectorSelector.allOf
criteria.addressSelector.collectorSelector.not	object	Output field: criteria.addressSelector.collectorSelector.not
criteria.addressSelector.valueMatches	object	Value for the parameter

Output Example

Fetches a Single Case

Retrieve detailed information for a specific case in Dragos using the provided case ID, including notes, evidences, and tasks.

Endpoint

URL: /cases/cases/{{id}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.id	number	Required	Case ID

Input Example

{"path_parameters":{"id":1}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
name	string	Name of the resource
hypothesis	object	Output field: hypothesis
justification	object	Output field: justification
visibility	string	Output field: visibility
status	string	Status value
priority	number	Output field: priority
incident	boolean	Unique identifier
creator	string	Output field: creator
assignee	object	Output field: assignee
createdAt	string	Output field: createdAt
updatedAt	string	Output field: updatedAt
notificationIds	array	Unique identifier
notificationIds.file_name	string	Unique identifier
notificationIds.file	string	Unique identifier
watchers	string	Output field: watchers
evidences	array	Unique identifier
evidences.id	number	Unique identifier
evidences.caseId	number	Unique identifier
evidences.author	string	Unique identifier
evidences.dataType	string	Response data
evidences.data	string	Response data
notes	array	Output field: notes

Output Example

{"status_code":200,"response_headers":{"Alt-Svc":"h3=\":443\"; ma=2592000","Cache-Control":"max-age=0, private, must-revalidate","Content-Type":"application/json; charset=utf-8","Etag":"W/\"0b4e0bef532ca790db2dd6a24abaae68\"","Server":"Caddy","X-Content-Type-Options":"nosniff","X-Frame-Options":"SAMEORIGIN","X-Identity-Id":"61bf8f1c-2679-4e84-8c25-3ffa85b15099","X-Privileges":"analytic:read,asset:map,asset:read,asset:write,auth:identity:read,baseline:read,...","X-Request-Id":"o+-+fpuvbw1m4735can...

Get a page of notifications

Retrieve a specific page of notifications from Dragos, filtered according to user-defined criteria.

Endpoint

URL: /notifications/api/v2/notification

Method: GET

Input

Argument Name	Type	Required	Description
parameters.pageNumber	number	Optional	Parameters for the Get a page of notifications action
parameters.pageSize	number	Optional	Parameters for the Get a page of notifications action
parameters.sorts	string	Optional	The format is comma-separated sets of a sort field, colon, and 'a' (for ascending) or 'd' (for descending).
parameters.sortField	string	Optional	Parameters for the Get a page of notifications action
parameters.sortDescending	boolean	Optional	Parameters for the Get a page of notifications action
parameters.limitTotalCount	number	Optional	Parameters for the Get a page of notifications action
parameters.filter	string	Optional	A filter string in FIQL format. See relevant information on FIQL Operators and Notification Selectors in doc.
parameters.resolveChildrenDepth	boolean	Optional	Number of steps deep to recursively resolve child notifications.

Input Example

{"parameters":{"pageNumber":1,"pageSize":12,"sorts":"createdAt:d","sortField":"id","sortDescending":false,"limitTotalCount":50,"filter":"id=ge=5","resolveChildrenDepth":false}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
headers	object	HTTP headers for the request
headers.alt-svc	string	HTTP headers for the request
headers.content-type	string	HTTP headers for the request
headers.server	string	HTTP headers for the request
headers.x-identity-id	string	HTTP headers for the request
headers.x-privileges	string	HTTP headers for the request
headers.x-request-id	string	HTTP headers for the request
headers.x-username	string	HTTP headers for the request
headers.date	string	HTTP headers for the request
headers.connection	string	HTTP headers for the request
headers.transfer-encoding	string	HTTP headers for the request
status_reason	string	Status value
body	object	Request body data
body.pageNumber	number	Request body data
body.pageSize	number	Request body data
body.sorts	array	Request body data
body.sorts.field	string	Request body data
body.sorts.descending	boolean	Request body data
body.totalCount	number	Request body data
body.totalPages	number	Request body data
body.content	array	Request body data
body.content.id	number	Request body data
body.content.assets	array	Request body data
body.content.assets.file_name	string	Request body data

Output Example

{"status_code":200,"headers":{"alt-svc":"h3=\":443\"; ma=2592000","content-type":"application/json; charset=UTF-8","server":"Caddy","x-identity-id":"61bf8f1c-2679-4e84-8c25-3ffa85b15099","x-privileges":"analytic:read,asset:map,asset:read,asset:write,auth:identity:read,baseline:read,...","x-request-id":"5k3wyzt=3sw1346h++pzgvf22arbqyqf996=1fmovm156=/3i0w12gnui072xfbj","x-username":"tp7864","date":"Wed, 28 Feb 2024 14:26:20 GMT","connection":"close","transfer-encoding":"chunked"},"status_reason":"...

Get Asset History Events

Retrieve historical events for a specific asset in Dragos, requiring 'AssetRead' privilege.

Endpoint

URL: /assets/api/v4/getAssetHistoryEvents

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Optional	HTTP headers for the request
headers.X-Username	string	Optional	Username of requester. Not needed if accessing via Gateway Service.
headers.X-Privileges	string	Optional	Comma-separated privilege IDs of requester. Not needed if accessing via Gateway Service.
selector	object	Optional	Parameter for Get Asset History Events
selector.assetIdIn	array	Optional	Unique identifier
selector.timestampIsOrAfter	string	Optional	Parameter for Get Asset History Events
selector.timestampIsOrBefore	string	Optional	Parameter for Get Asset History Events
selector.typeIn	array	Optional	Type of the resource
selector.addressSelector	object	Optional	Parameter for Get Asset History Events
selector.addressSelector.idIn	array	Optional	Unique identifier
selector.addressSelector.typeIn	array	Optional	Type of the resource
selector.addressSelector.networkIdIn	array	Optional	Unique identifier
selector.addressSelector.collectorSelector	object	Optional	Parameter for Get Asset History Events
selector.addressSelector.collectorSelector.customerId	string	Optional	Unique identifier
selector.addressSelector.collectorSelector.midpointId	string	Optional	Unique identifier
selector.addressSelector.collectorSelector.collectorId	string	Optional	Unique identifier
selector.addressSelector.collectorSelector.anyOf	array	Optional	Parameter for Get Asset History Events
selector.addressSelector.collectorSelector.allOf	array	Optional	Parameter for Get Asset History Events
selector.addressSelector.collectorSelector.not	object	Optional	Parameter for Get Asset History Events
selector.addressSelector.valueMatches	object	Optional	Value for the parameter
selector.addressSelector.valueMatches.type	string	Optional	Type of the resource
selector.addressSelector.anyOf	array	Optional	Parameter for Get Asset History Events
selector.addressSelector.allOf	array	Optional	Parameter for Get Asset History Events
selector.addressSelector.not	object	Optional	Parameter for Get Asset History Events
selector.attributeNameMatches	object	Optional	Name of the resource

Input Example

{"json_body":{"selector":{"assetIdIn":[0],"timestampIsOrAfter":"2019-08-24T14:15:22Z","timestampIsOrBefore":"2019-08-24T14:15:22Z","typeIn":["string"],"addressSelector":{"idIn":[0],"typeIn":["MAC"],"networkIdIn":["string"],"collectorSelector":{"customerId":"string","midpointId":"string","collectorId":"string","anyOf":[{}],"allOf":[{}],"not":{}},"valueMatches":{"type":"string"},"anyOf":[{}],"allOf":[{}],"not":{}},"attributeNameMatches":{"type":"string"},"userIdMatches":{"type":"string"},"reasonMatches":{"type":"string"},"allOf":[{}],"anyOf":[{}],"not":{}},"pagination":{"pageNumber":0,"pageSize":0,"limitTotalCount":0,"sorts":[{"field":"type","descending":true}]}},"headers":{"X-Username":"X-Username","X-Privileges":"analytic:read,asset:map,asset:read"}}

Output

Parameter	Type	Description
pageNumber	number	Output field: pageNumber
pageSize	number	Output field: pageSize
sorts	array	Output field: sorts
sorts.file_name	string	Name of the resource
sorts.file	string	Output field: sorts.file
totalCount	number	Count value
totalPages	number	Output field: totalPages
content	array	Response content
content.assetId	number	Unique identifier
content.timestamp	string	Response content
content.userId	string	Unique identifier
content.reason	string	Response reason phrase
content.resolutionContext	object	Response content
content.resolutionContext.macsAndIPs	array	Response content
content.resolutionContext.macsAndIPs.addressId	number	Unique identifier
content.resolutionContext.hostsAndDomains	array	Response content
content.resolutionContext.hostsAndDomains.file_name	string	Name of the resource
content.resolutionContext.hostsAndDomains.file	string	Response content
content.resolutionContext.at	string	Response content
content.type	string	Type of the resource
content.addressId	number	Unique identifier
content.addressCoordinates	object	Response content
content.addressCoordinates.type	string	Type of the resource
content.addressCoordinates.networkId	string	Unique identifier
content.addressCoordinates.value	string	Value for the parameter

Output Example

{"pageNumber":1,"pageSize":10,"sorts":[],"totalCount":284289,"totalPages":28429,"content":[{"assetId":1,"timestamp":"2023-03-02T15:27:24.457Z","userId":"sitestore-dataflow-service","reason":"Communications source address","resolutionContext":{},"type":"CREATED"},{"assetId":1,"timestamp":"2023-03-02T15:27:24.588Z","userId":"sitestore-dataflow-service","reason":"Communications source address","addressId":9,"addressCoordinates":{},"at":"2023-03-02T15:07:05.695Z","type":"ADDRESS_ASSOCIATED"}]}

Get Assets

Retrieve a list of assets, addresses, and time ranges from Dragos with 'AssetRead' privilege.

Endpoint

URL: /assets/api/v4/getAssets

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Optional	HTTP headers for the request
headers.X-Username	string	Optional	Username of requester. Not needed if accessing via Gateway Service.
headers.X-Privileges	string	Optional	Comma-separated privilege IDs of requester. Not needed if accessing via Gateway Service.
selector	object	Optional	Parameter for Get Assets
selector.idOrOldIdIn	array	Optional	Unique identifier
selector.attributesMatches	object	Optional	Parameter for Get Assets
selector.attributesMatches.property1	object	Optional	Parameter for Get Assets
selector.attributesMatches.property1.type	string	Optional	Type of the resource
selector.attributesMatches.property2	object	Optional	Parameter for Get Assets
selector.attributesMatches.property2.type	string	Optional	Type of the resource
selector.addressSelector	object	Optional	Parameter for Get Assets
selector.addressSelector.idIn	array	Optional	Unique identifier
selector.addressSelector.typeIn	array	Optional	Type of the resource
selector.addressSelector.networkIdIn	array	Optional	Unique identifier
selector.addressSelector.collectorSelector	object	Optional	Parameter for Get Assets
selector.addressSelector.collectorSelector.customerId	string	Optional	Unique identifier
selector.addressSelector.collectorSelector.midpointId	string	Optional	Unique identifier
selector.addressSelector.collectorSelector.collectorId	string	Optional	Unique identifier
selector.addressSelector.collectorSelector.anyOf	array	Optional	Parameter for Get Assets
selector.addressSelector.collectorSelector.allOf	array	Optional	Parameter for Get Assets
selector.addressSelector.collectorSelector.not	object	Optional	Parameter for Get Assets
selector.addressSelector.valueMatches	object	Optional	Value for the parameter
selector.addressSelector.valueMatches.type	string	Optional	Type of the resource
selector.addressSelector.anyOf	array	Optional	Parameter for Get Assets
selector.addressSelector.allOf	array	Optional	Parameter for Get Assets

Input Example

{"headers":{"X-Username":"X-Username","X-Privileges":"analytic:read,asset:map,asset:read"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
pageNumber	number	Output field: pageNumber
pageSize	number	Output field: pageSize
sortDescending	boolean	Output field: sortDescending
totalCount	number	Count value
totalPages	number	Output field: totalPages
totalCountExceededLimit	boolean	Output field: totalCountExceededLimit
sorts	array	Output field: sorts
sorts.field	string	Output field: sorts.field
sorts.descending	boolean	Output field: sorts.descending
content	array	Response content
content.id	number	Unique identifier
content.oldIds	array	Unique identifier
content.attributes	object	Response content
content.createdAt	string	Response content
content.lastSeenAt	string	Response content
content.addresses	array	Response content
content.addresses.type	string	Type of the resource
content.addresses.networkId	string	Unique identifier
content.addresses.value	string	Value for the parameter
content.addresses.id	number	Unique identifier
content.addresses.flags	array	Response content
content.addresses.collectors	array	Response content
content.addresses.collectors.customerId	string	Unique identifier

Output Example

{"status_code":200,"response_headers":{},"reason":"Success","json_body":{"pageNumber":0,"pageSize":0,"sortDescending":true,"totalCount":0,"totalPages":0,"totalCountExceededLimit":true,"sorts":[{}],"content":[{}]}}

Get Communications Summary

Retrieve a summary of communications data from Dragos, with optional filters for time-based analysis.

Endpoint

URL: /maps/api/v1/getCommunicationsSummary

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Optional	HTTP headers for the request
headers.X-Username	string	Optional	Username of requester. Not needed if accessing via Gateway Service.
headers.X-Privileges	string	Optional	Comma-separated privilege IDs of requester. Not needed if accessing via Gateway Service.
from	string	Optional	Parameter for Get Communications Summary
to	string	Optional	Parameter for Get Communications Summary
views	array	Optional	Parameter for Get Communications Summary

Input Example

{"json_body":{"from":"2019-08-24T14:15:22Z","to":"2019-08-24T14:15:22Z","views":["COLLECTOR"]},"headers":{"X-Username":"X-Username","X-Privileges":"analytic:read,asset:map,asset:read"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
from	string	Output field: from
to	string	Output field: to
byCollector	array	Output field: byCollector
byCollector.collector	object	Output field: byCollector.collector
byCollector.collector.customerId	string	Unique identifier
byCollector.collector.midpointId	string	Unique identifier
byCollector.collector.collectorId	string	Unique identifier
byCollector.networkId	string	Unique identifier
byCollector.protocolId	string	Unique identifier
byCollector.zoneId	number	Unique identifier
byCollector.addressesCommunicatingWithNetworkIds	array	Unique identifier
byCollector.addressesCommunicatingWithZoneIds	array	Unique identifier
byCollector.protocolIds	array	Unique identifier
byCollector.communicationsBytes	number	Output field: byCollector.communicationsBytes
byCollector.communicationsPackets	number	Output field: byCollector.communicationsPackets
byNetworkId	array	Unique identifier
byNetworkId.collector	object	Unique identifier
byNetworkId.collector.customerId	string	Unique identifier
byNetworkId.collector.midpointId	string	Unique identifier
byNetworkId.collector.collectorId	string	Unique identifier
byNetworkId.networkId	string	Unique identifier
byNetworkId.protocolId	string	Unique identifier
byNetworkId.zoneId	number	Unique identifier

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"from":"2019-08-24T14:15:22Z","to":"2019-08-24T14:15:22Z","byCollector":[{}],"byNetworkId":[{}],"byProtocolId":[{}],"byZoneId":[{}],"total":{"collector":{},"networkId":"string","protocolId":"string","zoneId":0,"addressesCommunicatingWithNetworkIds":[],"addressesCommunicatingWithZoneIds":[],"protocolIds":[],"communicationsBytes":0,"communicationsPackets":0}}}

Get Notification Details

Retrieve detailed information for a specific Dragos notification using the unique identifier provided in path parameters.

Endpoint

URL: /notifications/api/v2/notification/{{id}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.id	number	Required	ID of the notification.
parameters.resolveChildrenDepth	number	Optional	Number of steps deep to recursively resolve child notifications.
parameters.includeConversations	boolean	Optional	Whether conversations should be included with the notification, default is true.

Input Example

{"parameters":{"resolveChildrenDepth":1,"includeConversations":true},"path_parameters":{"id":1}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
assets	array	Output field: assets
assets.file_name	string	Name of the resource
assets.file	string	Output field: assets.file
createdAt	string	Output field: createdAt
matchedRuleIds	array	Unique identifier
matchedRuleIds.file_name	string	Unique identifier
matchedRuleIds.file	string	Unique identifier
reviewed	boolean	Output field: reviewed
retained	boolean	Output field: retained
type	string	Type of the resource
detectionQuads	array	Output field: detectionQuads
count	number	Count value
source	string	Output field: source
summary	string	Output field: summary
content	string	Response content
detectorId	string	Unique identifier
occurredAt	string	Output field: occurredAt
severity	number	Output field: severity
analyticEventId	string	Unique identifier
sourceIndex	string	Output field: sourceIndex
sourceIdField	string	Unique identifier
sourceIds	array	Unique identifier

Output Example

{"status_code":200,"response_headers":{"Alt-Svc":"h3=\":443\"; ma=2592000","Content-Type":"application/json; charset=UTF-8","Server":"Caddy","X-Identity-Id":"61bf8f1c-2679-4e84-8c25-3ffa85b15099","X-Privileges":"analytic:read,asset:map,asset:read,asset:write,auth:identity:read,baseline:read,..."},"reason":"OK","json_body":{"id":1,"assets":[],"createdAt":"2023-03-02T15:27:24Z","matchedRuleIds":[],"reviewed":false,"retained":false,"type":"Network Analytic","detectionQuads":["Threat Behavior"],"cou...

Get Page of Vulnerabilities

Retrieve a paginated list of vulnerabilities from Dragos, requiring the 'VulnerabilityRead' privilege.

Endpoint

URL: /vulnerabilities/api/v1/vulnerability

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Optional	HTTP headers for the request
headers.X-Username	string	Optional	Username of requester. Not needed if accessing via Gateway Service.
headers.X-Privileges	string	Optional	Comma-separated privilege IDs of requester. Not needed if accessing via Gateway Service.
selector	object	Optional	Parameter for Get Page of Vulnerabilities
selector.idIn	array	Optional	Filters by ID in list
selector.valueMatches	object	Optional	Filters by matching value.
selector.valueMatches.type	string	Required	Type of the resource
selector.valueMatches.field	string	Required	Value for the parameter
selector.valueMatches.exact	string	Required	Value for the parameter
selector.anyOf	array	Optional	List of other selectors to combine as an OR; only allowed if no other fields specified
selector.allOf	array	Optional	List of other selectors to combine as an AND; only allowed if no other fields specified
pagination	object	Optional	Parameter for Get Page of Vulnerabilities
pagination.pageNumber	number	Optional	Parameter for Get Page of Vulnerabilities
pagination.pageSize	number	Optional	Parameter for Get Page of Vulnerabilities
pagination.limitTotalCount	number	Optional	an optional limit of total count to avoid counting large data sets
pagination.sorts	array	Optional	Parameter for Get Page of Vulnerabilities

Input Example

{"json_body":{"selector":{"idIn":["string"],"valueMatches":{"type":"string"},"anyOf":[{}],"allOf":[{}]},"pagination":{"pageNumber":0,"pageSize":0,"limitTotalCount":0,"sorts":["string"]}},"headers":{"X-Username":"X-Username","X-Privileges":"analytic:read,asset:map,asset:read"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
pageNumber	number	Output field: pageNumber
pageSize	number	Output field: pageSize
totalCount	number	Count value
totalPages	number	Output field: totalPages
content	array	Response content
content.@timestamp	string	Response content
content.labels	string	Response content
content.message	string	Response content
content.tags	string	Response content
content.host	object	Response content
content.observer	object	Response content
content.related	object	Response content
content.threat	object	Response content
content.vulnerability	object	Response content

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"pageNumber":0,"pageSize":0,"totalCount":0,"totalPages":0,"content":[{}]}}

Get Page of Vulnerability Detection Rules

Retrieve a specific page of vulnerability detection rules from Dragos, requiring 'VulnerabilityDetectionRuleRead' privilege.

Endpoint

URL: /vulnerabilities/api/v1/vulnerability/detection/rules

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Optional	HTTP headers for the request
headers.X-Username	string	Optional	Username of requester. Not needed if accessing via Gateway Service.
headers.X-Privileges	string	Optional	Comma-separated privilege IDs of requester. Not needed if accessing via Gateway Service.
selector	object	Optional	Parameter for Get Page of Vulnerability Detection Rules
selector.idIn	array	Optional	Filters by ID in list
selector.valueMatches	object	Optional	Filters by matching value.
selector.valueMatches.type	string	Optional	Type of the resource
selector.anyOf	array	Optional	List of other selectors to combine as an OR; only allowed if no other fields specified
selector.allOf	array	Optional	List of other selectors to combine as an AND; only allowed if no other fields specified
pagination	object	Optional	Parameter for Get Page of Vulnerability Detection Rules
pagination.pageNumber	number	Optional	Parameter for Get Page of Vulnerability Detection Rules
pagination.pageSize	number	Optional	Parameter for Get Page of Vulnerability Detection Rules
pagination.limitTotalCount	number	Optional	an optional limit of total count to avoid counting large data sets
pagination.sorts	array	Optional	Parameter for Get Page of Vulnerability Detection Rules

Input Example

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
pageNumber	number	Output field: pageNumber
pageSize	number	Output field: pageSize
totalCount	number	Count value
totalPages	number	Output field: totalPages
content	array	Response content
content.selector	object	Response content
content.selector.idIn	array	Unique identifier
content.selector.valueMatches	object	Filters by matching value.
content.selector.valueMatches.type	string	Type of the resource
content.selector.valueMatches.field	string	Value for the parameter
content.selector.valueMatches.exact	string	Value for the parameter
content.selector.anyOf	array	Response content
content.selector.allOf	array	Response content
content.actions	array	Response content
content.actions.type	string	Type of the resource
content.name	string	Name of the resource
content.description	string	Response content
content.category	string	Response content
content.license	string	Response content
content.reference	string	Response content
content.expiration	string	Response content
content.uuid	string	Unique identifier
content.author	string	Response content

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"pageNumber":0,"pageSize":0,"totalCount":0,"totalPages":0,"content":[{}]}}

Get Page Vulnerability Detections

Retrieve a page of vulnerability detection data from Dragos, requiring 'VulnerabilityDetectionRead' privilege.

Endpoint

URL: /vulnerabilities/api/v1/vulnerability/detection

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Optional	HTTP headers for the request
headers.X-Username	string	Optional	Username of requester. Not needed if accessing via Gateway Service.
headers.X-Privileges	string	Optional	Comma-separated privilege IDs of requester. Not needed if accessing via Gateway Service.
selector	object	Optional	Parameter for Get Page Vulnerability Detections
selector.idIn	array	Optional	Filters by ID in list
selector.valueMatches	object	Optional	Filters by matching value.
selector.valueMatches.type	string	Required	Type of the resource
selector.valueMatches.field	string	Required	Value for the parameter
selector.valueMatches.exact	string	Required	Value for the parameter
selector.anyOf	array	Optional	List of other selectors to combine as an OR; only allowed if no other fields specified
selector.allOf	array	Optional	List of other selectors to combine as an AND; only allowed if no other fields specified
pagination	object	Optional	Parameter for Get Page Vulnerability Detections
pagination.pageNumber	number	Optional	Parameter for Get Page Vulnerability Detections
pagination.pageSize	number	Optional	Parameter for Get Page Vulnerability Detections
pagination.limitTotalCount	number	Optional	an optional limit of total count to avoid counting large data sets
pagination.sorts	array	Optional	Parameter for Get Page Vulnerability Detections

Input Example

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
pageNumber	number	Output field: pageNumber
pageSize	number	Output field: pageSize
totalCount	number	Count value
totalPages	number	Output field: totalPages
content	array	Response content
content.@timestamp	string	Response content
content.labels	string	Response content
content.message	string	Response content
content.tags	string	Response content
content.observer	object	Response content
content.vulnerability	object	Response content
content.hardware	object	Response content
content.package	object	Response content
content.os	object	Response content
content.host	object	Response content
content.event	object	Response content
content.related	object	Response content

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"pageNumber":0,"pageSize":0,"totalCount":0,"totalPages":0,"content":[{}]}}

Get Report

Retrieve a specific Dragos report using the 'reportId' from path parameters. Requires 'REPORT_READ' privilege and necessary headers.

Endpoint

URL: /reports/api/v2/report/{{reportId}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.reportId	number	Required	The report's id
headers	object	Required	HTTP headers for the request
headers.X-Username	string	Required	Requester's identity
headers.X-Privileges	string	Required	Requester's privileges

Input Example

{"path_parameters":{"reportId":1},"headers":{"X-Username":"tp7864","X-Privileges":"analytic:read,asset:map,asset:read,asset:write,auth:identity:read,baseline:read"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
name	string	Name of the resource
description	string	Output field: description
state	string	Output field: state
failureReason	string	Response reason phrase
createdTime	string	Time value
generationStartedTime	string	Time value
generationCompletedTime	string	Time value
generationProgress	number	Output field: generationProgress
parameters.type	string	Parameters for the Get Report action
parameters.formats	array	Parameters for the Get Report action
files	object	Output field: files

Output Example

{"status_code":200,"response_headers":{},"reason":"Success","json_body":{"id":0,"name":"string","description":"string","state":"READY_TO_GENERATE","failureReason":"string","createdTime":"2019-08-24T14:15:22Z","generationStartedTime":"2019-08-24T14:15:22Z","generationCompletedTime":"2019-08-24T14:15:22Z","generationProgress":0,"parameters":{"type":"IOC","formats":[]},"files":{}}}

Get Report Data

Retrieve specified report data from Dragos using 'reportId' and 'format', ensuring 'REPORT_READ' privilege and header parameters are set.

Endpoint

URL: /reports/api/v2/report/{{reportId}}/{{format}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.reportId	string	Required	The report's id
path_parameters.format	string	Required	Parameters for the Get Report Data action
headers	object	Required	HTTP headers for the request
headers.X-Username	string	Required	Requester's identity
headers.X-Privileges	string	Required	Requester's privileges

Input Example

{"path_parameters":{"reportId":"1","format":"CSV"},"headers":{"X-Username":"X-Username","X-Privileges":"analytic:read,asset:map,asset:read"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
name	string	Name of the resource
description	string	Output field: description
state	string	Output field: state
failureReason	string	Response reason phrase
createdTime	string	Time value
generationStartedTime	string	Time value
generationCompletedTime	string	Time value
generationProgress	number	Output field: generationProgress
parameters.type	string	Parameters for the Get Report Data action
parameters.formats	array	Parameters for the Get Report Data action
files	object	Output field: files
files.property1	number	Output field: files.property1
files.property2	number	Output field: files.property2

Output Example

Get Results from Detector ID

Retrieve detection results from Dragos using a specified detector ID as a path parameter.

Endpoint

URL: /analytics/analyticMetadata/{{detector_id}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.detector_id	string	Required	Parameters for the Get Results from Detector ID action

Input Example

{"path_parameters":{"detector_id":"7205ebab-ff5c-499b-9f87-f648e7b2f438"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
display_name	string	Name of the resource
engine	string	Output field: engine
description	string	Output field: description
silent	boolean	Output field: silent
type	string	Type of the resource
id	string	Unique identifier
metadata	object	Response data
metadata.detection_quad	array	Response data
metadata.kill_chain	array	Response data
metadata.attack_tactic	array	Response data
metadata.attack_technique	array	Response data
metadata.date_source	array	Response data
metadata.Purdue layer	array	Response data
metadata.intelligence_report	array	Response data
metadata.activity_group	array	Response data
metadata.tool	array	Response data
metadata.Asset Type	array	Response data
metadata.Vendor	array	Response data
metadata.Protocols	array	Response data
metadata.notifications	array	Response data
metadata.notifications.summary	string	Response data
metadata.notifications.message	string	Response data

Output Example

{"status_code":200,"response_headers":{"Alt-Svc":"h3=\":443\"; ma=2592000","Content-Type":"application/json; charset=UTF-8","Server":"Caddy","X-Identity-Id":"61bf8f1c-2679-4e84-8c25-3ffa85b15099","X-Privileges":"analytic:read,asset:map,asset:read,asset:write,auth:identity:read,baseline:read,..."},"reason":"OK","json_body":{"display_name":"ARP Scan","engine":"bro","description":"ARP Scanning can be use to discover live hosts.","silent":false,"type":"detection","id":"1bf8f1c-2679-4e84-8c25-3ffa85b...

Get Snapshot

Retrieve metadata and data for a specified snapshot in Dragos, requiring 'AssetSnapshotRead' privilege. Input the snapshot ID as JSON body.

Endpoint

URL: /maps/api/v1/getSnapshot

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Optional	HTTP headers for the request
headers.X-Username	string	Optional	Username of requester. Not needed if accessing via Gateway Service.
headers.X-Privileges	string	Optional	Comma-separated privilege IDs of requester. Not needed if accessing via Gateway Service.
id	number	Optional	ID of the snapshot to get
view	object	Optional	Parameter for Get Snapshot
view.type	string	Optional	Type of the resource
fetchFreshAssetAttributes	boolean	Optional	whether to pull fresh asset attributes from AIS

Input Example

{"json_body":{"id":0,"view":{"type":"base"},"fetchFreshAssetAttributes":true},"headers":{"X-Username":"X-Username","X-Privileges":"analytic:read,asset:map,asset:read"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
metadata	object	Response data
metadata.id	number	Response data
metadata.generationFilter	object	Response data
metadata.generationFilter.assetSelector	object	Response data
metadata.generationFilter.assetSelector.id	object	Response data
metadata.generationFilter.assetSelector.createdAt	object	Response data
metadata.generationFilter.assetSelector.lastSeenAt	object	Response data
metadata.generationFilter.assetSelector.attributes	object	Response data
metadata.generationFilter.assetSelector.attributes.property1	object	Response data
metadata.generationFilter.assetSelector.attributes.property2	object	Response data
metadata.generationFilter.assetSelector.address	object	Response data
metadata.generationFilter.assetSelector.address.id	object	Response data
metadata.generationFilter.assetSelector.address.type	object	Response data
metadata.generationFilter.assetSelector.address.networkId	object	Response data
metadata.generationFilter.assetSelector.address.value	object	Response data
metadata.generationFilter.assetSelector.address.collector	object	Response data
metadata.generationFilter.assetSelector.address.anyOf	array	Response data
metadata.generationFilter.assetSelector.address.allOf	array	Response data
metadata.generationFilter.assetSelector.anyOf	array	Response data
metadata.generationFilter.assetSelector.allOf	array	Response data
metadata.generationFilter.communicationsSelector	object	Response data
metadata.generationFilter.communicationsSelector.addressId	object	Response data
metadata.generationFilter.communicationsSelector.originatorPorts	object	Response data

Output Example

{"metadata":{"id":123,"generationFilter":{"assetSelector":{},"communicationsSelector":{},"limitAssetCount":123},"bins":[{}],"fromMin":"string","toMax":"string","composite":true,"ephemeral":true,"retention":{"deleteAfter":"string"},"createdAt":"string","state":"string","stateChangedAt":"string","metrics":{"generationMilliseconds":123,"generationStatistics":{},"dataBytes":123,"total":{},"byZoneId":[],"byNetworkId":[],"byCollector":[],"byProtocolId":[]}},"view":{"type":"string"}}

Get Snapshot Metadata

Retrieve metadata for a specified snapshot in Dragos using the 'id'. Requires 'AssetSnapshotRead' privilege.

Endpoint

URL: /maps/api/v1/getSnapshotMetadata

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Optional	HTTP headers for the request
headers.X-Username	string	Optional	Username of requester. Not needed if accessing via Gateway Service.
headers.X-Privileges	string	Optional	Comma-separated privilege IDs of requester. Not needed if accessing via Gateway Service.
id	number	Optional	ID of the snapshot to get

Input Example

{"json_body":{"id":0},"headers":{"X-Username":"X-Username","X-Privileges":"analytic:read,asset:map,asset:read"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
generationFilter	object	Output field: generationFilter
generationFilter.assetSelector	object	Output field: generationFilter.assetSelector
generationFilter.assetSelector.id	object	Unique identifier
generationFilter.assetSelector.createdAt	object	Output field: generationFilter.assetSelector.createdAt
generationFilter.assetSelector.lastSeenAt	object	Output field: generationFilter.assetSelector.lastSeenAt
generationFilter.assetSelector.attributes	object	Output field: generationFilter.assetSelector.attributes
generationFilter.assetSelector.address	object	Output field: generationFilter.assetSelector.address
generationFilter.assetSelector.anyOf	array	Output field: generationFilter.assetSelector.anyOf
generationFilter.assetSelector.allOf	array	Output field: generationFilter.assetSelector.allOf
generationFilter.communicationsSelector	object	Output field: generationFilter.communicationsSelector
generationFilter.communicationsSelector.addressId	object	Unique identifier
generationFilter.communicationsSelector.originatorPorts	object	Output field: generationFilter.communicationsSelector.originatorPorts
generationFilter.communicationsSelector.responderPorts	object	Output field: generationFilter.communicationsSelector.responderPorts
generationFilter.communicationsSelector.protocolId	object	Unique identifier
generationFilter.communicationsSelector.ipProtocolId	object	Unique identifier
generationFilter.communicationsSelector.bytes	object	Output field: generationFilter.communicationsSelector.bytes
generationFilter.communicationsSelector.packets	object	Output field: generationFilter.communicationsSelector.packets
generationFilter.communicationsSelector.anyOf	array	Output field: generationFilter.communicationsSelector.anyOf
generationFilter.communicationsSelector.allOf	array	Output field: generationFilter.communicationsSelector.allOf
generationFilter.limitAssetCount	number	Count value
bins	array	Output field: bins
bins.id	number	Unique identifier

Output Example

{"id":123,"generationFilter":{"assetSelector":{"id":{},"createdAt":{},"lastSeenAt":{},"attributes":{},"address":{},"anyOf":[],"allOf":[]},"communicationsSelector":{"addressId":{},"originatorPorts":{},"responderPorts":{},"protocolId":{},"ipProtocolId":{},"bytes":{},"packets":{},"anyOf":[],"allOf":[]},"limitAssetCount":123},"bins":[{"id":123,"from":"string","to":"string"}],"fromMin":"string","toMax":"string","composite":true,"ephemeral":true,"retention":{"deleteAfter":"string"},"createdAt":"string...

Get Snapshot Metadata Page

Retrieve a page of snapshot metadata from Dragos, requiring 'AssetSnapshotRead' privilege for access.

Endpoint

URL: /maps/api/v1/getSnapshotMetadataPage

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Optional	HTTP headers for the request
headers.X-Username	string	Optional	Username of requester. Not needed if accessing via Gateway Service.
headers.X-Privileges	string	Optional	Comma-separated privilege IDs of requester. Not needed if accessing via Gateway Service.
selector	object	Optional	Parameter for Get Snapshot Metadata Page
pagination	object	Optional	Parameter for Get Snapshot Metadata Page
pagination.pageNumber	number	Optional	Parameter for Get Snapshot Metadata Page
pagination.pageSize	number	Optional	Parameter for Get Snapshot Metadata Page
pagination.sortDescending	boolean	Optional	Parameter for Get Snapshot Metadata Page
pagination.sortField	string	Optional	Parameter for Get Snapshot Metadata Page

Input Example

{"json_body":{"selector":{},"pagination":{"pageNumber":0,"pageSize":0,"sortDescending":true,"sortField":"id"}},"headers":{"X-Username":"X-Username","X-Privileges":"analytic:read,asset:map,asset:read"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
pageNumber	number	Output field: pageNumber
pageSize	number	Output field: pageSize
sortDescending	boolean	Output field: sortDescending
totalCount	number	Count value
totalPages	number	Output field: totalPages
sortField	string	Output field: sortField
content	array	Response content
content.id	number	Unique identifier
content.generationFilter	object	Response content
content.generationFilter.assetSelector	object	Response content
content.generationFilter.assetSelector.id	object	Unique identifier
content.generationFilter.assetSelector.createdAt	object	Response content
content.generationFilter.assetSelector.lastSeenAt	object	Response content
content.generationFilter.assetSelector.attributes	object	Response content
content.generationFilter.assetSelector.address	object	Response content
content.generationFilter.assetSelector.anyOf	array	Response content
content.generationFilter.assetSelector.allOf	array	Response content
content.generationFilter.communicationsSelector	object	Response content
content.generationFilter.limitAssetCount	number	Response content
content.bins	array	Response content
content.bins.id	number	Unique identifier
content.bins.from	string	Response content
content.bins.to	string	Response content

Output Example

{"pageNumber":123,"pageSize":123,"sortDescending":true,"totalCount":123,"totalPages":123,"sortField":"string","content":[{"id":123,"generationFilter":{},"bins":[],"fromMin":"string","toMax":"string","composite":true,"ephemeral":true,"retention":{},"createdAt":"string","state":"string","stateChangedAt":"string","metrics":{}}]}

Get Zones

Retrieve a comprehensive list of zones from Dragos, detailing attributes and status for each zone.

Endpoint

URL: /assets/api/v4/getZones

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Optional	HTTP headers for the request
headers.X-Username	string	Optional	Username of requester. Not needed if accessing via Gateway Service.
headers.X-Privileges	string	Optional	Comma-separated privilege IDs of requester. Not needed if accessing via Gateway Service.

Input Example

{"json_body":{},"headers":{"X-Username":"X-Username","X-Privileges":"analytic:read,asset:map,asset:read"}}

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":{},"reason":"Success","json_body":[{"id":0,"name":"string","description":"string","colorHex":"#000000","criteria":{},"coordinates":{},"groupLabel":"string","metadata":{}}]}

List Evidences From Case

Retrieve evidence items from a specific case in Dragos using the case ID, accessible by permitted roles.

Endpoint

URL: /cases/cases/{{case_id}}/evidences

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.case_id	number	Required	Case ID

Input Example

{"path_parameters":{"case_id":1}}

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":{"Alt-Svc":"h3=\":443\"; ma=2592000","Cache-Control":"max-age=0, private, must-revalidate","Content-Type":"application/json; charset=utf-8","Etag":"W/\"49d28362723562024cd4c788aab9b05d\"","Server":"Caddy","X-Content-Type-Options":"nosniff","X-Frame-Options":"SAMEORIGIN","X-Identity-Id":"61bf8f1c-2679-4e84-8c25-3ffa85b15099","X-Privileges":"analytic:read,asset:map,asset:read,asset:write,auth:identity:read,baseline:read,...","X-Request-Id":"8niq8z7/thwtw3nv82q...

List notes from a Case

Retrieve all notes associated with a given case ID in Dragos for users with specific privileges.

Endpoint

URL: /cases/cases/{{case_id}}/notes

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.case_id	number	Required	Parameters for the List notes from a Case action

Input Example

{"path_parameters":{"case_id":1}}

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":{"Alt-Svc":"h3=\":443\"; ma=2592000","Cache-Control":"max-age=0, private, must-revalidate","Content-Type":"application/json; charset=utf-8","Etag":"W/\"465c975a3297a25173d3c2b284f638c0\"","Server":"Caddy","X-Content-Type-Options":"nosniff","X-Frame-Options":"SAMEORIGIN","X-Identity-Id":"61bf8f1c-2679-4e84-8c25-3ffa85b15099","X-Privileges":"analytic:read,asset:map,asset:read,asset:write,auth:identity:read,baseline:read,...","X-Request-Id":"5vyck6pw0g-g7+6tfrp...

List Report

Retrieve a paginated list of reports from Dragos, requiring 'REPORT_READ' privilege and necessary headers for access.

Endpoint

URL: /reports/api/v2/report

Method: GET

Input

Argument Name	Type	Required	Description
parameters.pageNumber	number	Optional	Parameters for the List Report action
parameters.pageSize	number	Optional	Parameters for the List Report action
parameters.sortDescending	boolean	Optional	Parameters for the List Report action
parameters.sortField	string	Optional	Parameters for the List Report action
parameters.includeId	array	Optional	Parameters for the List Report action
parameters.excludeId	array	Optional	Parameters for the List Report action
parameters.includeType	array	Optional	Parameters for the List Report action
parameters.excludeType	array	Optional	Parameters for the List Report action
parameters.includeState	array	Optional	Parameters for the List Report action
parameters.excludeState	array	Optional	Parameters for the List Report action
parameters.createdTimeAtOrAfter	string	Optional	Parameters for the List Report action
parameters.createdTimeAtOrBefore	string	Optional	Parameters for the List Report action
parameters.generationStartedTimeAtOrAfter	string	Optional	Parameters for the List Report action
parameters.generationStartedTimeAtOrBefore	string	Optional	Parameters for the List Report action
parameters.generationCompletedTimeAtOrAfter	string	Optional	Parameters for the List Report action
parameters.generationCompletedTimeAtOrBefore	string	Optional	Parameters for the List Report action
headers	object	Required	HTTP headers for the request
headers.X-Username	string	Required	Requester's identity
headers.X-Privileges	string	Required	Requester's privileges

Input Example

{"parameters":{"pageNumber":1,"pageSize":10,"sortDescending":true,"sortField":"id","includeId":[1,2,3],"excludeId":[1,2,3],"includeType":["IOC","AssetInventory"],"excludeType":["IOC","AssetInventory"],"includeState":["READY_TO_GENERATE"],"excludeState":["GENERATING"],"createdTimeAtOrAfter":"2023-06-29T01:46:30Z","createdTimeAtOrBefore":"2023-06-29T01:46:30Z","generationStartedTimeAtOrAfter":"2023-06-29T01:46:30Z","generationStartedTimeAtOrBefore":"2023-06-29T01:46:30Z","generationCompletedTimeAtOrAfter":"2023-06-29T01:46:30Z","generationCompletedTimeAtOrBefore":"2023-06-29T01:46:30Z"},"headers":{"X-Username":"X-Username","X-Privileges":"analytic:read,asset:map,asset:read"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
pageNumber	number	Output field: pageNumber
pageSize	number	Output field: pageSize
sorts	array	Output field: sorts
sorts.descending	boolean	Output field: sorts.descending
sorts.field	string	Output field: sorts.field
totalCount	number	Count value
totalPages	number	Output field: totalPages
content	array	Response content
content.id	number	Unique identifier
content.name	string	Name of the resource
content.description	string	Response content
content.state	string	Response content
content.failureReason	string	Response reason phrase
content.createdTime	string	Response content
content.generationStartedTime	string	Response content
content.generationCompletedTime	string	Response content
content.generationProgress	number	Response content
content.parameters.type	string	Parameters for the List Report action
content.parameters.formats	array	Parameters for the List Report action
content.files	object	Response content
content.files.property1	number	Response content
content.files.property2	number	Response content

Output Example

{"status_code":200,"response_headers":{},"reason":"Success","json_body":{"pageNumber":1,"pageSize":1,"sorts":[{}],"totalCount":0,"totalPages":0,"content":[{}]}}

Update Case

Update specific attributes of a Dragos case for admins, assignees, or creators using the 'id' path parameter.

Endpoint

URL: /cases/cases/{{id}}

Method: PATCH

Input

Argument Name	Type	Required	Description
path_parameters.id	number	Required	Case ID
name	string	Optional	Name
hypothesis	string	Optional	Hypothesis for case
justification	string	Optional	Justification
priority	number	Optional	Priority level (0 is the lowest)
notificationIds	array	Optional	Notification Ids are comma separated string OR array of integers

Input Example

{"json_body":{"name":"Integrity Case","hypothesis":"Hypothesis for case","justification":"justification","priority":0,"notificationIds":[0,1,2]},"path_parameters":{"id":1}}

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":{},"reason":"OK","json_body":{}}

Update Note

Update a note for an open case in Dragos using message content, along with note and case identifiers.

Endpoint

URL: /cases/cases/{{case_id}}/notes/{{id}}

Method: PATCH

Input

Argument Name	Type	Required	Description
path_parameters.case_id	number	Required	Parameters for the Update Note action
path_parameters.id	number	Required	Note ID
message	string	Optional	Message

Input Example

{"json_body":{"message":"Cyber Security"},"path_parameters":{"case_id":1,"id":1}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
headers	object	HTTP headers for the request
headers.alt-svc	string	HTTP headers for the request
headers.cache-control	string	HTTP headers for the request
headers.content-type	string	HTTP headers for the request
headers.etag	string	HTTP headers for the request
headers.server	string	HTTP headers for the request
headers.x-content-type-options	string	HTTP headers for the request
headers.x-frame-options	string	HTTP headers for the request
headers.x-identity-id	string	HTTP headers for the request
headers.x-privileges	string	HTTP headers for the request
headers.x-request-id	string	HTTP headers for the request
headers.x-runtime	string	HTTP headers for the request
headers.x-username	string	HTTP headers for the request
headers.x-xss-protection	string	HTTP headers for the request
headers.date	string	HTTP headers for the request
headers.connection	string	HTTP headers for the request
headers.transfer-encoding	string	HTTP headers for the request
status_reason	string	Status value
body	object	Request body data
body.id	number	Request body data
body.caseId	number	Request body data
body.generated	boolean	Request body data
body.author	string	Request body data
body.message	string	Request body data

Output Example

{"status_code":200,"headers":{"alt-svc":"h3=\":443\"; ma=2592000","cache-control":"max-age=0, private, must-revalidate","content-type":"application/json; charset=utf-8","etag":"W/\"aaba14bd2f6d36cda98410747ea0255f\"","server":"Caddy","x-content-type-options":"nosniff","x-frame-options":"SAMEORIGIN","x-identity-id":"61bf8f1c-2679-4e84-8c25-3ffa85b15099","x-privileges":"analytic:read,asset:map,asset:read,asset:write,auth:identity:read,baseline:read,...","x-request-id":"p+8czg0kzgj9cd=nx9-xi/c//5g9...

Update Vulnerability Detection Rule

Update an existing vulnerability detection rule in Dragos using a UUID. Requires 'VulnerabilityDetectionRuleUpdate' privilege.

Endpoint

URL: /vulnerabilities/api/v1/vulnerability/detection/rules/update

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Optional	HTTP headers for the request
headers.X-Username	string	Optional	Username of requester. Not needed if accessing via Gateway Service.
headers.X-Privileges	string	Optional	Comma-separated privilege IDs of requester. Not needed if accessing via Gateway Service.
selector	object	Optional	Parameter for Update Vulnerability Detection Rule
selector.idIn	array	Optional	Unique identifier
selector.valueMatches	object	Optional	Value for the parameter
selector.valueMatches.type	string	Required	Type of the resource
selector.valueMatches.field	string	Required	Value for the parameter
selector.anyOf	array	Optional	List of other selectors to combine as an OR; only allowed if no other fields specified.
selector.allOf	array	Optional	List of other selectors to combine as an AND; only allowed if no other fields specified.
actions	array	Optional	Parameter for Update Vulnerability Detection Rule
actions.type	string	Required	Type of the resource
actions.risk	number	Optional	Parameter for Update Vulnerability Detection Rule
name	string	Optional	Name of the resource
description	string	Optional	Parameter for Update Vulnerability Detection Rule
category	string	Optional	Parameter for Update Vulnerability Detection Rule
license	string	Optional	Parameter for Update Vulnerability Detection Rule
reference	string	Optional	Parameter for Update Vulnerability Detection Rule
expiration	string	Optional	Parameter for Update Vulnerability Detection Rule
uuid	string	Optional	Unique identifier

Input Example

{"json_body":{"selector":{"idIn":["string"],"valueMatches":{"type":"exact","field":"string"},"anyOf":[{}],"allOf":[{}]},"actions":[{"type":"updateRisk","risk":30}],"name":"string","description":"string","category":"string","license":"string","reference":"string","expiration":"2019-08-24","uuid":"string"},"headers":{"X-Username":"","X-Privileges":""}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
selector	object	Output field: selector
selector.idIn	array	Unique identifier
selector.valueMatches	object	Value for the parameter
selector.valueMatches.type	string	Type of the resource
selector.anyOf	array	Output field: selector.anyOf
selector.allOf	array	Output field: selector.allOf
actions	array	Output field: actions
actions.type	string	Type of the resource
name	string	Name of the resource
description	string	Output field: description
category	string	Output field: category
license	string	Output field: license
reference	string	Output field: reference
expiration	string	Output field: expiration
uuid	string	Unique identifier
author	string	Output field: author
lastModifiedBy	string	Output field: lastModifiedBy
lastModifiedAt	string	Output field: lastModifiedAt
createdAt	string	Output field: createdAt
version	number	Output field: version

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"selector":{"idIn":[],"valueMatches":{},"anyOf":[],"allOf":[]},"actions":[{}],"name":"string","description":"string","category":"string","license":"string","reference":"string","expiration":"2019-08-24","uuid":"string","author":"string","lastModifiedBy":"string","lastModifiedAt":"2019-08-24T14:15:22Z","createdAt":"2019-08-24T14:15:22Z","version":0}}

Update Zone

Update a zone's attributes in Dragos, including name, description, color, and criteria, triggering asset re-zoning. Requires JSON body with ID and update details.

Endpoint

URL: /assets/api/v4/updateZone

Method: POST

Input

Argument Name	Type	Required	Description
headers	object	Optional	HTTP headers for the request
headers.X-Username	string	Optional	HTTP headers for the request
headers.X-Privileges	string	Optional	HTTP headers for the request
id	number	Optional	Unique identifier
update	object	Optional	Date value
update.name	string	Optional	Name of the resource
update.description	string	Required	Parameter for Update Zone
update.colorHex	string	Optional	Parameter for Update Zone
update.criteria	object	Optional	Parameter for Update Zone
update.criteria.idOrOldIdIn	array	Optional	Unique identifier
update.criteria.attributesMatches	object	Optional	Parameter for Update Zone
update.criteria.attributesMatches.property1	object	Optional	Parameter for Update Zone
update.criteria.attributesMatches.property1.type	string	Optional	Type of the resource
update.criteria.attributesMatches.property2	object	Optional	Parameter for Update Zone
update.criteria.attributesMatches.property2.type	string	Optional	Type of the resource
update.criteria.addressSelector	object	Optional	Parameter for Update Zone
update.criteria.addressSelector.idIn	array	Optional	Unique identifier
update.criteria.addressSelector.typeIn	array	Optional	Type of the resource
update.criteria.addressSelector.networkIdIn	array	Optional	Unique identifier
update.criteria.addressSelector.collectorSelector	object	Optional	Parameter for Update Zone
update.criteria.addressSelector.collectorSelector.customerId	string	Optional	Unique identifier
update.criteria.addressSelector.collectorSelector.midpointId	string	Optional	Unique identifier
update.criteria.addressSelector.collectorSelector.collectorId	string	Optional	Unique identifier
update.criteria.addressSelector.collectorSelector.anyOf	array	Optional	Parameter for Update Zone
update.criteria.addressSelector.collectorSelector.allOf	array	Optional	Parameter for Update Zone

Input Example

{"json_body":{"id":0,"update":{"name":"string","description":"string","colorHex":"string","criteria":{"idOrOldIdIn":[0],"attributesMatches":{"property1":{"type":"string"},"property2":{"type":"string"}},"addressSelector":{"idIn":[0],"typeIn":["MAC"],"networkIdIn":["string"],"collectorSelector":{"customerId":"string","midpointId":"string","collectorId":"string","anyOf":[{}],"allOf":[{}],"not":{}},"valueMatches":{"type":"string"},"anyOf":[{}],"allOf":[{}],"not":{},"associationTimeRangeOverlaps":{"from":"2019-08-24T14:15:22Z","to":"2019-08-24T14:15:22Z"}},"createdAtBefore":"2019-08-24T14:15:22Z","createdAtAfter":"2019-08-24T14:15:22Z","lastSeenAtBefore":"2019-08-24T14:15:22Z","lastSeenAtAfter":"2019-08-24T14:15:22Z","textSearch":"string","isDeleted":true,"anyOf":[{}],"allOf":[{}],"not":{}},"coordinates":{"x":0,"y":0,"width":0,"height":0},"groupLabel":"string"}},"headers":{"X-Username":"X-Username","X-Privileges":"analytic:read,asset:map,asset:read"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
name	string	Name of the resource
description	string	Output field: description
colorHex	string	Output field: colorHex
criteria	object	Output field: criteria
criteria.idOrOldIdIn	array	Unique identifier
criteria.attributesMatches	object	Output field: criteria.attributesMatches
criteria.attributesMatches.property1	object	Output field: criteria.attributesMatches.property1
criteria.attributesMatches.property1.type	string	Type of the resource
criteria.attributesMatches.property2	object	Output field: criteria.attributesMatches.property2
criteria.attributesMatches.property2.type	string	Type of the resource
criteria.addressSelector	object	Output field: criteria.addressSelector
criteria.addressSelector.idIn	array	Unique identifier
criteria.addressSelector.typeIn	array	Type of the resource
criteria.addressSelector.networkIdIn	array	Unique identifier
criteria.addressSelector.collectorSelector	object	Output field: criteria.addressSelector.collectorSelector
criteria.addressSelector.collectorSelector.customerId	string	Unique identifier
criteria.addressSelector.collectorSelector.midpointId	string	Unique identifier
criteria.addressSelector.collectorSelector.collectorId	string	Unique identifier
criteria.addressSelector.collectorSelector.anyOf	array	Output field: criteria.addressSelector.collectorSelector.anyOf
criteria.addressSelector.collectorSelector.allOf	array	Output field: criteria.addressSelector.collectorSelector.allOf
criteria.addressSelector.collectorSelector.not	object	Output field: criteria.addressSelector.collectorSelector.not
criteria.addressSelector.valueMatches	object	Value for the parameter

Output Example

Response Headers

Header	Description	Example
Alt-Svc	HTTP response header: Alt-Svc	h3=":443"; ma=2592000
Cache-Control	Directives for caching mechanisms	max-age=0, private, must-revalidate
Content-Type	The media type of the resource	application/json; charset=utf-8
Date	The date and time at which the message was originated	Wed, 28 Feb 2024 05:50:25 GMT
Etag	An identifier for a specific version of a resource	W/"465c975a3297a25173d3c2b284f638c0"
Server	Information about the software used by the origin server	Caddy
Transfer-Encoding	HTTP response header: Transfer-Encoding	chunked
X-Content-Type-Options	HTTP response header: X-Content-Type-Options	nosniff
X-Frame-Options	HTTP response header: X-Frame-Options	SAMEORIGIN
X-Identity-Id	HTTP response header: X-Identity-Id	61bf8f1c-2679-4e84-8c25-3ffa85b15099
X-Privileges	HTTP response header: X-Privileges	analytic:read,asset:map,asset:read,asset:write,auth:identity:read,baseline:read,baseline:update,case:create,case:read,file:upload,network:read,notification:read,notification:rule:read,notification:update,playbook:create,playbook:read,report:read,report:write,sensor:read,tasking:capture:create,tasking:read,vulnerability:log:read,vulnerability:read,vulnerability:rule:read
X-Request-Id	A unique identifier for the request	5vyck6pw0g-g7+6tfrp-mj5wxeijz4zxrn-=t+lw1ai1+=//pr-z742ijbkdv28v
X-Runtime	HTTP response header: X-Runtime	0.017550
X-Username	HTTP response header: X-Username	tp7864
X-Xss-Protection	HTTP response header: X-Xss-Protection	1; mode=block