0% found this document useful (0 votes)

78 views196 pages

Dragos Platform Developer Guide

Uploaded by

bid nbid

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

78 views196 pages

Dragos Platform Developer Guide

Uploaded by

bid nbid

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 196

Dragos Platform

Developer Guide
1
Proprietary Statement
This material constitutes proprietary and trade secret
information and shall not be disclosed to any third party,
nor used by the recipient except under the terms and
conditions prescribed by Dragos, Inc.

Dragos Global Headquarters

1745 Dorsey Rd
Suite R
Hanover, Maryland 21076
(855)-372-4670
[Link]

Customer Support Requests

[Link]
Table of Contents

1. Developer Guide....................................................................................................................... 3
2. Dragos Platform API................................................................................................................. 4
2.1. Overview........................................................................................................................................... 5
2.2. User API Keys in the Dragos Platform..............................................................................................6
2.3. Embedded Documentation............................................................................................................... 9
2.4. Security........................................................................................................................................... 11
2.4.1. Encryption...............................................................................................................................................12
2.4.2. Authentication......................................................................................................................................... 13
2.4.3. Authorization........................................................................................................................................... 25
2.6. Appendix A: Component API Documentation Pages......................................................................26
2.7. Appendix B: Privileges.................................................................................................................... 28

3. Assets..................................................................................................................................... 34
3.1. Retrieving Assets............................................................................................................................ 35
3.1.1. Overview.................................................................................................................................................36
3.1.2. Use Cases.............................................................................................................................................. 37
3.1.3. Requirements......................................................................................................................................... 39
3.1.4. Pre-Development Checklist.................................................................................................................... 40
3.1.5. Configuration Guidance.......................................................................................................................... 42
3.1.6. Integration Considerations...................................................................................................................... 43
3.1.7. Scenarios................................................................................................................................................44
3.1.8. Testing and Validation............................................................................................................................. 55
3.1.9. Maintenance and Support.......................................................................................................................58
3.1.10. Appendices........................................................................................................................................... 59
3.2. Retrieving Notifications by Asset.................................................................................................... 60
3.2.1. Overview.................................................................................................................................................61
3.2.2. Use Cases.............................................................................................................................................. 62
3.2.3. Requirements......................................................................................................................................... 64
3.2.4. Pre-Development Checklist.................................................................................................................... 65
3.2.5. Configuration Guidance.......................................................................................................................... 67
3.2.6. Integration Considerations...................................................................................................................... 68
3.2.7. Scenarios................................................................................................................................................69
3.2.8. Testing and Validation............................................................................................................................. 74
3.2.9. Maintenance and Support.......................................................................................................................77
3.2.10. Appendices........................................................................................................................................... 78
3.3. Retrieving Observed Protocols by Asset........................................................................................ 79
3.3.1. Overview.................................................................................................................................................80
3.3.2. Use Cases.............................................................................................................................................. 81
3.3.3. Requirements......................................................................................................................................... 83
3.3.4. Pre-Development Checklist.................................................................................................................... 84
3.3.5. Configuration Guidance.......................................................................................................................... 86
3.3.6. Integration Considerations...................................................................................................................... 87
3.3.7. Scenario..................................................................................................................................................88
3.3.8. Testing and Validation............................................................................................................................. 92
3.3.9. Maintenance and Support.......................................................................................................................95
3.3.10. Appendices........................................................................................................................................... 96
3.4. Retrieving Hardware Vulnerability Detections by Asset.................................................................. 97
3.4.1. Overview.................................................................................................................................................98
3.4.2. Use Cases.............................................................................................................................................. 99
3.4.3. Requirements....................................................................................................................................... 101
3.4.4. Pre-Development Checklist.................................................................................................................. 102
3.4.5. Configuration Guidance........................................................................................................................ 104
3.4.6. Integration Considerations.................................................................................................................... 105
3.4.7. Scenarios..............................................................................................................................................106
3.4.8. Testing and Validation........................................................................................................................... 118
3.4.9. Maintenance and Support.....................................................................................................................121
3.4.10. Appendices......................................................................................................................................... 122

4. Notifications...........................................................................................................................123
4.1. Retrieving Notifications................................................................................................................. 124
4.1.1. Overview...............................................................................................................................................125
4.1.2. Use Cases............................................................................................................................................ 126
4.1.3. Requirements....................................................................................................................................... 128
4.1.4. Pre-Development Checklist.................................................................................................................. 129
4.1.5. Configuration Guidance........................................................................................................................ 131
4.1.6. Integration Considerations.................................................................................................................... 132

1
4.1.7. Scenarios..............................................................................................................................................134
4.1.8. Testing and Validation........................................................................................................................... 149
4.1.9. Maintenance and Support.....................................................................................................................152
4.1.10. Appendices......................................................................................................................................... 153

5. Vulnerabilities........................................................................................................................ 154
5.1. Retrieving Vulnerability Detections............................................................................................... 155
5.1.1. Overview...............................................................................................................................................156
5.1.2. Use Cases............................................................................................................................................ 157
5.1.3. Requirements....................................................................................................................................... 159
5.1.4. Pre-Development Checklist.................................................................................................................. 160
5.1.5. Configuration Guidance........................................................................................................................ 162
5.1.6. Integration Considerations.................................................................................................................... 163
5.1.7. Scenarios..............................................................................................................................................164
5.1.8. Testing and Validation........................................................................................................................... 182
5.1.9. Maintenance and Support.....................................................................................................................185
5.1.10. Appendices......................................................................................................................................... 186

6. Using Queries and Filters with the Dragos SiteStore API V2................................................187

2
1. Developer Guide
· Dragos Platform API

· Assets

· Notifications

· Vulnerabilities

· Using Queries and Filters with the Dragos SiteStore API V2

3
2. Dragos Platform API
· Overview

· User API Keys in the Dragos Platform

· Embedded Documentation

· API Reference

· Appendix A: Component API Documentation Pages

· Appendix B: Privileges

4
2.1. Overview
While the SiteStore has several open ports, the scope of this document is to detail the usage of
the HTTPS API running on TCP port 443. Attempting to use HTTP on TCP port 80 will redirect
to HTTPS.

For the remainder of the document, the Dragos SiteStore HTTPS API is simply referred to as
the API. The API is just a composite of many component-level APIs, but in most cases, the
document will just refer to the holistic API.

WARNING: Improper use of the API may cause loss of data or degrade system integrity. Dragos
is not liable for any damages or errors resulting from third-party use of the API. Please contact
Dragos if support related to the use of the API is required.

5
2.2. User API Keys in the Dragos Platform

API Keys

1. Click + Add New API Key

6
Generate New API Key

2. The Generate New API Key box expands.

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

4. Click GENERATE KEY, and a message box appears.

API Successful Message Box

NOTE: This message box conations 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 is lost, then the API Key must be deleted and a new
API Key assigned.

7
5. Click OK and the API Key is configured.

Configured

API Key Delete Option

8
2.3. Embedded Documentation
Most component-level APIs host documentation that can be viewed in a web browser. These
are backed by OpenAPI (formerly Swagger) specifications that can be downloaded and
imported into a variety of development tools.

Many of the components render their specifications in Redoc, but a couple use Swagger UI.

Notifications API specification in Redoc

9
Case Management specification in Swagger UI

A table of paths to component API documentation pages is provided in Appendix A.

10
2.4. Security

11
2.4.1. Encryption

As mentioned, an HTTPS connection is required to interact with the API and the TLS certificate
can be set by an administrator of the SiteStore. Instructions on this are outside the scope of this
document. Any scripts or tooling interacting with the API will need to be configured to either trust
the TLS certificate chain or be configured insecurely to ignore certificate verification.

12
2.4.2. Authentication

Many, but not all, requests to the API require authentication. User accounts may have any
number of bindings to different authentication providers.

Example listing authentication providers:

GET /auth/api/v1/authProvider

200 OK

Content-Type: application/json

{
"pageNumber": 1,
"totalCount": 2,
"content": [{
"id": "00000000-0000-0000-0000-000000000001",
"name": "API Keys",
"builtIn": true,
"publicConfig": {
"type": "apikey"
}
},
{
"id": "00000000-0000-0000-0000-000000000002",
"name": "Username/Password",
"builtIn": true,
"publicConfig": {
"minLength": 12,

13
"minUppercase": 0,
"minLowercase": 0,
"minDigit": 0,
"minSpecial": 0,
"type": "password"
}
}],
"pageSize": 10,
"totalCountExceededLimit": false,
"totalPages": 1,
"sorts": []
}

Stateful Providers

Stateful providers perform a login action where the server creates and returns auth and refresh
tokens to the caller. The auth token must be provided as a Bearer Token to any endpoint in the
SiteStore which requires authorization. It should be noted that the auth token will eventually
expire at which point the refresh token can be used to generate a new token set for the
proceeding calls without needing the original credentials. The intended use is by web browsers.

Providers are used once in the authorization flow to validate the caller, after which the SiteStore
instance will use a traditional OAuth flow with the auth and refresh tokens to validate and
prolong the caller’s session.

Local Username and Password

This uses the user account’s username and a locally stored password as credentials.
Passwords are hashed and subject to configurable policies like minimum length, character type
counts, time-based expirations, and reuse history. Too many failed login attempts will
temporarily lock the account based on configured policy criteria. Expired passwords can be
reset by users directly; however, forgotten passwords must be reset to a temporary password by

14
an administrator. Temporary passwords are auto expired so users must reset them before being
allowed to log in.

While every user account has a username, some accounts may not have local passwords.

Example Username/Password login

POST /auth/api/v1/login/password?providerId=00000000-0000-0000-0000-000000000002

Content-Type: application/json

"username": "alice",

"password": "MyPAssw0rdIsTh3G0@t!"

200 OK

Set-Cookie: dragos-auth-token=eyJraWQiOiJhdXRoLWt....

Content-Type: application/json

{
"authToken": "$authToken",
"refreshToken": "$refreshToken",
"identity": {
"id": "00000000-0000-0000-0000-000000000004",
"name": "alice",
"legacyUsername": "alice",
"builtIn": true,
"roles": []

15
...
}
...
}

Example Username/Password reset

PUT /auth/api/v1/identity/:userId/password?providerId=00000000-0000-0000-0000-
000000000002

Content-Type: application/json

"username": "alice",

"password": "MyPAssw0rdIsTh3G0@t!"

204 No Content

LDAP

The LDAP provider sends authentication requests to configured LDAP

connections. Connections can be plaintext, LDAPS, or StartTLS and users can paste in, upload,
or fetch server certificates. LDAP group memberships can be mapped to Platform roles. There

16
is an admin endpoint for testing connection, authentication, and role mappings before applying
the configuration changes.

Because there may be multiple LDAP providers defined, the login endpoint requires specifying
which LDAP provider to authenticate against by ID.

Example LDAP login

POST /auth/api/v1/login/ldap?providerId=80b4f5e1-03df-43ef-9a02-8c6efc97d9c4

Content-Type: application/json

"username": "alice",

"password": "MyPAssw0rdIsTh3G0@t!"

200 OK

Set-Cookie: dragos-auth-token=eyJraWQiOiJhdXRoLWt....

Content-Type: application/json

{
"authToken": "$authToken",
"refreshToken": "$refreshToken",
"identity": {
"id": "00000000-0000-0000-0000-000000000004",
"name": "alice",

17
"legacyUsername": "alice",
"builtIn": true,
"roles": []
...
}
...
}

Post Login Actions

Once the caller has valid auth and refresh tokens from the SiteStore, they may begin using them
in the same manner regardless of their authentication provider.

Example Get Identities (easy way to view your own identity id and use in in subsequent
requests)

GET /auth/api/v1/identity/

Authorization: Bearer $authToken

Content-Type: application/json

200 OK

Set-Cookie: dragos-auth-token=$authToken

Content-Type: application/json

{
"pageNumber": 1,
"totalCount": 3,
"content": [
{

18
"id": "00000000-0000-0000-0000-000000000001",
"name": "Administrator",
"legacyUsername": "admin",
"builtIn": true,
"roles": [
{
"id": "00000000-0000-0000-0000-000000000001",
"name": "Administrator",
...
}
...
}
...
}

Example Refresh Token (to be used when your auth token expires):

POST /auth/api/v1/login/refresh

Authorization: Bearer $authToken

Content-Type: application/json

{
"refreshToken": "$refreshToken"
}

19
200 OK

Set-Cookie: dragos-auth-token=$New_Auth_Token...

Content-Type: application/json

{
"authToken": "$New_Auth_Token",
"refreshToken": "$New_Refresh_Token"
}

Example logout (to be used when your auth token expires):

POST /auth/api/v1/logout

Authorization: Bearer $authToken

200 OK

Example API request and response using a Bearer Token

POST /assets/api/v4/getAssets

Authorization: Bearer $authToken

{"selector":{"allOf":[{"idOrOldIdIn":[1]}],"isDeleted":null},"maskAddressTimeRanges":{"from":"202
4-01-01T[Link].000Z","to":"2024-02-20T[Link].999Z"}}

200 OK

Content-Type: application/json

20
{
"pageNumber": 1,
"pageSize": 10,
"sorts": [],
"totalCount": 1,
"totalPages": 1,
"content": [
{
"id": 1,
"oldIds": [],
"attributes": {
"[Link]": "Asset 1",
"[Link].last_seen": "2024-02-20T[Link].364Z",
"host.last_seen": "2024-02-20T[Link].364Z",
"[Link]": "1",
"host.address_id": [
1,
5
]
...
}
...
}
...
]
...
}

21
Stateless Providers

Stateless providers pass credentials on every request and do not create a session. There is no
login or logout needed, you simply make the API call using the credentials. The intended use is
for programmatic access like scripts or third-party tools.

API Keys

While the API supports API keys as of SiteStore 2.2, the management of them has not been
implemented on the SiteStore web UI yet. If you wish to use API keys, you will need to provision
them via the Authentication Management API first using another authentication described
above.

API keys are bound to a user account in the same way as any other authentication binding,
except the credentials are generated server-side. User accounts may have multiple API keys at
once and can be removed or renamed at any point. When a new API key is generated, the API
key ID and secret are returned. After this, the API key secret can no longer be retrieved from the
API. If the secret is forgotten, a new API key must be generated.

Example provisioning of an API key

POST /auth/api/v1/identity/{id}/apikey

Authorization: Bearer $authToken

Content-Type: application/json

{"name": "A new key"}

200 OK

Content-Type: application/json

22
"apiKeyId": "CR1sk11C9pH8aXzxzdwPQA==",

"apiKeySecret": "sgFZ8kW6BZSF0...nxX3D-GNtppFfTK59abSP70lJXA==",

"name": "A new key"

...

Once an API key has been generated, the ID and secret are passed in subsequent requests
using standard HTTP Basic Auth format ("Basic " + base64(id + ":" + secret)).

Example API request and response using an API key

POST /assets/api/v4/getAssets

Authorization: Basic Q1Ixc2sxMUM5...hYlNQNzBsSlhBPT0=

{"selector":{"allOf":[{"idOrOldIdIn":[1]}],"isDeleted":null},"maskAddressTimeRanges":{"from":"202
4-01-01T[Link].000Z","to":"2024-02-20T[Link].999Z"}}

200 OK

Content-Type: application/json

{
"pageNumber": 1,
"pageSize": 10,
"sorts": [],
"totalCount": 1,
"totalPages": 1,
"content": [
{

23
"id": 1,
"oldIds": [],
"attributes": {
"[Link]": "Asset 1",
"[Link].last_seen": "2024-02-20T[Link].364Z",
"host.last_seen": "2024-02-20T[Link].364Z",
"[Link]": "1",
"host.address_id": [
1,
5
]
...
}
...
}
...
]
...
}

24
2.4.3. Authorization

Most component APIs require the authenticated user account to have been granted various
privileges. Privileges are granted via roles assigned to the accounts. This can be done in the
SiteStore web UI or via the Authentication Management API.

While it may be tempting to provide a service user account the built-in “Administrator” role and
thus all privileges, it is considered security best practice to assign only privileges needed to
service accounts. Consider creating a custom role for a service account and assigning a limited
set of privileges as needed.

NOTE: As of SiteStore version 2.2, privileges have been renamed and in some cases several
combined. The components API documentation in many cases still may refer to the old
privileges. This will be gradually corrected in future releases, but for now please refer to
Appendix B for a mapping of old to new privilege names.

25
2.6. Appendix A: Component API Documentation Pages
All paths are relative to the root path of the SiteStore URL (for example, [Link]

Component API Documentation Path API Path

/assets/docs/[Link] /assets/api/v4/
Asset Inventory

/maps/docs/[Link] /maps/api/v1/
Asset Maps

/auth/docs/[Link] /auth/api/v1/
Authentication Management

/baselines/docs/[Link] /baselines/api/v3/
Baselines

/cases/docs/[Link] /cases/
Case Management

Data Import Service /ddis/docs/[Link] /ddis/api/v1/

/detections/docs/[Link] /detections/api/v1/
Detection Management

/files/docs/[Link] /files/api/v1/
Files

26
/nodes/docs/v1/[Link] /nodes/api/v1/
Node Management Service

Notifications /notifications/docs/[Link] /api/v2/notification

/reports/docs/[Link] /reports/api/v2/
Reports

/taskings/docs/[Link] /taskings/api/v1/
Taskings

/vulnerabilities/docs/[Link] /vulnerabilities/api/v1/
Vulnerabilities

27
2.7. Appendix B: Privileges

Name Consolidated Legacy Privileges Description

admin Admin Allow usage of various admin pages

and services.

analytic:beta:read AnalyticBeta Allow reading of beta analytic list

and details.

asset:delete AssetDelete Allow deleting of assets.

analytic:read AnalyticRead Allow reading of analytic list and

details.

analytic:manage · AnalyticCreate Allow creating, updating, deleting,

and manually running of analytics.
· AnalyticDelete
· AnalyticRestart
· AnalyticRun
· AnalyticUpdate

asset:map · AssetSnapshotCreate Allow generating and reading of

asset maps.
· AssetSnapshotDelete
· AssetSnapshotRead

asset:read AssetRead Allow reading of assets.

asset:write AssetWrite Allow updating, importing, and

merging of assets.

auth:provider:manage Manage authentication providers.

auth:identity:manage Manage identity accounts.

auth:identity:read Read identity accounts.

auth:role:manage Manage identity roles.

baseline:config BaselineAdmin Allow reading of baseline metadata

information.

baseline:read BaselineRead Allow reading of baseline metadata

information.

baseline:update BaselineUpdate Allow changes to the baseline itself

(add/remove to/from baseline).

case:admin CaseAdmin Administrative access over all

cases.

case:create CaseCreate Allow creation of cases.

28
case:read CaseRead Allow reading of cases.

detection:manage · DetectionCatalogConfigRead Manage detections

· DetectionCatalogConfigUpdate
· DetectionCatalogCreate
· DetectionCatalogDelete
· DetectionCatalogRead
· DetectionCreate
· DetectionDelete
· DetectionUpdate

detection:read Allow reading of detections

DetectionRead

file:delete FileDelete Allow deleting files.

file:packetcapture:download PacketCaptureDownload Allow downloading of packet capture

(PCAP) files.

file:packetcapture:metadata:update PacketCaptureMetadataUpdate Allow update of metadata for packet

capture (PCAP) files.

file:upload FileCreate Allow uploading files.

misc:jupyterhub JupyterhubAccess Allows logging in to the Jupyterhub

environment.

network:manage · NetworkCreate Allow creating, updating, and

deleting of networks.
· NetworkDelete
· NetworkMetadataUpdate

network:read NetworkRead Allow reading of networks.

notification:read NotificationRead Allow reading of notifications (not

including system notifications).

notification:rule:manage · NotificationCreationRuleActionCreate Allow management of notification

rules and actions.
· NotificationCreationRuleActionDelete
· NotificationCreationRuleActionUpdate
· NotificationCreationRuleCreate
· NotificationCreationRuleDelete
· NotificationCreationRuleUpdate
· NotificationCreationRuleWithDrop
· NotificaitonCreationRuleActionUpdate

notification:rule:read · NotificationCreationRuleActionRead Allow reading of notification rules

and actions.

29
· NotificationCreationRuleRead

notification:system:read NotificationSystemType Allow reading of system

notifications.

notification:update NotificationUpdate Allow updating of notifications.

playbook:admin PlaybookAdmin Administrative access over all

playbooks.

playbook:create PlaybookCreate Create a new playbook.

playbook:read PlaybookRead Allow reading of playbooks.

report:delete ReportDelete Allow deleting reports.

report:read ReportRead Allow reading of reports.

report:write ReportWrite Allow creating and updating of

reports.

sensor:manage · CollectorDelete Allow updating and deleting of

sensors and collectors.
· CollectorMetadataUpdate
· MidpointDelete
· MidpointMetadataUpdate
· SensorPairing

sensor:read · CollectorRead Allow reading of sensors and

collectors.
· MidpointRead

tasking:capture:create TaskingCreate Allow creation of capture taskings.

tasking:contentpack:create TaskingContentPackCreate Allow creation of Content Pack

deployment taskings.

tasking:delete TaskingDelete Allow deletion of taskings.

tasking:read TaskingRead Allow reading of taskings.

vulnerability:read · VulnerabilityRead Allow reading vulnerabilities and

detections.
· VulnerabilityDetectionRead

vulnerability:log:read VulnerabilityManagementAuditLogRead Allow reading of vulnerability audit

logs.

vulnerability:rule:manage · VulnerabilityDetectionRuleCreate Allow creating, updating, and

deleting of vulnerability detection
· VulnerabilityDetectionRuleUpdate
rules.
· VulnerabilityDetectionRuleDelete

30
vulnerability:rule:read · VulnerabilityDetectionRuleRead Allow reading of vulnerability
detection rules.

vulnerability:update · VulnerabilityDetectionUpdate Allow updating state of vulnerability

detections.

31
32
33
3. Assets
· Retrieving Assets

· Retrieving Notifications by Asset

· Retrieving Observed Protocols by Asset

· Retrieving Hardware Vulnerability Detections by Asset

34
3.1. Retrieving Assets
· Overview

· Use Cases

· Requirements

· Pre-Development Checklist

· Configuration Guidance

· Integration Considerations

· Scenarios

· Testing and Validation

· Maintenance and Support

· Appendices

35
3.1.1. Overview

This document is intended to provide guidance on pulling Notification information by Asset from
the Dragos Platform. Notification information can be retrieved from a Dragos SiteStore in a
variety of ways. This guide covers retrieving a count of Notifications for an Asset and retrieving a
list of all Notifications for an Asset.

This guide and the included code samples are provided solely as a reference to support with the development of
custom implementations. Nothing in the guide is intended to serve as a definitive solution for any possible use
case. Any information contained in the materials should be used in a way that aligns with your organization’s
programming languages, frameworks, and security practices. All content is provided on an "as is" basis and
without any warranties, conditions or support of any kind whether express or implied.

36
3.1.2. Use Cases

1. Asset Inventory and Visibility

Use Case: Maintain a complete and accurate inventory of all devices.
How It Helps: Identifies what is on the network, including device type, OS, installed
software, and configurations—critical for managing security posture.
2. Vulnerability and Patch Management
Use Case: Identify and remediate vulnerabilities based on asset context.
How It Helps: Knowing the OS version, installed applications, and firmware allows for
targeted vulnerability scanning and patching.
3. Risk Assessment and Prioritization
Use Case: Evaluate and rank assets based on their risk profile.
How It Helps: High-value or high-risk assets (e.g., domain controllers, legacy systems) can
be prioritized for protection and monitoring.
4. Network Segmentation and Access Control
Use Case: Enforce security zones and least privilege access.
How It Helps: Device roles and types (e.g., IoT, servers, workstations) inform
segmentation strategies and firewall rules.
5. Threat Detection
Use Case: Identify unusual behavior or unauthorized changes.
How It Helps: Baselines can be established for normal operations per asset type, enabling
detection of deviations.
6. Incident Response and Forensics
Use Case: Investigate and contain security incidents.
How It Helps: Detailed asset data helps responders understand the scope of compromise
and determine the best containment strategy.
7. Shadow IT and Rogue Device Detection
Use Case: Identify unmanaged or unauthorized devices.
How It Helps: Compares known asset profiles with real-time network activity to flag
unknown or suspicious devices.

37
8. Security Architecture and Planning
Use Case: Design and evolve a secure network infrastructure.
How It Helps: Informs decisions about where to place security controls, deploy monitoring,
or upgrade hardware/software.

PreviousNext

38
3.1.3. Requirements

System Requirements
1. Dragos Platform 3.x

2. SiteStore API v2

Network Requirements
1. TCP/IP connection between the API client and Dragos Platform SiteStore (normally
tcp/443)

PreviousNext

39
3.1.4. Pre-Development Checklist

API Usage

The SiteStore v2 API endpoints referenced in this guide are part of the latest enhancements introduced in the
Dragos Platform 3.0. For backward compatibility, the SiteStore 1.1 API will remain available for a limited time.
Customers and partners will receive advance notice of any deprecation through our standard product
announcement channels.

The SiteStore API documentation can be found at SiteStore API v2. The OpenAPI spec is also
available at [Link]

This guide will cover the use of the /api/v2/assets endpoint. To view all details about this
endpoint please refer to the API documentation linked above.

Authentication

API access requires either an API key or an OAuth 2.0 Bearer Access Token in JWT format.

OAuth2 Bearer tokens are recommended because they are dynamic, have an expiration period,
and can be refreshed, whereas API keys remain static and do not expire.

Authorization

The user account(s) for API access should be assigned to a role which provides least privilege
access. To read Asset data for this use case, the API user should be assigned a role for which
asset:read access has been granted.

SSL

To minimize potential SSL connections issues with your integration, it is recommended to use a
public Certificate Authority to issue the Web Server certificate protecting the SiteStore. Please
see the Dragos Platform Admin Guide for information on how to update your certificate, if
needed.

40
PreviousNext

41
3.1.5. Configuration Guidance

Permissions

Choosing the balance between number of users and roles required to perform platform
integration is outside of the scope of this guide, however, it is strongly advised that you do not
assign the admin role to API users.

A detailed description of available Permissions, user and role management can be found in the Dragos Platform
Admin Guide.

PreviousNext

42
3.1.6. Integration Considerations

Rate Limitations

SiteStore API Version 2.0 and earlier do not include API rate limiting. As a result, a high
volumes of requests may lead to performance issues on the Dragos Platform SiteStore.

Pagination

The SiteStore v2 API returns a meta object with the metadata about pagination.

JSON

{
"meta": {
"pageNumber": <The current page of results being returned>,
"pageSize": <The number of items included per page>,
"totalItems": <The total number of items available across all pages>
}
}

To ensure you retrieve all available results, use these values to iterate through each page of
data until all items are collected.

PreviousNext

43
3.1.7. Scenarios

· Scenario 1: Retrieve Asset data using a known Dragos Asset ID

· Scenario 2: Retrieve Asset data using known attribute value

· Scenario 3: Get all Asset information

Scenarios

Scenario 1: Retrieve Asset data using a known Dragos Asset ID

Get Asset by ID endpoint api/v2/assets/{id} is used to retrieve a single asset by its known
Dragos Asset ID.

Asset Address information can be obtained through the addition of the expand
parameter addresses.

The addresses expansion retrieves the asset's associated [Link], a unique identifier that can be configured
on the SiteStore to meet specific customer environment needs. This ID enables differentiation between assets
that may share identical attributes—such as IP addresses—across multiple environments.

GET Request Sample

GET /api/v2/assets/10?expand=addresses

Request Headers

Authorization: …

Response Headers

HTTP/2 200

Response

44
JSON

{
"id": "10",
"name": "Asset 10",
"type": "General Use Desktop",
"class": "Business User Workstation",
"zone": {
"id": "1",
"name": "RFC1918",
"expansion": "expanded",
"description": "Address Allocation for Private Internets"
},
"os": {
"family": "Windows",
"full": "Windows 10",
"kernel": "",
"name": "Windows 10",
"platform": "Windows",
"version": "10.0"
},
"tags": [
"DnsQuery",
"HTTPRequest",
"HTTPResponse",
"WebClient",
"DnsResponse"
],
"addresses": [
{
"id": "16",
"addressType": "MAC",
"value": "[Link]",
"expansion": "expanded",
"scope": {
"type": "network",
"id": "1e1b6980-902a-482b-af00-eae50306e2e0"
},
"firstObservedTime": "2025-08-04T[Link].559Z",
"lastObservedTime": "2025-08-04T[Link].694Z",
"observers": [
"cbb9f58b-b946-4c76-b839-f7c42db1ca6f"
]
},
{
"id": "18",
"addressType": "IP",
"value": "[Link]",
"expansion": "expanded",
"scope": {

45
"type": "network",
"id": "1e1b6980-902a-482b-af00-eae50306e2e0"
},
"firstObservedTime": "2025-08-04T[Link].559Z",
"lastObservedTime": "2025-08-04T[Link].695Z",
"observers": [
"cbb9f58b-b946-4c76-b839-f7c42db1ca6f"
]
},
{
"id": "7810",
"addressType": "HOSTNAME",
"value": "windows10enterp",
"expansion": "expanded",
"firstObservedTime": "2025-08-04T[Link].477Z",
"lastObservedTime": "2025-08-04T[Link].741Z",
"observers": [
"cbb9f58b-b946-4c76-b839-f7c42db1ca6f"
]
}
],
"connectedAssets": [],
"notificationCounts": {
"total": 8,
"critical": 0,
"high": 0,
"medium": 0,
"low": 5
},
"vulnerabilityCounts": {
"total": 0,
"critical": 0,
"high": 0,
"medium": 0,
"low": 0
},
"baselines": [],
"connectedRootDevice": false,
"firstObservedTime": "2025-08-04T[Link].723Z",
"lastObservedTime": "2025-08-04T[Link].345Z",
"monitored": true,
"labels": {
"zone_name": "RFC1918",
"LastReconciledTime": "2025-08-04T[Link].164803133Z",
"AttributesLastObservedDate": "2025-08-04"
}
}

46
In the event there the Asset ID does not exist, the response will be similar that below.

Response Headers

HTTP/2 404
content-type: application/json

Response

JSON

{
...
"statusCode": 404,
"error": {
"id": "RESOURCE_NOT_FOUND",
"parameters": {
"message": "Asset '99' not found"
}
},
"message": "Asset '99' not found"
}

Scenario 2: Retrieve Asset data using known attribute value

If the Dragos Asset ID for enrichment is unknown, you can refine your search using the filter
query parameter. This allows you to retrieve all matching Assets and their attributes in a JSON
response. Example search fields and supported operators are provided in Appendix B. Logical
expressions such as AND and OR can be used for precise filtering.

A filter query parameter to search for the known hardware MAC address would be as follows:

filter: search matches "[Link]"

GET Request Sample

47
GET /api/v2/assets?expand=addresses&filter=search%20matches%20%2200%3A50%3A56%3A86%3
AFA%3A19%22

Request Headers

Authorization: ...

Response Headers

HTTP/2 200
content-type: application/json

Response

JSON

{
"meta": {
"pageNumber":1,
"pageSize":50,
"totalItems":1
},
"content": [
{"id":"10",
"name":"Asset 10",
"type":"General Use Desktop",
"class":"Business User Workstation",
"zone": {
"id":"1",
"expansion":"reference"
},
"os": {
"family":"Windows",
"full":"Windows 10",
"kernel":"",
"name":"Windows 10",
"platform":"Windows",
"version":"10.0"
},
"tags": [
"DnsQuery",
"HTTPRequest",
"HTTPResponse",
"WebClient",

48
"DnsResponse"
],
"addresses": [
{"id":"16",
"expansion":"reference"
},
{
"id":"18",
"expansion":"reference"
},
{
"id":"7810",
"expansion":"reference"
}
],
"connectedAssets": [
],
"baselines": [
],
"connectedRootDevice":false,
"firstObservedTime":"2025-08-04T[Link].723Z",
"lastObservedTime":"2025-08-04T[Link].164Z",
"monitored":true,
"labels": {
"zone_name":"RFC1918",
"LastReconciledTime":"2025-08-04T[Link].253908855Z",
"AttributesLastObservedDate":"2025-08-04"
}
}
]
}

In the event there is no match to the query, the response will be similar that below.

Response Headers

HTTP/2 200
content-type: application/json

Response

JSON

49
{
"meta": {
"pageNumber": 1,
"pageSize": 50,
"totalItems": 0
},
"content": []
}

Scenario 3: Get all Asset information

If you need to fetch all Assets from the Dragos Platform using the Get Assets API, you may
need to retrieve results in paginated sections. If pageNumber and pageSize are not specified in
the query parameters, the default settings apply: pageNumber starts at 1, and pageSize is set to
50 Assets per request.

GET Request Sample

GET /api/v2/assets?pageSize=100&pageNumber=1

Request Headers

Authorization: ...

Response Headers

HTTP/2 200
content-type: application/json

Response

JSON

50
{
"meta": {
"pageNumber": 1,
"pageSize": 100,
"totalItems": 11763
},
"content": [{
"id": "10718",
"name": "Asset 10718",
"addresses": [{
"id": "12945",
"expansion": "reference"
}, {
"id": "9605",
"expansion": "reference"
}
],
"connectedAssets": [],
"baselines": [],
"connectedRootDevice": false,
"firstObservedTime": "2025-08-04T[Link].852Z",
"lastObservedTime": "2025-08-04T[Link].852Z",
"labels": {
"LastReconciledTime": "2025-08-04T[Link].869245978Z"
}
},
...
]
}

The fields and filter query parameters allow for customization of result sets. To limit the results
to just the Asset id, Asset name, and Addresses, the following comma-separated list of fields
can be added to fields query parameter.

fields=id,name,addresses

The ensure the address information is displayed, include the address expand.

expand=addresses

51
By selectively retrieving a recent time period, reprocessing of the entire dataset can be avoided.
In the example below, only Assets which have been observed within the past day would be
returned.

lastObservedTime gt -1d ORDER BY [Link]

GET Request Sample

GET
/api/v2/assets?fields=id,name,addresses&expand=addresses&filter=lastObservedTime%20g
t%20-1d%20ORDER%20BY%[Link]

Request Headers

Authorization: ...

Response Headers

HTTP/2 200
content-type: application/json

Response

JSON

{
"content": [{
"id": "1",
"name": "Asset 1",
"addresses": [{
"id": "2",
"addressType": "MAC",
"value": "[Link]",
"expansion": "expanded",
"scope": null,
"network": null,
"firstObservedTime": 1754302710.32,
"lastObservedTime": 1754302710.32,
"observers": []
}, {

52
"id": "1",
"addressType": "IP",
"value": "[Link]",
"expansion": "expanded",
"scope": null,
"network": null,
"firstObservedTime": 1754302710.3,
"lastObservedTime": 1754302710.3,
"observers": []
}, {
"id": "3",
"addressType": "HOSTNAME",
"value": "[Link]",
"expansion": "expanded",
"scope": null,
"network": null,
"firstObservedTime": 1754302710.74,
"lastObservedTime": 1754302710.74,
"observers": []
}
]
}, {
"id": "10",
"name": "Asset 10",
"addresses": [{
"id": "16",
"addressType": "MAC",
"value": "[Link]",
"expansion": "expanded",
"scope": {
"type": "network",
"id": "1e1b6980-902a-482b-af00-eae50306e2e0"
},
"network": null,
"firstObservedTime": 1754303748.559,
"lastObservedTime": 1754334522.622,
"observers": ["cbb9f58b-b946-4c76-b839-f7c42db1ca6f"]
}, {
"id": "18",
"addressType": "IP",
"value": "[Link]",
"expansion": "expanded",
"scope": {
"type": "network",
"id": "1e1b6980-902a-482b-af00-eae50306e2e0"
},
"network": null,
"firstObservedTime": 1754303748.559,
"lastObservedTime": 1754334490.627,
"observers": ["cbb9f58b-b946-4c76-b839-f7c42db1ca6f"]
}, {

53
"id": "7810",
"addressType": "HOSTNAME",
"value": "windows10enterp",
"expansion": "expanded",
"scope": null,
"network": null,
"firstObservedTime": 1754304110.477,
"lastObservedTime": 1754334348.168,
"observers": ["cbb9f58b-b946-4c76-b839-f7c42db1ca6f"]
}
]
},
...
],
"meta": {
"pageNumber": 1,
"pageSize": 50,
"totalItems": 11966,
"expansionErrors": null
}
}

PreviousNext

54
3.1.8. Testing and Validation

Python Code Sample

This code sample demonstrates the use of the /api/v2/assets endpoint with filter by Hardware
Vendor to test the endpoint and verify expected data.

Python

import os
import requests
import json
from tabulate import tabulate

# Step 1: Get Bearer Token

username = [Link]("API_USERNAME", "Variable not found")
password = [Link]("API_PASSWORD", "Variable not found")
login_url = "[Link]
login_payload = {
"type": "password",
"username": f"{username}",
"password": f"{password}"
}
login_headers = {
"Content-Type": "application/json"
}

login_response = [Link](login_url, headers=login_headers,

json=login_payload)
login_data = login_response.json()

# Extract token
bearer_token = login_data.get("authToken")
if not bearer_token:
raise Exception("Failed to retrieve bearer token")

# Step 2: Use Bearer Token for API Calls

base_url = "[Link]
headers = {
'Authorization': f'Bearer {bearer_token}',
'Content-Type': 'application/json'
}

all_data = []

55
params = {
"filter": '[Link] eq "Rockwell Automation"'
}

while True:
response = [Link](base_url, headers=headers, params=params)
data = [Link]()

content = [Link]("content", [])

all_data.extend(content)

meta = [Link]("meta", {})

total_items = [Link]("totalItems", 0)
page_size = [Link]("pageSize", 50)
current_page = [Link]("pageNumber", 1)

if len(all_data) >= total_items:

break

params["pageNumber"] += 1

# Prepare table data

table_data = []
for asset in all_data:
hardware = [Link]("hardware", {})
table_data.append([
[Link]("id", "N/A"),
[Link]("name", "N/A"),
[Link]("family", "N/A"),
[Link]("firmware", "N/A"),
[Link]("model", "N/A"),
[Link]("series", "N/A")
])

# Print table
print(tabulate(table_data, headers=["Asset ID", "Asset Name", "Family",
"Firmware", "Model", "Series"], tablefmt="grid"))

Troubleshooting Common Response codes

Response Common issues

Codes

400
Bad Request: URL String Syntax Error. Possible illegal character.

Check the URL and request syntax and parameters.

56
401 Unauthorized - Authentication is required and has failed or is missing. Verify the token is not expired. Verify
user has been granted a role with the permissions required to perform the operation.

403 Forbidden Check permissions to access this resource. Authentication was successful but authorization failed.

404 Check the URL; Check the response for "Asset 'x' not found" message

PreviousNext

57
3.1.9. Maintenance and Support

Maintaining this integration requires a thorough understanding what changes to the API
specifications result during the evolution of the Dragos Platform. Typically, backward
compatibility is preserved within updates of the same major release. However, major version
increments may introduce breaking changes to some APIs.

To ensure a smooth transition, it is crucial to review version upgrade release notes and consult
the Dragos API guides to identify potential modifications. Any integration changes should be
tested in a pre-production environment before deployment.

Support for integrations should begin with Dragos Customer Portal or Dragos Partner Portal,
where integrators can access documentation, request assistance, and explore product updates.

PreviousNext

58
3.1.10. Appendices

Appendix A - API Endpoints referenced in this guide

· /api/v2/auth/login

· /api/v2/assets

Appendix B - Filter Query Examples for Common Filters

Attribute Operator Example

IP Address equals [Link] eq "[Link]"

IPv4 CIDR matches [Link] matches '[Link]/24'

MAC Address exists [Link] exists true

Hardware Vendor equals [Link] eq "Emerson"

Zone Name (v 2.6+) equals [Link] eq "RFC1918"

59
3.2. Retrieving Notifications by Asset
· Overview

· Use Cases

· Requirements

· Pre-Development Checklist

· Configuration Guidance

· Integration Considerations

· Scenarios

· Testing and Validation

· Maintenance and Support

· Appendices

60
3.2.1. Overview

This document is intended to provide guidance on pulling Notification Information by Asset from
the Dragos Platform. Notification Information can be retrieved from a Dragos SiteStore in a
variety of ways. This guide covers retrieving a count of Notifications for an Asset and retrieving a
list of all Notifications for an Asset.

Additional Notification use cases such as the forwarding of Notifications may be by utilizing the
syslog integration functionality of Dragos SiteStore. For further details, please refer to the
Dragos Platform Syslog Integration guide available from the Dragos Customer Portal.

61
3.2.2. Use Cases

1. Threat Containment and Incident Response

Use Case: Quickly isolate compromised devices to prevent lateral movement or data
exfiltration.
How It Helps: If a device is associated with malware, command-and-control (C2) traffic, or
brute-force attempts, it can be quarantined or segmented immediately.
2. Threat Attribution and Root Cause Analysis
Use Case: Understand how and why a device was targeted or compromised.
How It Helps: Observed threats (e.g., phishing, ransomware, port scanning) help analysts
trace the attack vector and attacker behavior.
3. Risk Scoring and Prioritization
Use Case: Assign risk levels to devices for focused remediation.
How It Helps: Devices with a history of threats or repeated targeting can be prioritized for
patching, monitoring, or replacement.
4. Automated Threat Response
Use Case: Trigger automated actions based on threat detection.
How It Helps: Detection of known threats (e.g., indicators of compromise or IOCs) can
trigger playbooks that block IPs, disable accounts, or alert SOC teams.
5. Threat Intelligence Enrichment
Use Case: Correlate local threat data with global threat intelligence feeds.
How It Helps: Observed threats can be matched with known campaigns, malware families,
or attacker TTPs (tactics, techniques, and procedures).
6. Compliance and Audit Readiness
Use Case: Demonstrate proactive threat detection and response.
How It Helps: Logs of observed threats and responses provide evidence for regulatory
compliance (e.g., HIPAA, PCI-DSS, NIST).
7. Behavioral Analytics and Threat Hunting
Use Case: Identify stealthy or evolving threats.

62
How It Helps: Repeated atomic threat detections or threat patterns on a device can
indicate advanced persistent threats (APTs) or insider threats.
8. Device Reputation and Trust Scoring
Use Case: Determine if a device should be trusted on the network.
How It Helps: Devices with a history of threats may be flagged as high-risk and subject to
stricter access controls or monitoring.

PreviousNext

63
3.2.3. Requirements

System Requirements
1. Dragos Platform 3.x

2. SiteStore API v2

Network Requirements
1. TCP/IP connection between the API client and Dragos Platform SiteStore (normally
tcp/443)

PreviousNext

64
3.2.4. Pre-Development Checklist

API Usage

The SiteStore API documentation can be found at SiteStore API v2. The OpenAPI spec is also
available at [Link]

This guide will cover the use of the /api/v2/assets and /api/v2/notifications endpoints. To view
all details about these endpoints please refer to the API documentation linked above.

Authentication

API access requires either an API key or an OAuth 2.0 Bearer Access Token in JWT format.

OAuth2 Bearer tokens are recommended because they are dynamic, have an expiration period,
and can be refreshed, whereas API keys remain static and do not expire.

Authorization

The user account(s) for API access should be assigned to a role which provides least privilege
access. To read notification data for this use case, the API user should be assigned a role for
which asset:read and notification:read access has been granted.

SSL

65
PreviousNext

66
3.2.5. Configuration Guidance

Permissions

A detailed description of available Permissions, user and role management can be found in the Dragos Platform
Admin Guide.

PreviousNext

67
3.2.6. Integration Considerations

Rate Limitations

SiteStore API Version 2.0 and earlier do not include API rate limiting. As a result, a high
volumes of requests may lead to performance issues on the Dragos Platform SiteStore.

Pagination

The SiteStore v2 API returns a meta object with the metadata about pagination.

JSON

{
"meta": {
"pageNumber": <The current page of results being returned>,
"pageSize": <The number of items included per page>,
"totalItems": <The total number of items available across all pages>
}
}

To ensure you retrieve all available results, use these values to iterate through each page of
data until all items are collected.

PreviousNext

68
3.2.7. Scenarios

· Scenario 1: Retrieve Notifications Counts by Asset

· Scenario 2: Retrieve Notifications by Asset

Scenarios

Scenario 1: Retrieve Notifications Counts by Asset

If you know the Dragos Asset ID, the Get Asset by ID endpoint /api/v2/assets/{id} can be used
along with the NotificationCounts expand parameter to retrieve all total Notification counts in
JSON format.

GET Request Sample

GET /api/v2/assets/4025?expand=notificationCounts

Request Headers

Authorization: …

Response Headers

HTTP/2 200
content-type: application/json

Response

The response contains a notificationCounts object with the a total key value of 145, as seen in
JSON response below..

JSON

69
{
"id": "4025",
"name": "Asset 4025",
"type": "Remote Terminal Unit",
"class": "Controller",
"purdueLevel": 1,
"zone": {
"id": "1",
"expansion": "reference"
},
"tags": [
"OT",
"Field Device",
"DNP3 Outstation Device",
"Controller",
"Remote Terminal Unit"
],
"addresses": [
{
"id": "9130",
"expansion": "reference"
}
],
"connectedAssets": [],
"notificationCounts": {
"total": 145,
"critical": 24,
"high": 0,
"medium": 49,
"low": 48
},
"baselines": [],
"connectedRootDevice": false,
"firstObservedTime": "2025-07-16T[Link].54Z",
"lastObservedTime": "2025-08-08T[Link].833Z",
"ot": true,
"monitored": true,
"labels": {
"zone_name": "RFC1918",
"ObservedBy": [
"vispair02ns100sensor"
],
"Monitored-OT": "true",
"Monitored-OTPeer": "true",
"LastReconciledTime": "2025-08-08T[Link].380076485Z",
"AttributesLastObservedDate": "2025-07-25"
}
}

70
Scenario 2: Retrieve Notifications by Asset

To retrieve the Notification Details for an Asset, the List Notifications

endpoint /api/v2/notifications is used with a filter HTTP Header containing the Asset ID number.

filter: [Link] eq "4025"

GET Request Sample

GET /api/v2/notifications?filter=[Link]%20eq%20%224025%22

Request Headers

Authorization: ...

Response Headers

HTTP/2 200
content-type: application/json

Response

The response metadata "totalItems": 145 matches the "notificationCounts": {"total": 145,..} value
from Scenario 1.

JSON

{
"meta": {
"pageNumber": 1,
"pageSize": 50,
"totalItems": 145
},
"content": [
{
"id": "2253",
"source": "Network Traffic",
"reviewed": false,
"state": "Unresolved",

71
"type": "Communication",
"severity": 4,
"summary": "DNP3 Stop Application Flood Detected",
"content": "Possible DNP3 stop application flood detected, with
Asset 4027 ([Link]) sending 39 stop application commands to Asset
4025 ([Link]) in a 15 minute window",
"updatedAt": "2025-07-16T[Link]Z",
"endpoints": [
{
"asset": {
"id": "4025",
"expansion": "reference"
},
"roles": [
"Destination"
]
},
{
"asset": {
"id": "4027",
"expansion": "reference"
},
"roles": [
"Source"
]
}
],
"detection": {
"id": "29e9982f-db30-4a19-82c3-b825b62b2793",
"expansion": "expanded",
"detectionQuads": [
"Indicator"
],
"threatInfo": [],
"intelReports": [
"None"
]
},
"firstSeenAt": "2025-07-16T[Link]Z",
"lastSeenAt": "2025-07-16T[Link]Z",
"count": 1
},
...
]
}

If there are no results, a JSON response similar to that below will be returned.

72
Response Headers

HTTP/2 200
content-type: application/json

Response

JSON

{
"meta": {
"pageNumber": 1,
"pageSize": 50,
"totalItems": 0
},
"content": []
}

PreviousNext

73
3.2.8. Testing and Validation

Python Code Sample

This code sample demonstrates the /notifications/api/v2/notification endpoint to test the

endpoint and verify expected data. It is provided as a reference, with no recommendation to use
this code. You should use your preferred API client.

Python

import os
import requests
import json
import [Link]

# Step 1: Get Bearer Token

username = [Link]("API_USERNAME", "Variable not found")
password = [Link]("API_PASSWORD", "Variable not found")
login_url = "[Link]
login_payload = {
"type": "password",
"username": username,
"password": password
}
login_headers = {
"Content-Type": "application/json"
}

login_response = [Link](login_url, headers=login_headers,

json=login_payload)
login_data = login_response.json()

# Extract token
bearer_token = login_data.get("authToken")
if not bearer_token:
raise Exception("[ERROR] Failed to retrieve bearer token")

# Step 2: Prepare API Request

base_url = "[Link] # Replace with
actual endpoint

# Variables for filter

asset_id = "4025"

74
state_val = "UNRESOLVED"
time_window_1 = "-7d"
time_window_2 = "-1d"

# Construct filter string

filter_conditions = (
f"(firstObservedTime gte {time_window_1} AND lastObservedTime gte
{time_window_2}) "
f"AND [Link] eq '{asset_id}' AND state eq \"{state_val}\""
)

group_by = "assetId"
page_size = 100

query_params = {
"groupBy": group_by,
"filter": filter_conditions,
"pageSize": page_size
}

query_string = [Link](query_params, safe="()=;!:'\" ")

request_url = f"{base_url}?{query_string}"

headers = {
'Authorization': f'Bearer {bearer_token}',
'Content-Type': 'application/json'
}

response = [Link](request_url, headers=headers)

data = [Link]()

print(f"\nFor asset ID [{asset_id}], we found:")

if [Link]("content"):
for item in data["content"]:
print(f"Notification ID {item['id']} is Summary of {item['summary']}
and state is {item['state']}")
else:
print("No notifications found.")

Troubleshooting Common Response codes

Response Common issues

Codes

400
Bad Request: URL String Syntax Error. Possible illegal character.

75
Check the URL and request syntax and parameters.

401 Unauthorized - Authentication is required and has failed or is missing. Verify the API key and secret are
correct and encoded properly. If using Oauth2, verify token is not expired. Verify user has been granted a
role with the permissions required to perform the operation.

403 Forbidden Check permissions to access this resource. Authentication was successful but authorization
failed.

404 Check the URL; Check the response for "Asset 'x' not found" message

PreviousNext

76
3.2.9. Maintenance and Support

Support for integrations should begin with Dragos Customer Portal or Dragos Partner Portal,
where integrators can access documentation, request assistance, and explore product updates.

PreviousNext

77
3.2.10. Appendices

Appendix A - API Endpoints referenced in this guide

· /api/v2/auth/login

· /api/v2/assets

· /api/v2/notifications

78
3.3. Retrieving Observed Protocols by Asset
· Overview

· Use Cases

· Requirements

· Pre-Development Checklist

· Configuration Guidance

· Integration Considerations

· Scenario

· Testing and Validation

· Maintenance and Support

· Appendices

79
3.3.1. Overview

This document aims to offer guidance on retrieving observed network protocols for an asset or
set of assets from the Dragos Platform. It covers steps for navigating the interface, utilizing
search functions, and interpreting the data presented. Additionally, it provides best practices for
ensuring accurate and comprehensive extraction of network protocol data to support security
and operational analysis.

80
3.3.2. Use Cases

1. Network Visibility and Asset Discovery

Use Case: Identify all devices and their roles on the network.
How Protocols Help: Protocols like DHCP, DNS, HTTP, and SNMP can reveal device
types, operating systems, and functions.
2. Intrusion Detection and Anomaly Detection
Use Case: Detect unauthorized or suspicious behavior.
How Protocols Help: If a device suddenly starts using a protocol it never used before (e.g.,
SSH or FTP), it could indicate compromise or lateral movement.
3. Access Control and Segmentation
Use Case: Enforce least privilege and network segmentation.
How Protocols Help: Knowing that a printer only uses IPP and SNMP, for example, allows
you to block all other protocols to/from it.
4. Encryption and Compliance Monitoring
Use Case: Ensure sensitive data is transmitted securely.
How Protocols Help: Detect use of insecure protocols (e.g., HTTP, Telnet, FTP) and
enforce secure alternatives (e.g., HTTPS, SSH, SFTP).
5. Threat Hunting and Forensics
Use Case: Investigate incidents and trace attacker behavior.
How Protocols Help: Protocol logs (e.g., SMB, RDP, DNS) can reveal attacker tools, lateral
movement, and data exfiltration paths.
6. Vulnerability Management
Use Case: Identify and prioritize vulnerabilities.
How Protocols Help: Certain protocols (e.g., SMBv1, NetBIOS) are known to be
vulnerable. Their presence can trigger patching or deprecation efforts.
7. Behavioral Baselines and Machine Learning
Use Case: Build normal behavior profiles for devices.
How Protocols Help: Protocol usage patterns help define what’s “normal” for a device,
aiding in anomaly detection.

81
PreviousNext

82
3.3.3. Requirements

System Requirements

Dragos Platform version 3.0 and greater.

Network Requirements

TCP/IP connection between the API client and Dragos Platform SiteStore (normally tcp/443)

PreviousNext

83
3.3.4. Pre-Development Checklist

API Usage

The SiteStore API documentation can be found at SiteStore API v2. The OpenAPI spec is also
available at [Link]

This guide will cover the use of the assets/api/v4/createAssetCommunicationsSnapshot

endpoint. To view all details about this endpoint please refer to the API documentation linked
above.

Authentication

API access requires either an API key or an OAuth 2.0 Bearer Access Token in JWT format.

OAuth2 Bearer tokens are recommended because they are dynamic, have an expiration period,
and can be refreshed, whereas API keys remain static and do not expire.

Authorization

SSL

To minimize potential SSL connections issues with your integration, it is recommended to use a
public Certificate Authority to issue the Web Server certificate protecting the SiteStore. Please

84
see the Dragos Platform Admin Guide for information on how to update your certificate, if
needed.

PreviousNext

85
3.3.5. Configuration Guidance

Permissions

A detailed description of available Permissions, user and role management can be found in the Dragos Platform
Admin Guide.

PreviousNext

86
3.3.6. Integration Considerations

Rate Limitations

Version 3.0 and earlier do not include API rate limiting. As a result, a high volumes of requests
may lead to performance issues on the Dragos Platform SiteStore.

PreviousNext

87
3.3.7. Scenario

Scenario 1: View protocol discovered for an asset

POST Request Sample

POST /assets/api/v4/createAssetCommunicationsSnapshot
{"assetId": 30,"timeRange": {"from": "2025-06-16T[Link]Z","to": "2025-07-
01T[Link]Z"}}

Request Headers

Authorization: …

Response Headers

content-type: application/json

Response

JSON

{
"metadata": {
...
},
"view": {
"type": "assets",
"parameters": {
"type": "assets"

},
...
"protocolCounts": [
{
"protocolId": "ARP",
"count": 1
},

88
{
"protocolId": "NTP",
"count": 1

},
{
"protocolId": "DELTAV-RTP",
"count": 1

},
{
"protocolId": "TCP",
"count": 1

},
{
"protocolId": "DELTAV_DOP",
"count": 1

],
"protocolSummary": [
{
"protocolId": "ARP",
"bytes": 491244524,
"packets": 7467649,
"clientPorts": [
],
"serverPorts": [
]

},
{
"protocolId": "NTP",
"ipProtocolId": "udp",
"bytes": 67903448,
"packets": 732772,
"clientPorts": [
123
],
"serverPorts": [
123
]

},
{
"protocolId": "DELTAV_DOP",
"ipProtocolId": "udp",
"bytes": 13648308324,
"packets": 82245548,

89
"clientPorts": [
18507
],
"serverPorts": [
18507
]

},
{
"protocolId": "TCP",
"ipProtocolId": "tcp",
"bytes": 334300,
"packets": 812,
"clientPorts": [
62129,
61601,
58371,
50420,
61718,
50713,
58665,
51978,
64861,
58157
],
"serverPorts": [
18519
]

},
{
"protocolId": "DELTAV-RTP",
"ipProtocolId": "tcp",
"bytes": 1111972456,
"packets": 1626620,
"clientPorts": [
50000...
]
"serverPorts": [
18519
]

],
"type": "assets"

}
}

90
PreviousNext

91
3.3.8. Testing and Validation

Python Code Sample

This code sample demonstrates the api/v4/createAssetCommunicationsSnapshot endpoint to

test and verify expected output. It is provided as a reference, with no recommendation to use
this code. You should use your preferred API client.

Python

import os
import requests
import json

# Step 1: Retrieve credentials

username = [Link]("API_USERNAME", "Variable not found")
password = [Link]("API_PASSWORD", "Variable not found")

if "Variable not found" in (username, password):

raise Exception("[ERROR] Missing API credentials in environment
variables")

# Step 2: Prepare login request

login_url = "[Link]

login_payload = {
"type": "password",
"username": username,
"password": password
}

login_headers = {
"Content-Type": "application/json"
}

# Step 3: Send login request

login_response = [Link](login_url, headers=login_headers,
json=login_payload)

if login_response.status_code != 200:
raise Exception(f"[ERROR] Login failed: HTTP
{login_response.status_code}")

login_data = login_response.json()

92
bearer_token = login_data.get("authToken")

if not bearer_token:
raise Exception("[ERROR] Failed to retrieve bearer token")

# Step 4: Prepare snapshot request

snapshot_url =
"[Link]

snapshot_payload = {
"assetId": 30,
"timeRange": {
"from": "1970-01-01T[Link]Z",
"to": "2025-08-13T[Link]Z"
}
}

snapshot_headers = {
'Authorization': f'Bearer {bearer_token}',
'Content-Type': 'application/json'
}

# Step 5: Send snapshot request

print("[DEBUG] Sending POST request to snapshot endpoint...")
response = [Link](snapshot_url, headers=snapshot_headers,
json=snapshot_payload)

if response.status_code != 200:
raise Exception(f"[ERROR] Snapshot request failed: HTTP
{response.status_code}")

data = [Link]()

# Step 6: Extract protocol IDs

protocol_counts = [Link]("view", {}).get("protocolCounts", [])
protocol_ids = [item["protocolId"] for item in protocol_counts]
print(f"Protocol IDs found {protocol_ids}")

Troubleshooting Common Response codes

Response Common issues

Codes

400
Bad Request: URL String Syntax Error. Possible illegal character.

Check the URL and request syntax and parameters. Check that all required

93
401 Unauthorized - Authentication is required and has failed or is missing. Verify the API key and secret are
correct and encoded properly. If using Oauth2, verify token is not expired. Verify user has been granted a
role with the permissions required to perform the operation.

403 Forbidden Check permissions to access this resource. Authentication was successful but authorization
failed.

404
Check the URL

PreviousNext

94
3.3.9. Maintenance and Support

Support for integrations should begin with Dragos Customer Portal or Dragos Partner Portal,
where integrators can access documentation, request assistance, and explore product updates.

PreviousNext

95
3.3.10. Appendices

Appendix A - API Endpoints referenced in this guide

API Endpoints referenced in this guide

• /api/v2/auth/login
• /assets/api/v4/createAssetCommunicationsSnapshot

96
3.4. Retrieving Hardware Vulnerability Detections by Asset
· Overview

· Use Cases

· Requirements

· Pre-Development Checklist

· Configuration Guidance

· Integration Considerations

· Scenarios

· Testing and Validation

· Maintenance and Support

· Appendices

97
3.4.1. Overview

This document is intended to provide guidance on pulling Hardware & Firmware Vulnerabilities
Detection information by Asset from the Dragos Platform. Vulnerabilities Detection information
can be retrieved from a Dragos SiteStore in a variety of ways. This guide covers retrieving a
count of Vulnerabilities Detected for a Hardware Asset and a list of all Vulnerability Detections
for a Hardware Asset.

98
3.4.2. Use Cases

1. Vulnerability Management and Remediation

Use Case: Identify and fix vulnerabilities before they are exploited.
How It Helps: Supports awareness for patching or configuration changes to address
known CVEs (Common Vulnerabilities and Exposures) on the device.
2. Risk Assessment and Prioritization
Use Case: Focus resources on the most critical risks.
How It Helps: Devices with high-severity or exploitable vulnerabilities can be prioritized for
remediation or isolation.
3. Threat Modeling and Attack Surface Reduction
Use Case: Understand potential attack paths and reduce exposure.
How It Helps: Knowing vulnerabilities helps map how an attacker might compromise the
device and move laterally.
4. Patch Management Automation
Use Case: Streamline and automate patch deployment.
How It Helps: Integrate with patch management tools to support identifying assets that are
potentially at risk.
5. Security Posture Monitoring
Use Case: Continuously assess the security health of devices.
How It Helps: Tracks vulnerability trends over time to measure improvement or detect
regression.
6. Incident Response and Forensics
Use Case: Investigate how a breach occurred.
How It Helps: Understand what assets have vulnerabilities that could be part of a pivot
path on your network for an attacker.
7. Access Control and Network Segmentation
Use Case: Restrict access for high-risk devices.
How It Helps: Devices with unpatched critical vulnerabilities can be segmented or have
limited access until remediated.

99
8. Threat Intelligence Correlation
Use Case: Match vulnerabilities with active exploits in the wild.
How It Helps: Prioritizes vulnerabilities that have been identified in your environment.

PreviousNext

100
3.4.3. Requirements

System Requirements
1. Dragos Platform 3.x

2. SiteStore API v2

Network Requirements
1. TCP/IP connection between the API client and Dragos Platform SiteStore (normally
tcp/443)

PreviousNext

101
3.4.4. Pre-Development Checklist

API Usage

The SiteStore API documentation can be found at SiteStore API v2. The OpenAPI spec is also
available at [Link]

This guide will cover the use of the /api/v2/assets and /api/v1/vulnerabilities endpoints. To view
all details about this endpoint please refer to the API documentation linked above.

Authentication

API access requires either an API key or an OAuth 2.0 Bearer Access Token in JWT format.

OAuth2 Bearer tokens are recommended because they are dynamic, have an expiration period,
and can be refreshed, whereas API keys remain static and do not expire.

Authorization

The user account(s) for API access should be assigned to a role which provides least privilege
access. To read vulnerability data for this use case, the API user should be assigned a role for
which asset:read and vulnerability:read access has been granted.

SSL

102
PreviousNext

103
3.4.5. Configuration Guidance

Permissions

A detailed description of available Permissions, user and role management can be found in the Dragos Platform
Admin Guide.

PreviousNext

104
3.4.6. Integration Considerations

Rate Limitations

SiteStore API Version 2.0 and earlier do not include API rate limiting. As a result, a high
volumes of requests may lead to performance issues on the Dragos Platform SiteStore.

Pagination

The SiteStore v1 API returns a x-has-next-page header in the response. If true, iterate through
each page of data until all items are collected.

The SiteStore v2 API returns a meta object with the metadata about pagination.

JSON

{
"meta": {
"pageNumber": <The current page of results being returned>,
"pageSize": <The number of items included per page>,
"totalItems": <The total number of items available across all pages>
}
}

To ensure you retrieve all available results, use these values to iterate through each page of
data until all items are collected.

PreviousNext

105
3.4.7. Scenarios

Scenario 1: Retrieve Vulnerability Detection Counts by

Hardware Asset

If you know the Dragos Asset ID, The Get Asset by ID endpoint /api/v2/assets/{id} is used with
the vulnerabilityCounts expand to retrieve all total Vulnerability Detection counts in JSON
format.

GET Request Sample

GET /api/v2/assets/3603?expand=vulnerabilityCounts

Request Headers

Authorization: …

Response Headers

content-type: application/json

Response

The response contains a vulnerabilityCounts object with the a total key value of 10, as seen in
JSON response below..

JSON

{
"id":"3603",
"name":"Asset 3603",
"type":"PLC",
"class":"Controller",
"zone": {
"id":"1",

106
"expansion":"reference"
},
"hardware": {
"family":"MicroLogix",
"firmware":"14.002",
"model":"1763-L16AWA",
"serial":"9CA0A950",
"series":"1100",
"vendor":"Rockwell Automation"
},
"tags": [
"OT"
],
"addresses": [
{"id":"8482",
"expansion":"reference"
},
{
"id":"8488",
"expansion":"reference"
}
],
"connectedAssets": [
],
"vulnerabilityCounts": {
"total":10,
"critical":3,
"high":7,
"medium":0,
"low":0
},
"baselines": [
],
"connectedRootDevice":false,
"firstObservedTime":"2025-07-16T[Link].136Z",
"lastObservedTime":"2025-08-08T[Link].923Z",
"ot":true,
"monitored":true,
"vlan":96,
"labels": {
"zone_name":"RFC1918",
"ObservedBy": [
"vispair02ns100sensor"
],
"Monitored-OT":"true",
"enip_device_type":"Communications Adapter",
"[Link]":3,
"LastReconciledTime":"2025-08-08T[Link].123904245Z",
"AttributesLastObservedDate":"2025-07-29"
}
}

107
Scenario 2: Retrieve Vulnerability Detection Details by Asset

If you know the Dragos Asset ID, it can be used to retrieve Vulnerability Detection details in
JSON format by adding the Asset ID in the

To retrieve the Vulnerability Detection details for a Hardware Asset, the Get Vulnerabilities
endpoint /api/v1/vulnerabilities is used with the the X-Query HTTP header containing the Asset
ID number

x-query: [Link] eq '3603'

GET Request Sample

GET /api/v1/vulnerabilities

Request Headers

Authorization: ...
X-Query: [Link] eq "3603"

Response Headers

The HTTP Response Header response header x-total-count: 10 matches the

"vulnerabilityCounts": {"total":10,...} value from Scenario 1. The x-has-next-page: false header
indicates no further records are part of the result set.

content-type: application/json
x-total-count: 10
x-total-count-exceeded-limit: false
x-total-pages: 1
x-has-next-page: false

Response

108
JSON

[
{
"value": {
"id": "70cbaea4-513f-77a5-6f7e-503439f18ce7",
"report": {
"type": "vulnerabilityReport",
"id": "dragos-advisory-2457",
"expandedState": "skipped"
},
"reasons": [
{
"type": "Hardware",
"criteria": [
"Rockwell Automation, MicroLogix, 1100, 1763-L16AWA,
*"
],
"host": "Rockwell Automation, MicroLogix, 1100, 1763-
L16AWA, 14.002"
}
],
"confidence": 3,
"risk": "Medium",
"priority": "Next",
"disposition": "Not Set",
"firstObservedTime": "2025-07-29T[Link].437Z",
"lastObservedTime": "2025-08-08T[Link].598Z",
"asset": {
"type": "asset",
"id": "3603",
"expandedState": "skipped"
}
}
},
...
}
]

Vulnerability Report details can be displayed by adding the expand parameter report

GET Request Sample

GET /api/v1/vulnerabilities?expand=report

109
Request Headers

Authorization: ...
X-Query: [Link] eq "3603"

Response Headers

content-type: application/json
x-total-count: 10
x-total-count-exceeded-limit: false
x-total-pages: 1
x-has-next-page: false

Response

JSON

[
{
"value": {
"id": "70cbaea4-513f-77a5-6f7e-503439f18ce7",
"report": {
"type": "vulnerabilityReport",
"id": "dragos-advisory-2457",
"expandedState": "expanded",
"expansionTime": "2025-08-08T[Link].472654807Z",
"expanded": {
"id": "dragos-advisory-2457",
"score": {
"base": 6.5,
"dragos": 7.1
},
"title": "Rockwell Automation MicroLogix",
"description": "Successful exploitation could allow an
unauthenticated and remote adversary that leverages the vulnerable HTTP
headers to disclose information, such as user credentials through
clickjacking attacks.",
"type": "Improper Restriction of Rendered UI Layers or
Frames",
"enumeration": "Advisory",
"severity": "High",
"publishedTime": "2022-07-07T[Link]Z",
"state": "enabled",
"summaryHtml": "Rockwell Automation MicroLogix 1400
and 1100 are Programmable Logic Controllers (PLCs) deployed worldwide and

110
commonly seen in the critical manufacturing industry.",
"mitigationsHtml": [
"Rockwell Automation has not released a patch to
resolve these issues."
],
"playbooksHtml": [
"Restrict access to HTTP (TCP/80)."
],
"links": [
{
"url": "[Link]
[Link]/ics/advisories/ICSA-22-188-01",
"label": "ICSA-22-188-01"
},
{
"url":
"[Link]
",
"label": "<a
href=\"[Link]
135994\" rel=\"noopener noreferrer\" target=\"_blank\" style=\"background-
color:rgb(255, 255, 255);color:rgb(0, 102, 204);\">PN1597</a>"
}
],
"source": {
"name": "Intelligence",
"product": "Vulnerability Database",
"type": "OT Vulnerability",
"vendor": "Dragos",
"version": "1.0"
},
"ports": [
{
"number": 80,
"protocols": [
"tcp",
"HTTP"
],
"status": "open"
}
],
"relatedReports": [
{
"type": "vulnerabilityReport",
"id": "CVE-2022-2179",
"expandedState": "skipped"
}
],
"tags": [
{
"id": "DATA_THEFT",

111
"label": "Data Theft"
},
{
"id": "REMOTELY_EXPLOITABLE",
"label": "Remotely Exploitable"
},
{
"id": "USER_INTERACTION",
"label": "User Interaction"
}
]
}
},
"reasons": [
{
"type": "Hardware",
"criteria": [
"Rockwell Automation, MicroLogix, 1100, 1763-L16AWA,
*"
],
"host": "Rockwell Automation, MicroLogix, 1100, 1763-
L16AWA, 14.002"
}
],
"confidence": 3,
"risk": "Medium",
"priority": "Next",
"disposition": "Not Set",
"firstObservedTime": "2025-07-29T[Link].437Z",
"lastObservedTime": "2025-08-08T[Link].197Z",
"asset": {
"type": "asset",
"id": "3603",
"expandedState": "skipped"
}
}
},
...
]

112
Scenario 3: Retrieve subset of Vulnerability Detection Details
by Asset

If you need to obtain a subset of the Vulnerability Detections for an Asset, this can be added to
the X-Query header using the Logical expression AND.

In the below example, only the Vulnerability Details with a Priority of 'Now' will be returned for
the given asset.

GET Request Sample

GET /api/v1/vulnerabilities?expand=report

Request Headers

Authorization: ...
Content-Type: application/json
X-Query: [Link] eq '3603' AND priority eq "Now"

Response Headers

content-type: application/json
x-total-count: 2
x-total-count-exceeded-limit: false
x-total-pages: 1
x-has-next-page: false

Response

JSON

[
{
"value": {
"id": "12a31c48-21fc-0d5b-b94a-9949fd37f7f9",
"report": {
"type": "vulnerabilityReport",
"id": "dragos-advisory-1056",

113
"expandedState": "expanded",
"expansionTime": "2025-08-08T[Link].946142579Z",
"expanded": {
"id": "dragos-advisory-1056",
"score": {
"base": 7.1,
"dragos": 7.1
},
"title": "Rockwell Allen-Bradley MicroLogix, SLC 500, and
PLC-5 Fault Generation Vulnerability",
"description": "Successful exploitation could allow an
unauthenticated and remote adversary to cause a DoS condition forcing the PLC
into a fault state. Physical interaction is required to resume normal
operations.",
"type": "Modification of Assumed Immutable Data",
"enumeration": "Advisory",
"severity": "Critical",
"publishedTime": "2014-04-10T[Link]Z",
"state": "enabled",
"summaryHtml": " Rockwell Automation / Allen-
Bradley MicroLogix line are Programmable Logic Controllers (PLC) deployed
worldwide and commonly seen in the agriculture and food, water, chemical, and
critical manufacturing industries.",
"mitigationsHtml": [
"Update firmware to a <a
href=\"[Link]
html\" rel=\"noopener noreferrer\" target=\"_blank\">patched
version</a>:<ul><li>MicroLogix 1100: update to v13.000 or
later.</li><li>MicroLogix 1200: update to v13.000 or
later.</li><li>MicroLogix 1400: update to v14.000 or
later.</li><li>MicroLogix 1500: update to v13.000 or later.</li></ul>"
],
"playbooksHtml": [
"Restrict access to TCP/2222, UDP/2222, TCP/44818,
and UDP/44818. Ensure controllers are not directly internet-facing. For SLC-
500, set status file to STATIC. For PLC-5, enable the Passwords
& Privileges feature."
],
"links": [
{
"url": "[Link]
[Link]/ics/advisories/ICSA-12-342-01B",
"label": "ICSA-12-342-01B"
},
{
"url":
"[Link]
,
"label": "<a
href=\"[Link]
11407\" rel=\"noopener noreferrer\" target=\"_blank\" style=\"color:rgb(0,

114
102, 204);background-color:rgb(255, 255, 255);\">PN744</a>"
}
],
"source": {
"name": "Intelligence",
"product": "Vulnerability Database",
"type": "OT Vulnerability",
"vendor": "Dragos",
"version": "1.0"
},
"ports": [
{
"number": 2222,
"protocols": [
"tcp",
"Ethernet/IP"
],
"status": "open"
},
{
"number": 2222,
"protocols": [
"udp",
"Ethernet/IP (UDP)"
],
"status": "open"
},
{
"number": 44818,
"protocols": [
"tcp",
"Ethernet/IP"
],
"status": "open"
},
{
"number": 44818,
"protocols": [
"udp",
"Ethernet/IP (UDP)"
],
"status": "open"
}
],
"relatedReports": [
{
"type": "vulnerabilityReport",
"id": "CVE-2012-4690",
"expandedState": "skipped"
}
],

115
"tags": [
{
"id": "DOS",
"label": "Denial Of Service"
},
{
"id": "REMOTELY_EXPLOITABLE",
"label": "Remotely Exploitable"
}
]
}
},
"reasons": [
{
"type": "Hardware",
"criteria": [
"Rockwell Automation, MicroLogix, 1100, *",
"Rockwell Automation, MicroLogix, 1100, >=13.000",
"Rockwell Automation, MicroLogix, 1100, *"
],
"host": "Rockwell Automation, MicroLogix, 1100, 1763-
L16AWA, 14.002"
}
],
"confidence": 1,
"risk": "Medium",
"priority": "Now",
"disposition": "Not Set",
"firstObservedTime": "2025-07-29T[Link].437Z",
"lastObservedTime": "2025-08-08T[Link].201Z",
"asset": {
"type": "asset",
"id": "3603",
"expandedState": "skipped"
}
}
},
...
]

No Data Response

This following response indicates that there were no Vulnerability Detections with a Priority of
Now for the Asset.

JSON

116
[]

PreviousNext

117
3.4.8. Testing and Validation

Python Code Sample

This code sample demonstrates the use of the /api/v1/vulnerabilities endpoint with an X-Query
search for a given Asset ID to test the endpoint and verify expected data.

Python

import os
import requests
import json

# Step 1: Retrieve credentials

print("[DEBUG] Retrieving API_USERNAME and API_PASSWORD from environment...")
username = [Link]("API_USERNAME", "Variable not found")
password = [Link]("API_PASSWORD", "Variable not found")

if "Variable not found" in (username, password):

raise Exception("[ERROR] Missing API credentials in environment
variables")

# Step 2: Authenticate and get Bearer Token

login_url = "[Link]
login_payload = {
"type": "password",
"username": username,
"password": password
}

login_headers = {
"Content-Type": "application/json"
}

login_response = [Link](login_url, headers=login_headers,

json=login_payload)

if login_response.status_code != 200:
raise Exception(f"[ERROR] Login failed: HTTP
{login_response.status_code}")

login_data = login_response.json()
bearer_token = login_data.get("authToken")

if not bearer_token:

118
raise Exception("[ERROR] Failed to retrieve bearer token")

# Step 3: Prepare vulnerability request

assetID = 2374
url =
"[Link]
headers = {
'Authorization': f'Bearer {bearer_token}',
'Content-Type': 'application/json',
'X-Query': f'[Link] eq "{assetID}"'
}
response = [Link](url, headers=headers)

if response.status_code != 200:
raise Exception(f"[ERROR] Vulnerability request failed: HTTP
{response.status_code}")

data = [Link]()

# Step 4: Parse and display results

print(f"\nFor asset ID {assetID}, we found:")

if not data:
print("No Vulnerability Detections")
else:
for item in data:
value = [Link]("value", {})
id_value = [Link]("id", "N/A")
reasons = [Link]("reasons", [])

criteria_list = []
for reason in reasons:
criteria = [Link]("criteria", [])
criteria_list.extend(criteria)

print(f"ID: {id_value}")
print(f"Criteria: {', '.join(criteria_list) if criteria_list else
'None'}")
print("-" * 40)

Troubleshooting Common Response codes

Response Common issues

Codes

400
Bad Request: URL String Syntax Error. Possible illegal character.

119
Check the URL and request syntax and parameters.

401 Unauthorized - Authentication is required and has failed or is missing. Verify the API key and secret are
correct and encoded properly. If using Oauth2, verify token is not expired. Verify user has been granted a role
with the permissions required to perform the operation.

403 Forbidden Check permissions to access this resource. Authentication was successful but authorization failed.

404
Check the URL

PreviousNext

120
3.4.9. Maintenance and Support

Support for integrations should begin with Dragos Customer Portal or Dragos Partner Portal,
where integrators can access documentation, request assistance, and explore product updates.

PreviousNext

121
3.4.10. Appendices

Appendix A - API Endpoints referenced in this guide

API Endpoints referenced in this guide

· /api/v2/auth/login

· /api/v2/assets

· /api/v1/vulnerabilities

Appendix B - X-Query Examples for Common Filters

Attribute Example

[Link] eq "Critical"
Severity

Critical, High, Medium, Low, None

priority eq "Now"
Priority

Never, Next, Now

risk eq "High"
Risk

High, Medium, Low

confidence gte 3
Confidence

1 - Low 2- Medium 3- High

Hardware Vendor [Link] eq "Emerson"

122
4. Notifications
· Retrieving Notifications

123
4.1. Retrieving Notifications
· Overview

· Use Cases

· Requirements

· Pre-Development Checklist

· Configuration Guidance

· Integration Considerations

· Scenarios

· Testing and Validation

· Maintenance and Support

· Appendices

124
4.1.1. Overview

This document is intended to provide guidance on pulling Notification Information from the
Dragos Platform. This guide covers retrieving all Notifications, retrieving Notifications by
Severity, and Searching Notifications using Complex Queries . Additional Notification use cases,
such as the forwarding of Notifications, may be by utilizing the syslog integration functionality of
Dragos SiteStore . For further details, please refer to the Dragos Platform Syslog Integration
guide available from the Dragos Customer Portal.

125
4.1.2. Use Cases

1. Threat Containment and Incident Response

126
How It Helps: Repeated atomic threat detections or threat patterns on a device can
indicate advanced persistent threats (APTs) or insider threats.
8. Device Reputation and Trust Scoring
Use Case: Determine if a device should be trusted on the network.
How It Helps: Devices with a history of threats may be flagged as high-risk and subject to
stricter access controls or monitoring.

PreviousNext

127
4.1.3. Requirements

System Requirements
1. Dragos Platform 3.x

2. SiteStore API v2

Network Requirements

TCP/IP connection between the API client and Dragos Platform SiteStore (normally tcp/443)

PreviousNext

128
4.1.4. Pre-Development Checklist

API Usage

The SiteStore API documentation can be found at SiteStore API v2. The OpenAPI spec is also
available at [Link]

This guide will cover the use of the following endpoints:

· List notifications /api/v2/notifications

· Search notifications with complex queries /api/v2/notifications/search

To view all details about this endpoint please refer to the API documentation linked above.

Authentication

API access requires either an API key or an OAuth 2.0 Bearer Access Token in JWT format.

OAuth2 Bearer tokens are recommended because they are dynamic, have an expiration period,
and can be refreshed, whereas API keys remain static and do not expire.

Authorization

The identities for API access should be assigned to a role which provides least privilege access.
To read notification data for this use case, must be be assigned a role for which at
least notification:read access has been granted. To include asset expand, at least asset:read
must also be granted

129
SSL

PreviousNext

130
4.1.5. Configuration Guidance

Permissions

A detailed description of available Permissions, user and role management can be found in the Dragos Platform
Admin Guide.

PreviousNext

131
4.1.6. Integration Considerations

Rate Limitations

The SiteStore v2 API 2.0 and earlier do not include API rate limiting. As a result, a high volumes
of requests may lead to performance issues on the Dragos Platform SiteStore.

Pagination

The SiteStore v2 API returns a meta object with the metadata about pagination.

JSON

{
"meta": {
"pageNumber": <The current page of results being returned>,
"pageSize": <The number of items included per page>,
"totalItems": <The total number of items available across all pages>
}
}

To ensure you retrieve all available results, use these values to iterate through each page of
data until all items are collected.

Idempotency

Idempotency is critical when ingesting Notifications to ensure that the same alert is not
processed multiple times, which can lead to unnecessary noise in your system. When
processing notifications, you can use the Notification id to enforce implement logic.

A Notification Status may change from unread to read, ("reviewed": false to "reviewed": true). If
the Notification exists in your system, it would likely need to be updated instead of creating a
new Notification.

132
Time-bounding

When retrieving notifications, it can be helpful to apply time constraints to your queries,
especially since the total volume of notifications may be quite large. We suggest using the
firstObservedTime and lastObservedTime fields to filter notifications within a specific date and
time range. This approach can make it easier to monitor for new or updated notifications and
helps ensure that the amount of data returned is manageable.

PreviousNext

133
4.1.7. Scenarios

· Scenario 1: Get all Notifications

· Scenario 2: Get Notification Information by Severity

· Scenario 3: Search Notifications with Complex Queries

Scenarios

Scenario 1: Get all Notifications

The List Notifications endpoint /api/v2/notifications allows retrieval of all Notifications.

GET Request Sample

GET /api/v2/notifications
Authorization: …

Request Headers

Authorization: …

Response Headers

HTTP/2 200
content-type: application/json

Response

The meta object contains the pagination metadata and the content array contains the individual
Notifications.

JSON

{
"meta": {

134
"pageNumber": 1,
"pageSize": 50,
"totalItems": 4493
},
"content": [{
"id": "1",
"source": "Network Traffic",
"reviewed": false,
"state": "Unresolved",
"retained": false,
"type": "Indicator",
"severity": 0,
"summary": "Asset Characterization Debian Linux",
"content": "Asset Characterization Debian Linux",
"updatedAt": "2025-08-12T[Link]Z",
"endpoints": [{
"asset": {
"id": "8401",
"expansion": "reference"
},
"roles": [
"Destination"
]
}, {
"asset": {
"id": "3383",
"expansion": "reference"
},
"roles": [
"Source"
]
}
],
"detection": {
"id": "af7e2302-3d8a-48a0-acb8-fb949277991d",
"expansion": "expanded",
"detectionQuads": [
"Indicator"
],
"threatInfo": [],
"intelReports": [
"None"
]
},
"firstSeenAt": "2025-08-12T[Link]Z",
"lastSeenAt": "2025-08-12T[Link]Z",
"count": 3262
},
...
]
}

135
Scenario 2: Get Notification Information by Severity

The List Notifications endpoint allows retrieval of Notifications by a specific severity or a severity
range, along with a variety of other filters.

The filter query parameter to search for Notifications with Severity greater than 3 would be as
follows:

filter: severity gte 3

GET Request Sample

GET /api/v2/notifications?filter=severity%20gte%203
Authorization: …

Request Headers

Authorization: …

Response Headers

HTTP/2 200
content-type: application/json

Response

The application of the severity filter has reduced the result set to just 27 Notifications from the
4493 Notifications retrieved in Scenario 1.

JSON

136
{
"meta": {
"pageNumber": 1,
"pageSize": 50,
"totalItems": 27
},
"content": [
{
"id": "564",
"source": "Network Traffic",
"reviewed": false,
"state": "Unresolved",
"type": "Communication",
"severity": 3,
"summary": "RDP Negotiation Response non-Standard Port in Use",
"content": "Source host 5462 with IP address [Link] responded to
an RDP connection request from destination host 5463 using IP address
[Link]. The destination host initiated the request to port 54321, which
is non-standard for RDP (typically using port 3389). Attackers often use non-
standard ports for RDP to evade detection by security tools, obfuscate the
usage of RDP, or bypass firewall rules.",
"updatedAt": "2025-08-05T[Link]Z",
"endpoints": [
{
"asset": {
"id": "5462",
"expansion": "reference"
},
"roles": [
"Source"
]
},
{
"asset": {
"id": "5463",
"expansion": "reference"
},
"roles": [
"Destination"
]
}
],
"detection": {
"id": "5fb41ff3-126f-422d-b76a-b6f0f0da90ef",
"expansion": "expanded",
"detectionQuads": [
"Indicator"
],
"threatInfo": [
{
"framework": "MITRE ATT&CK FOR ICS",

137
"tactic": {
"id": "TA0008",
"name": "Lateral Movement",
"reference": "[Link]
}
}
],
"intelReports": [
"N/A"
]
},
"firstSeenAt": "2025-08-05T[Link]Z",
"lastSeenAt": "2025-08-05T[Link]Z",
"count": 1

},
...
]
}

Application of a time-based filter is done in the filter query parameter by adding a selector such
as firstObservedTime.

Choosing the selectors and combinations help refine your search.

1. To find “new” alerts, one may choose the use of firstObservedTime greater than or equal
to 1 day from the current timestamp: firstObservedTime gte -1h

2. To find alerts for events still occurring, one may choose lastObservedTime greater than
or equal to 1 day from the current timestamp: lastObservedTime gte -1h

3. To find that started recently and are still active, combine both
selectors: firstObservedTime gte -1h AND lastObservedTime gte -1h

In the below example severity and upper and lower time boundaries are supplied for further
refinement.

filter: severity gte 3 AND (firstObservedTime gte -1h AND lastObservedTime gte -1h)

GET Request Sample

138
GET
/api/v2/notifications?filter=severity%20gte%203%20AND%20(firstObservedTime%20gte%20-
1h%20AND%20lastObservedTime%20gte%20-1h)

Request Headers

Authorization: ....

Response Headers

HTTP/2 200
content-type: application/json

Response

The totalItems count has been reduced from 27 to 3 by specifying the date and time range filter.

JSON

{
"meta": {
"pageNumber": 1,
"pageSize": 50,
"totalItems": 3
},
"content": [
{
"id": "7346",
"source": "",
"reviewed": false,
"state": "Unresolved",
"type": "Communication",
"severity": 3,
"summary": "Cobalt Strike Behaviors",
"content": "Multiple Cobalt Strike behaviors from host
[Link] (asset 7092). ['HTTP GET with Encoded Cookie - Possible Cobalt
Strike C2', 'HTTP POST with Encoded Payload - Possible Cobalt Strike C2', 'ET
MALWARE Cobalt Strike Beacon Observed', 'Cobalt Strike User-Agent + Cookie
M2']",
"updatedAt": "2025-08-07T[Link]Z",
"endpoints": [
{
"asset": {

139
"id": "7092",
"expansion": "reference"
},
"roles": [
"Source"
]
},
{
"asset": {
"id": "7488",
"expansion": "reference"
},
"roles": [
"Destination"
]
}
],
"detection": {
"id": "b8a0465f-9f50-4c90-ba00-ad6dbde85070",
"expansion": "expanded",
"detectionQuads": [
"Threat Behavior"
],
"threatInfo": [
{
"framework": "MITRE ATT&CK FOR ICS",
"tactic": {
"id": "TA0011",
"name": "Command and Control",
"reference":
"[Link]
},
"technique": {
"id": "T0869",
"name": "Standard Application Layer Protocol",
"reference":
"[Link]
}
}
],
"intelReports": [
"TR-2019-14"
]
},
"firstSeenAt": "2025-08-07T[Link]Z",
"lastSeenAt": "2025-08-07T[Link]Z",
"count": 1
},
{
"id": "7347",
"source": "",

140
"reviewed": false,
"state": "Unresolved",
"type": "Communication",
"severity": 3,
"summary": "Cobalt Strike Behaviors",
"content": "Multiple Cobalt Strike behaviors from host
[Link] (asset 7093). ['HTTP GET with Encoded Cookie - Possible Cobalt
Strike C2', 'HTTP POST with Encoded Payload - Possible Cobalt Strike C2',
'HTTP POST to IP with Fake Browser', 'Cobalt Strike User-Agent + Cookie
M2']",
"updatedAt": "2025-08-07T[Link]Z",
"endpoints": [
{
"asset": {
"id": "7488",
"expansion": "reference"
},
"roles": [
"Destination"
]
},
{
"asset": {
"id": "7093",
"expansion": "reference"
},
"roles": [
"Source"
]
}
],
"detection": {
"id": "b8a0465f-9f50-4c90-ba00-ad6dbde85070",
"expansion": "expanded",
"detectionQuads": [
"Threat Behavior"
],
"threatInfo": [
{
"framework": "MITRE ATT&CK FOR ICS",
"tactic": {
"id": "TA0011",
"name": "Command and Control",
"reference":
"[Link]
},
"technique": {
"id": "T0869",
"name": "Standard Application Layer Protocol",
"reference":
"[Link]

141
}
}
],
"intelReports": [
"TR-2019-14"
]
},
"firstSeenAt": "2025-08-07T[Link]Z",
"lastSeenAt": "2025-08-07T[Link]Z",
"count": 1
},
{
"id": "7348",
"source": "",
"reviewed": false,
"state": "Unresolved",
"type": "Communication",
"severity": 3,
"summary": "Cobalt Strike Behaviors",
"content": "Multiple Cobalt Strike behaviors from host [Link]
(asset 6738). ['HTTP GET with Encoded Cookie - Possible Cobalt Strike C2',
'HTTP POST with Encoded Payload - Possible Cobalt Strike C2', 'ET MALWARE
Cobalt Strike Beacon Observed', 'Cobalt Strike User-Agent + Cookie M2']",
"updatedAt": "2025-08-07T[Link]Z",
"endpoints": [
{
"asset": {
"id": "7488",
"expansion": "reference"
},
"roles": [
"Destination"
]
},
{
"asset": {
"id": "6738",
"expansion": "reference"
},
"roles": [
"Source"
]
}
],
"detection": {
"id": "b8a0465f-9f50-4c90-ba00-ad6dbde85070",
"expansion": "expanded",
"detectionQuads": [
"Threat Behavior"
],
"threatInfo": [

142
{
"framework": "MITRE ATT&CK FOR ICS",
"tactic": {
"id": "TA0011",
"name": "Command and Control",
"reference":
"[Link]
},
"technique": {
"id": "T0869",
"name": "Standard Application Layer Protocol",
"reference":
"[Link]
}
}
],
"intelReports": [
"TR-2019-14"
]
},
"firstSeenAt": "2025-08-07T[Link]Z",
"lastSeenAt": "2025-08-07T[Link]Z",
"count": 1
}
]
}

Scenario 3: Search Notifications with Complex Queries

Complex, multi-field queries, including the ability to build nested logical conditions are possible
using the /api/v2/notifications/search endpoint.
The following example is a query for Baseline Deviation Detected Notifications for assets
assigned to either Zone "Plant 1" or "Plant 2."

POST Request Sample

POST /api/v2/notifications/search

"filter": {

143
"allOf": [{

"fields": {

"type": {

"values": [ "Baseline" ]

"type": "exact"

}, {

"anyOf": [{

"fields": {

"[Link]": {

"type": "exact",

"values": ["3"]

}, {

"fields": {

"[Link]": {

"type": "exact",

"values": ["4"]

144
]

"fields": "id,severity,[Link]",

"expand": "[Link]",

"sort": "severity desc",

"pageSize": 25,

"pageNumber": 1

Request Headers

Content-Type: application/json
Authorization: ...

Response Headers

HTTP/2 200
content-type: application/json

Response

JSON

{
"meta": {
"pageNumber": 1,
"pageSize": 50,
"totalItems": 203
},
"content": [
{
"id": "6890",
"source": "3561eeb8-0e8d-44dd-8748-abf6a475d70d",
"reviewed": false,
"state": "Unresolved",
"retained": false,

145
"type": "Baseline",
"severity": 2,
"summary": "Baseline Deviation Detected",
"content": "Asset 178 violated baseline 'Test Baseline' with
Asset 504 over POP3 [[Link] <-(POP3)- [Link]]",
"updatedAt": "2025-08-12T[Link]Z",
"endpoints": [
{
"asset": {
"id": "178",
"expansion": "expanded",
"name": "Asset 178",
"addresses": [
{
"id": "304",
"expansion": "reference"
},
{
"id": "305",
"expansion": "reference"
}
],
"connectedRootDevice": false,
"firstObservedTime": "2025-08-12T[Link].377Z",
"lastObservedTime": "2025-08-12T[Link].496Z",
"monitored": true,
"labels": {
"zone_name": "Plant 1",
"LastReconciledTime": "2025-08-
12T[Link].837889269Z",
"AttributesLastObservedDate": "2025-08-12"
}
},
"roles": [
"Destination"
]
},
{
"asset": {
"id": "504",
"expansion": "expanded",
"name": "Asset 504",
"type": "Server",
"class": "Enterprise Management",
"purdueLevel": 4,
"tags": [
"Enterprise Management",
"Server"
],
"addresses": [
{

146
"id": "909",
"expansion": "reference"
},
{
"id": "5309",
"expansion": "reference"
},
{
"id": "8428",
"expansion": "reference"
}
],
"connectedRootDevice": false,
"firstObservedTime": "2025-08-12T[Link].746Z",
"lastObservedTime": "2025-08-12T[Link]Z",
"ot": false,
"monitored": true,
"vlan": 212,
"labels": {
"zone_name": "RFC1918",
"LastReconciledTime": "2025-08-
12T[Link].873796130Z",
"SMB Browser Comment": "",
"AttributesLastObservedDate": "2025-08-12"
}
},
"roles": [
"Source"
]
}
],
"parentNotificationId": "6529",
"detection": {
"id": "ee1660cd-ea80-49c6-9f8b-e14a6462d2f9",
"expansion": "expanded",
"detectionQuads": [
"Modeling"
],
"threatInfo": [
{
"framework": "MITRE ATT&CK FOR ICS",
"tactic": {
"name": "N/A"
}
}
],
"intelReports": [
"N/A"
]
},
"firstSeenAt": "2025-08-12T[Link]Z",

147
"lastSeenAt": "2025-08-12T[Link]Z",
"count": 2
},
...
]
}

PreviousNext

148
4.1.8. Testing and Validation

Python Code Sample

Python

import os
import requests
import json
import pandas as pd

# Ignoring warnings related to self-signed certificates on test environments

import warnings
[Link]("ignore")

basicauth = [Link]("API_BASE64_CREDENTIALS", "Variable not found")

url = "[Link]

# Define query parameters

severity = 3
occurred_start = "2025-06-10T[Link]Z"
occurred_end = "2025-06-11T[Link]Z"
last_seen_start = "2025-06-10T[Link]Z"
last_seen_end = "2025-06-11T[Link]Z"
page_number = 1
page_size = 100

filter_query = (
f"severity=ge={severity};"
f"((occurredAt=ge='{occurred_start}';occurredAt=le='{occurred_end}'));"
f"((lastSeenAt=ge='{last_seen_start}';lastSeenAt=le='{last_seen_end}'))"
)

# Define query parameters

params = {
"filter": filter_query,
"pageNumber": page_number,
"pageSize": page_size
}

headers = {
'Authorization': f'Basic {basicauth}',
'Content-Type': 'application/json'
}

response = [Link](url, headers=headers, params=params, verify=False)

data = [Link]([Link])

149
# Extract Detains if content exists
if "content" in data and data["content"]:
parsed_data = [
{
"Type": content_item.get("type", "N/A"),
"Notification ID": content_item.get("id", "N/A"),
"Summary": content_item.get("summary", "N/A"),
"Severity": content_item.get("severity", "N/A"),
"State": content_item.get("state", "N/A"),
"Last Seen At": content_item.get("lastSeenAt", "N/A"),
"Host Name":
content_item["assets"][0]["attributes"].get("[Link]", "N/A")
if "assets" in content_item and content_item["assets"] else "N/A"
}
for content_item in data["content"] # Iterate correctly over each
item in content
]

# Convert to DataFrame and display table

df = [Link](parsed_data)
print(df)

Troubleshooting Common Response codes

Response Common issues

Codes

400
Bad Request: URL String Syntax Error. Possible illegal character.

Check the URL and request syntax and parameters.

401 Unauthorized - Authentication is required and has failed or is missing. Verify the API key and secret are
correct and encoded properly. If using Oauth2, verify token is not expired. Verify user has been granted a role
with the permissions required to perform the operation.

403 Forbidden Check permissions to access this resource. Authentication was successful but authorization failed.

404
Check the URL

150
PreviousNext

151
4.1.9. Maintenance and Support

Support for integrations should begin with Dragos Customer Portal or Dragos Partner Portal,
where integrators can access documentation, request assistance, and explore product updates.

PreviousNext

152
4.1.10. Appendices

Appendix A - API Endpoints referenced in this guide

· /api/v2/auth/login

· /api/v2/notifications

· /api/v2/notifications/search

Appendix B - Notification Types

1. Analytic

2. Anomaly

3. Asset

4. Baseline

5. Communication

6. Detection

7. Failure

8. Indicator

9. Network

10. System

153
5. Vulnerabilities
· Retrieving Vulnerability Detections

154
5.1. Retrieving Vulnerability Detections
· Overview

· Use Cases

· Requirements

· Pre-Development Checklist

· Configuration Guidance

· Integration Considerations

· Scenarios

· Testing and Validation

· Maintenance and Support

· Appendices

155
5.1.1. Overview

This document is intended to provide guidance on pulling Vulnerability Detection information

from the Dragos Platform. This guide covers retrieving all Vulnerabilities Detections,
Vulnerabilities Detections by Priority, and time bound Vulnerabilities Detections by Priority.

PreviousNext

156
5.1.2. Use Cases

1. Vulnerability Management and Remediation

157
8. Threat Intelligence Correlation
Use Case: Match vulnerabilities with active exploits in the wild.
How It Helps: Prioritizes vulnerabilities that have been identified in your environment.

PreviousNext

158
5.1.3. Requirements

System Requirements
1. Dragos Platform 3.x

2. SiteStore API v2

Network Requirements

TCP/IP connection between the API client and Dragos Platform SiteStore (normally tcp/443)

PreviousNext

159
5.1.4. Pre-Development Checklist

API Usage

The SiteStore API documentation can be found at SiteStore API v2. The OpenAPI spec is also
available at [Link]

This guide will cover the use of the api/v1/vulnerabilities endpoint for Vulnerability Detections for
Hardware and Firmware Assets and api/v2/vulnerabilities for Vulnerability Detections for
Software and Operating Systems. To view all details about these endpoints please refer to the
OpenAPI specs are available at [Link]
and [Link]

Vulnerability Detections for all Asset classes will be available from a common endpoint using
the SiteStore AP1 V2 in a future release.

Authentication

API access requires either an API key or an OAuth 2.0 Bearer Access Token in JWT format.

OAuth2 Bearer tokens are recommended because they are dynamic, have an expiration period,
and can be refreshed, whereas API keys remain static and do not expire.

Authorization

The user account(s) for API access should be assigned to a role which provides least privilege
access. To read vulnerability data for this use case, the API user should be assigned a role for
which vulnerability:read access has been granted. To read asset information associated with the

160
vulnerability, asset:read access will be required. To read network information associated with
the vulnerability, network:read access will be required.

SSL

PreviousNext

161
5.1.5. Configuration Guidance

Permissions

A detailed description of available Permissions, user and role management can be found in the Dragos Platform
Admin Guide.

PreviousNext

162
5.1.6. Integration Considerations

Rate Limitations

SiteStore API Version 2.0 and earlier do not include API rate limiting. As a result, a high
volumes of requests may lead to performance issues on the Dragos Platform SiteStore.

Pagination

The SiteStore v1 API uses a x-has-next-page header in the response for handling pagination.
If x-has-next-page: true values to iterate through each page of data until all items are collected.
In SiteStore v1 pageNumber defaults to 1 and pageSize to 10.

The SiteStore v2 API returns a meta object with the metadata about pagination.

JSON

{
"meta": {
"pageNumber": <The current page of results being returned>,
"pageSize": <The number of items included per page>,
"totalItems": <The total number of items available across all pages>
}
}

To ensure you retrieve all available results, use these values to iterate through each page of
data until all items are collected. In SiteStore v2 pageNumber defaults to 1 and pageSize to 50.

PreviousNext

163
5.1.7. Scenarios

Scenario 1: Get all Vulnerability Detection information for

Hardware & Firmware

You can fetch Vulnerability Detections for Hardware & Firmware from the Dragos Platform
using the /api/v1/vulnerabilities endpoint. Expand parameters are available for additional Asset
and Vulnerability Report details, as outlined in the API documentation.

GET Request Sample

GET [Link]
Authorization: …

Request Headers

Authorization: ...
content-type: application/json

Response Headers

content-type: application/json
x-total-count: 426
x-total-pages: 43
x-has-next-page: true

Response

JSON

[
{
"value": {
"id": "7c933f09-4752-16e3-353f-fb00b64b5c00",
"report": {
"type": "vulnerabilityReport",

164
"id": "dragos-advisory-183",
"expandedState": "expanded",
"expansionTime": "2025-07-01T[Link].104634765Z",
"expanded": {
"id": "dragos-advisory-183",
"score": {
"base": 10,
"dragos": 10

},
"title": "Schneider Modicon Vulnerabilities",
"description": "Successful exploitation could allow an
unauthenticated and remote adversary that leverages the vulnerabilities to
access the Ethernet interface and crash or execute code. ",
"enumeration": "Advisory",
"severity": "Critical",
"publishedTime": "2018-03-27T[Link]Z",
"state": "enabled",
"summaryHtml": "Schneider Electric Modicon devices are
Programmable Automation Controllers (PLCs) deployed worldwide and seen across
a variety of industries.",
"mitigationsHtml": [
"Update to a patched version:<ul><li>Modicon
M580 (part numbers BMEP* & BMEH*, excluding M580 CPU Safety): SV4.10 or
later.</li><li>Modicon RTU (BMXNOR0200H): v1.7 IR24 or later.</li><li>Modicon
X80 Ethernet Communication Module (BMXNOC0401): v2.11 or
later.</li></ul> CVE-2018-7242 only:<ul><li>Modicon M340:
v3.50 or later.</li></ul>"

],
"playbooksHtml": [
"Restrict access to (TCP/21) and (TCP/502). If
possible, use deep packet inspection to restrict access to Modbus Function
Code 90 further. Ensure host systems are segmented from the enterprise
network and the internet. "

],
"links": [
{
"url": "[Link]
[Link]/ics/advisories/ICSA-18-086-01",
"label": "ICSA-18-086-01"

},
{
"url": "[Link]
[Link]/en/download/document/SEVD-2018-081-01/",
"label": "<a href=\"[Link]
[Link]/en/download/document/SEVD-2018-081-01/\"
target=\"_blank\">Schneider Advisory SEVD-2018-081-01</a>"

165
}

],
"source": {
"name": "Intelligence",
"product": "Vulnerability Database",
"type": "OT Vulnerability",
"vendor": "Dragos",
"version": "1.0"

},
"ports": [
{
"number": 502,
"protocols": [
"tcp",
"Modbus"

],
"status": "open"

},
{
"number": 21,
"protocols": [
"tcp",
"FTP"

],
"status": "open"

],
"relatedReports": [
{
"type": "vulnerabilityReport",
"id": "CVE-2018-7240",
"expandedState": "skipped"

},
{
"type": "vulnerabilityReport",
"id": "CVE-2018-7241",
"expandedState": "skipped"

},
{
"type": "vulnerabilityReport",
"id": "CVE-2018-7242",
"expandedState": "skipped"

166
},
{
"type": "vulnerabilityReport",
"id": "CVE-2011-4859",
"expandedState": "skipped"

],
"tags": [
{
"id": "CODE_EXECUTION",
"label": "Code Execution"

},
{
"id": "CREDENTIAL_EXPOSURE",
"label": "Credential Exposure"

},
{
"id": "DATA_THEFT",
"label": "Data Theft"

},
{
"id": "DOS",
"label": "Denial Of Service"

},
{
"id": "REMOTELY_EXPLOITABLE",
"label": "Remotely Exploitable"

},
"reasons": [
{
"type": "Hardware",
"criteria": [
"Schneider Electric, Modicon, M580, BMEP581020,
<SV4.10"

],
"host": "Schneider Electric, BMEP581020, 2.50"

167
}

],
"confidence": 3,
"risk": "High",
"priority": "Now",
"disposition": "Not Set",
"firstObservedTime": "2025-06-27T[Link].507Z",
"lastObservedTime": "2025-07-01T[Link].989Z",
"asset": {
"type": "asset",
"id": "179",
"expandedState": "expanded",
"expansionTime": "2025-07-01T[Link].109513566Z",
"expanded": {
"id": "179",
"name": "Asset 179",
"type": "PLC",
"class": "Controller",
"zone": {
"type": "zone",
"id": "1",
"expandedState": "skipped"

},
"tags": [
"OT"

],
"addresses": [
{
"type": "address",
"id": "277",
"expandedState": "skipped"

},
{
"type": "address",
"id": "279",
"expandedState": "skipped"

},
{
"type": "address",
"id": "4767",
"expandedState": "skipped"

168
"connectedRootDevice": false,
"notificationCounts": {
"type": "assetNotificationCounts",
"id": "179",
"expandedState": "skipped"

},
"vulnerabilityCounts": {
"type": "assetVulnerabilityCounts",
"id": "179",
"expandedState": "skipped"

},
"firstObservedTime": "2025-06-27T[Link].617Z",
"lastObservedTime": "2025-07-01T[Link].817Z",
"ot": true,
"baselines": [
],
"hardware": {
"firmware": "2.50",
"model": "BMEP581020",
"vendor": "Schneider Electric"

},
"monitored": true,
"vlan": 24,
"labels": {
"zone_name": "RFC1918",
"ObservedBy": [
"uatpair01ns250sensor"

],
"Monitored-OT": "true",
"Monitored-MAC": "true",
"Monitored-OTPeer": "true",
"Monitored-MACPeer": "true",
"[Link]": 1,
"LastReconciledTime": "2025-07-
01T[Link].566173528Z",
"AttributesLastObservedDate": "2025-06-28"

}
]

169
Scenario 2: Get all Vulnerability Detection information for
Software & OS

You can fetch Vulnerability Detections for Software & OS from the Dragos Platform using the
/api/v2/vulnerabilities endpoint. Expand parameters are added for additional Asset, Software
Package, and Operating System details, as outlined in the API documentation. asset
operatingSystem

GET Request Sample

GET /api/v2/vulnerabilities?expand=asset,softwarePackage,operatingSystem
Authorization: …

Request Headers

Authorization: ...

Response Headers

content-type: application/json

Response

The meta object indicates 74,789 vulnerability detections are available in the result set. An
example of Operating System and Software Package are provided in JSON response below.

JSON

{
"meta": {
"pageNumber": 1,
"pageSize": 50,
"totalItems": 74789
},

170
"content": [
{
"id": "22",
"createdTime": "2025-07-22T[Link].024091Z",
"modifiedTime": "2025-07-22T[Link].024091Z",
"resolution": "Closed",
"title": "Vulnerability 22",
"type": "operatingSystem",
"asset": {
"id": "9555",
"expansion": "expanded",
"name": "Asset 9555",
"type": "Computing Platform",
"class": "Computing Platform",
"stage": "Deployed",
"criticality": 4,
"purdueLevel": 3,
"addresses": [],
"connectedRootDevice": false,
"firstObservedTime": "2025-07-19T[Link].734Z",
"lastObservedTime": "2025-08-13T[Link].132Z",
"ot": true,
"monitored": true,
"labels": {
"zone_name": "RFC1918",
"LastReconciledTime": "2025-08-13T[Link].166850591Z"
}
},
"operatingSystem": {
"id": "57",
"name": "Windows 7",
"expansion": "expanded",
"version": "sp1"
},
"cpe": {
"string": "cpe:2.3:o:microsoft:windows_7:sp1:*:*:*:*:*:x86:*"
},
"cves": [
{
"id": "CVE-2022-41128",
"status": "Analyzed",
"description": "Windows Scripting Languages Remote Code
Execution Vulnerability",
"cvssVersion": "3.1",
"cvssType": "primary",
"cvssBaseScore": 8.8,
"cvssVectorString":
"CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:U/C:H/I:H/A:H",
"cvssExploitabilityScore": 2.8,
"cvssImpactScore": 5.9,
"cvssTemporalScore": 8.8,

171
"cvssTemporalString": "E:H/RL:X/RC:C",
"dragosScore": 8.8,
"publishedTime": "2022-11-09T[Link].453Z"
}
],
"score": 0,
"severity": "None"
},
...
{
"id": "291",
"createdTime": "2025-07-24T[Link].46604Z",
"modifiedTime": "2025-07-24T[Link].46604Z",
"resolution": "Not Set",
"title": "Vulnerability 291",
"type": "softwarePackage",
"asset": {
"id": "6320",
"expansion": "expanded",
"name": "Name 00009",
"type": "IP Phone",
"class": "IoT",
"stage": "Planned",
"criticality": 1,
"tags": [
"TAG-120821931"
],
"addresses": [
{
"id": "12353",
"expansion": "reference"
},
{
"id": "12352",
"expansion": "reference"
},
{
"id": "12354",
"expansion": "reference"
},
{
"id": "12355",
"expansion": "reference"
}
],
"connectedRootDevice": false,
"firstObservedTime": "2025-07-17T[Link]Z",
"lastObservedTime": "2025-07-17T[Link]Z",
"ot": true,
"monitored": true,
"labels": {

172
"Monitored-OT": "true",
"LastReconciledTime": "2025-08-12T[Link].210837807Z",
"AttributesLastObservedDate": "2025-07-17"
}
},
"softwarePackage": {
"id": "153",
"name": "crisp",
"expansion": "expanded",
"version": "0.8",
"vendor": "crisp"
},
"cpe": {
"string": "cpe:2.[Link]risp:crisp:0.8:*:*:*:*:wordpress:*:*"
},
"cves": [
{
"id": "CVE-2021-43353",
"status": "Modified",
"description": "The Crisp Live Chat WordPress plugin is
vulnerable to Cross-Site Request Forgery due to missing nonce validation via
the crisp_plugin_settings_page function found in the ~/[Link] file, which
made it possible for attackers to inject arbitrary web scripts in versions up
to, and including 0.31.",
"cvssVersion": "3.1",
"cvssType": "primary",
"cvssBaseScore": 8.8,
"cvssVectorString":
"CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:U/C:H/I:H/A:H",
"cvssExploitabilityScore": 2.8,
"cvssImpactScore": 5.9,
"cvssTemporalScore": 8,
"cvssTemporalString": "E:U/RL:X/RC:C",
"publishedTime": "2022-01-18T[Link].18Z"
}
],
"score": 0,
"severity": "None"
}
...
]
}

173
Scenario 3: Get all Vulnerability Detection information by
Priority for Hardware & Firmware

To fetch all Vulnerability Detections by Priority, you can refine your search using the X-Query
HTTP header. Example search fields and supported operators are provided in Appendix B.
Logical expressions such as AND and OR can be used for precise filtering.

X-Query: priority eq "Now"

GET Request Sample

GET [Link]
Authorization: …

Request Headers

Authorization: ...
Content-Type: application/json
X-Query: priority eq "Now"

Response Headers

x-total-count: 84

Response

The x-total-count has been reduced from 426 Detections returned in Scenario 1 to a 84
Detections of Priority Now.

JSON

[
{
"value": {

174
"id": "7c933f09-4752-16e3-353f-fb00b64b5c00",
"report": {
"type": "vulnerabilityReport",
"id": "dragos-advisory-183",
"expandedState": "skipped"

},
"reasons": [
{
"type": "Hardware",
"criteria": [
"Schneider Electric, Modicon, M580, BMEP581020,
<SV4.10"

],
"host": "Schneider Electric, BMEP581020, 2.50"

],
"confidence": 3,
"risk": "High",
"priority": "Now",
"disposition": "Not Set",
...
"asset": {
"type": "asset",
"id": "179",
"expandedState": "skipped"

}
]

Scenario 4: Get all Vulnerability Detection information by

Priority for Software & OS

To fetch all Vulnerability Detections by Priority for Software & OS you can refine your search
using the text filter HTTP header.

175
filter: dragosAssessment eq "Now"

GET Request Sample

GET /api/v2/vulnerabilities?filter=dragosAssessment%20eq%20%22Now%22
Authorization: …

Request Headers

Authorization: ...

Response Headers

content-type: application/json

Response

The totalItems displays 2,174 Detections of Priority Now of the 74,789 returned in Scenario 2.

JSON

{
"meta": {
"pageNumber": 1,
"pageSize": 50,
"totalItems": 2174
},
"content": [
{
"id": "276",
"createdTime": "2025-07-22T[Link].660726Z",
"modifiedTime": "2025-07-22T[Link].660726Z",
"resolution": "Closed",
"title": "CredSSP Vulnerability Impacts RDP / PEPPRL+FUCHS",
"type": "operatingSystem",
"asset": {
"id": "9001",
"expansion": "expanded",
"name": "Asset 9001",
"addresses": [
{
"id": "17054",
"expansion": "reference"

176
}
],
"connectedRootDevice": false,
"firstObservedTime": "2025-07-19T[Link].751Z",
"lastObservedTime": "2025-08-09T[Link].401Z",
"monitored": true,
"vlan": 3204,
"labels": {
"zone_name": "Other Network Assets",
"ObservedBy": [
"vispair02ns100sensor"
],
"[Link]": 0,
"LastReconciledTime": "2025-08-13T[Link].867715725Z",
"AttributesLastObservedDate": "2025-07-26"
}
},
"operatingSystem": {
"id": "58",
"name": "windowsserver2008",
"expansion": "expanded",
"version": "r2"
},
"cpe": {
"string":
"cpe:2.3:o:microsoft:windows_server_2008:r2:sp1:*:*:standard:*:x64:*"
},
"cves": [
{
"id": "CVE-2018-0886",
"status": "Modified",
"description": "The Credential Security Support Provider
protocol (CredSSP) in Microsoft Windows Server 2008 SP2 and R2 SP1, Windows 7
SP1, Windows 8.1 and RT 8.1, Windows Server 2012 and R2, Windows 10 Gold,
1511, 1607, 1703, and 1709 Windows Server 2016 and Windows Server, version
1709 allows a remote code execution vulnerability due to how CredSSP
validates request during the authentication process, aka \"CredSSP Remote
Code Execution Vulnerability\".",
"cvssVersion": "2.0",
"cvssType": "primary",
"cvssBaseScore": 7.6,
"cvssVectorString": "AV:N/AC:H/Au:N/C:C/I:C/A:C",
"cvssExploitabilityScore": 0,
"cvssImpactScore": 0,
"cvssTemporalScore": 6.8,
"cvssTemporalString": "E:POC/RL:ND/RC:C",
"dragosScore": 7,
"publishedTime": "2018-03-14T[Link].527Z"
}
],
"advisory": {

177
"id": "dragos-advisory-129",
"title": "CredSSP Vulnerability Impacts RDP / PEPPRL+FUCHS",
"descriptionHtml": "A vulnerability in CredSSP
authentication can allow an attacker to execute commands with a user’s
credentials.",
"type": "Improper Authentication",
"enumeration": "Advisory",
"severity": "Critical",
"baseScore": 7,
"dragosScore": 7,
"publishedTime": "2018-07-17T[Link]Z",
"mitigationsHtml": [
"PEPPERL+FUCHS has produced a set of security patches
which are reported to fix the vulnerabilities. See the advisory for patch
sets which apply to your product. Note that the RDP client systems must also
be updated, or they will fail to connect to the updated product."
],
"playbooksHtml": [
"Monitor the network for suspicious ARP and RDP
activity, such as RDP sessions which abort during handshake. Apply updates to
PEPPERL+FUCHS HMI products and all client systems during the next maintenance
window."
],
"links": [
{
"url": "[Link]
18-198-03",
"label": "ICSA-18-198-03"
},
{
"url": "[Link]
us/security-guidance/advisory/CVE-2018-0886",
"label": "<a
href=\"[Link]
guidance/advisory/CVE-2018-0886\" target=\"_blank\">Microsoft Bulletin for
CVE-2018-0886</a>"
}
],
"ports": [],
"tags": []
},
"score": 7,
"severity": "Critical"
}
...
]
}

178
Scenario 5: Get Timebound Vulnerability Detection information
by Priority for Hardware & Firmware

If you filter Vulnerability Detections by Priority present within the past 24 hours.

GET Request Sample

GET [Link]
Authorization: …

Request Headers

Authorization: ...
Content-Type: application/json
X-Query: priority eq "Now" AND lastObservedTime gte -1d

Response Headers

x-total-count: 24

Response

The x-total-count has been reduced from 84 Detections returned in Scenario 3 to 24 Detections
of Priority Now within the past 24 hours

JSON

[
{
"value": {
"id": "7c933f09-4752-16e3-353f-fb00b64b5c00",
"report": {
"type": "vulnerabilityReport",
"id": "dragos-advisory-183",
...
},
...
"priority": "Now",
...

179
"lastObservedTime": "2025-07-01T[Link].989Z",
...
}
},
...
]

Scenario 6: Get Timebound Vulnerability Detection information

by Priority for Software & OS

To filter Vulnerability Detections by Priority for Software & OS created since a given time.

filter: dragosAssessment eq "Now" AND createdTime gte -1d

GET Request Sample

GET /api/v2/vulnerabilities?filter=createdTime%20gte%202025-08-11T00%3A00%3A00Z
Authorization: …

Request Headers

Authorization: ...

Response Headers

HTTP/2 200
Content-Type: application/json

Response

The totalItems displays 31 Detections of Priority Now created after the specified date, of
the 2,174 returned in Scenario 4.

JSON

180
{
"meta": {
"pageNumber": 1,
"pageSize": 50,
"totalItems": 31
},
"content": [
..
]
}

PreviousNext

181
5.1.8. Testing and Validation

Python Code Sample

The below code sample is using the SiteStore V1 API for Retrieving Hardware Vulnerability
Detections.

Python

import os
import requests
import pandas as pd

# Step 1: Get Bearer Token

username = [Link]("API_USERNAME", "Variable not found")
password = [Link]("API_PASSWORD", "Variable not found")
login_url = "[Link]
login_payload = {
"type": "password",
"username": username,
"password": password
}
login_headers = {
"Content-Type": "application/json"
}

login_response = [Link](login_url, headers=login_headers,

json=login_payload)
login_data = login_response.json()

# Extract token
bearer_token = login_data.get("authToken")
if not bearer_token:
raise Exception("[ERROR] Failed to retrieve bearer token")

# Step 2: Prepare API Request

headers = {
'Authorization': f'Bearer {bearer_token}',
'Content-Type': 'application/json',
'X-Query': 'priority eq "Now" AND lastObservedTime gt -1d'
}
base_url = "[Link]
page_number = 1
page_size = 10
alldata = []

182
while True:
params = {
"pageNumber": page_number,
"pageSize": page_size,
"expand":
"asset,[Link],[Link],report,[Link]"
}

response = [Link](base_url, headers=headers, params=params)

if response.status_code != 200:
print(f"Error fetching page {page_number}: HTTP
{response.status_code}")
break

data = [Link]()
[Link](data)
has_next = [Link]("x-has-next-page", "false").lower()
if has_next == "false":
break
page_number += 1

# Transform raw data into structured rows

rows = []
for idx, item in enumerate(alldata):
val = [Link]("value", {})
reasons = [Link]("reasons", [])
reason_info = reasons[0] if reasons else {}

# Extract related report IDs (e.g., CVEs)

related_reports = []
report = [Link]("report", {})
expanded = [Link]("expanded", {})
related = [Link]("relatedReports", [])
for r in related:
related_id = [Link]("id")
if related_id:
related_reports.append(related_id)

[Link]({
"Report ID": [Link]("id", "N/A"),
"Priority": [Link]("priority", "N/A"),
"Asset ID": [Link]("asset", {}).get("id", "N/A"),
"Related Reports": ", ".join(related_reports)
})

# Create and print formatted table

df = [Link](rows)
print(df)

183
Troubleshooting Common Response codes

Response Common issues

Codes

400
Bad Request: URL String Syntax Error. Possible illegal character.

Check the URL and request syntax and parameters.

401 Unauthorized - Authentication is required and has failed or is missing. Verify the API key and secret are
correct and encoded properly. If using Oauth2, verify token is not expired. Verify user has been granted a role
with the permissions required to perform the operation.

403 Forbidden Check permissions to access this resource. Authentication was successful but authorization failed.

404
Check the URL

PreviousNext

184
5.1.9. Maintenance and Support

Support for integrations should begin with Dragos Customer Portal or Dragos Partner Portal,
where integrators can access documentation, request assistance, and explore product updates.

PreviousNext

185
5.1.10. Appendices

Appendix A - API Endpoints referenced in this guide

· /api/v2/auth/login

· /api/v1/vulnerabilities

· /api/v2/vulnerabilities

186
6. Using Queries and Filters with the Dragos
SiteStore API V2

This document aims to facilitate the development of integrations with the Dragos Platform by
explaining Queries and Filters and how they can be used with the SiteStore V2 API.

The SiteStore V2 API supports two main ways to query and filter data:

· Text Filters are used with for simple queries in GET endpoints.

· Structured Filters are used for complex queries in POST /search endpoints.

Both filter types require knowledge of the Attributes and Operators applicable to the type of
resource being retrieved.

Fieldsets: Understanding Filterable Attributes

A Fieldset defines the schema for a resource, including available fields and their capabilities.
Fieldsets inform the following:
· List of fields for each resource (e.g., host, notification, user)

· Field types (string, number, datetime, etc.)

· Filterable, sortable, and required status

Retrieve Fieldsets

Use the /api/v2/fieldsets endpoint to get available fieldsets:

GET Request Sample

GET /api/v2/fieldsets
Authorization:

Sample Response

187
The available Fieldsets are returned as ids within the content array of the response, as in the
example below.

JSON

"content": [
{ "id": "address", ... },
{ "id": "asset", ... },
{ "id": "assetSoftwarePackage", ... },
{ "id": "zone", ... }
]

Each resource type contains field definitions, such as Baseline field and its acceptable operators
- "Equals" (eq) , "Not Equals" (!eq), "Includes" (in) and "Not Includes" (!in) -as seen in the JSON
below.

JSON

...
"id": "asset",
"fields": [
{
"id": "baseline",
"label": "Baseline",
"valueType": {
"id": "string",
"suggestions": {
"id": "[Link]",
"fieldsetId": "baseline",
"valueField": "id",
"labelFilterHint": {
"field": "name",
"operator": "matches"
}
}
},
"operators": [
{
"id": "eq",
"label": "Equals",
"multiValue": false,
"details": "The field's value must equal this value."
}, {
"id": "!eq",
"label": "Not Equals",

188
"multiValue": false,
"details": "The field's value must not equal this value."

},
{
"id": "in",
"label": "Includes",
"multiValue": true,
"details": "The field's value must be one of these values."
}, {
"id": "!in",
"label": "Not Includes",
"multiValue": true,
"details": "The field's value must not be one of these values."
}
],
"filterable": true,
"sortable": false,
"aliasIds": [
"[Link]"
]
...

]
...

},
{

Text Filters

Text filters use a string-based syntax inspired by SQL WHERE clauses providing a flexible way
to express complex queries over platform resources.

Syntax:: <attribute> <operator> <value/function>

Text Filters are applied to the GET endpoints through the addition of a HTTP Query Parameter.

Example using Asset resource type (List Assets endpoint)

filter: lastObservedTime gte -1h

189
GET Request Sample

GET /api/v2/assets?filter=lastObservedTime%20gte%20-1h
Authorization: …

Logical Combinations

Combine conditions with AND, OR, and parentheses for grouping:

(status = 'active' OR crownJewel = true) AND lastSeenAt > -7d

Ordering

Use order by <attribute> [asc|desc] to sort results

monitored eq true ORDER BY [Link] ASC

Structured Filters (POST /search Endpoints)

Dragos utilizes powerful JSON-based structured filters with the resource POST /search
endpoints. This allows you to build complex, multi-field queries that go far beyond what simple
text filters can do, including the ability to build nested logical conditions within your filter
definitions. This means you can combine multiple filter criteria using logical operators like
ALL_OF (AND), ANY_OF (OR), and NOT, and these can themselves contain other nested
logical groups or selectors.

The SiteStore V2 API contains complex queries for Assets, Notifications, and Vulnerabilities.
Detailed payload examples are available via the OpenAPI specification outlined in the SiteStore
API v2

190
Example Regex Search Assets

The below example case insensitive regex matching is used to query Assets.

POST Request Sample

POST /api/v2/assets/search HTTP/2

{
"filter": {
"fields": {
"[Link]": {
"type": "regex",
"value": "(?i)^rockwell"
}}}
}

Example of Nested Search Assets

The below example searches for Assets based on multiple Hardware Vendors with a Purdue
Level of 1.
ets.

POST Request Sample

POST /api/v2/assets/search HTTP/2

{
"filter": {
"allOf": [{
"allOf": [{"fields": {"purdueLevel": {"op": "eq", "value": 1, "type":
"numberCompare"}}}]
},
{
"anyOf": [{"fields": {"[Link]": {"type": "regex", "value":
"(?i)^rockwell"}}},
{"fields": {"[Link]": {"values": ["Cisco"], "type":
"exact"}}}
]}
]}
}

191
Additional Tips
· Use the suggestions field in the API response to help construct filters.

· Refer to the OpenAPI specification for detailed payload structures.

· Always validate field names and operators using the /api/v2/fieldsets endpoint.

192

Management For Professionals
No ratings yet
Management For Professionals
13 pages
M Waleed Kadous LLMs in Production Learning From Experience 1
No ratings yet
M Waleed Kadous LLMs in Production Learning From Experience 1
51 pages
Illumio App For Splunk 4.0
No ratings yet
Illumio App For Splunk 4.0
47 pages
ETM NG Firewall User Guide
No ratings yet
ETM NG Firewall User Guide
353 pages
V5 FLOOR PLAN EVOKE 220 Sqyds
No ratings yet
V5 FLOOR PLAN EVOKE 220 Sqyds
1 page
V4 FLOOR PLAN EVOKE 180 Sqyds
No ratings yet
V4 FLOOR PLAN EVOKE 180 Sqyds
1 page
V3 150 SQ Yard Villa
No ratings yet
V3 150 SQ Yard Villa
1 page
Windows Intrusion Detection Guide
No ratings yet
Windows Intrusion Detection Guide
4 pages
Networking and Internet Class 11 Notes
No ratings yet
Networking and Internet Class 11 Notes
10 pages
Writing Information Security Policies
100% (1)
Writing Information Security Policies
161 pages
MSC-FAL 1-Circ 3
No ratings yet
MSC-FAL 1-Circ 3
6 pages
Tinder Security Audit SSN Project 2013
No ratings yet
Tinder Security Audit SSN Project 2013
19 pages
Sangfor AI Firewall: Stop Unknown Threats
No ratings yet
Sangfor AI Firewall: Stop Unknown Threats
24 pages
Phase03 Ede Final
No ratings yet
Phase03 Ede Final
52 pages
A Seminar Report On Graphical Password Authentication
No ratings yet
A Seminar Report On Graphical Password Authentication
16 pages
Palo Alto Firewall Essentials
No ratings yet
Palo Alto Firewall Essentials
8 pages
Modern Cryptography For Cybersecurity Professionals 1st Edition by Lisa Bock 1838647791 9781838647797 - The Full Ebook Version Is Just One Click Away
No ratings yet
Modern Cryptography For Cybersecurity Professionals 1st Edition by Lisa Bock 1838647791 9781838647797 - The Full Ebook Version Is Just One Click Away
44 pages
Ethical Perspectives On Hacktivism: The Roles and Actions of Hacker Activist Groups
No ratings yet
Ethical Perspectives On Hacktivism: The Roles and Actions of Hacker Activist Groups
7 pages
Course Guide SS117
No ratings yet
Course Guide SS117
5 pages
Syllabus (Digital Security)
No ratings yet
Syllabus (Digital Security)
6 pages
MITRE ATT&CK for Cyber Pros
No ratings yet
MITRE ATT&CK for Cyber Pros
11 pages
How To Set Up Hyper-V Replication
No ratings yet
How To Set Up Hyper-V Replication
58 pages
Tsedey Bank
No ratings yet
Tsedey Bank
11 pages
ACCA PM Secure
No ratings yet
ACCA PM Secure
213 pages
Anyconnect Guide
No ratings yet
Anyconnect Guide
46 pages
Rr410504 Network Security and Cryptography
No ratings yet
Rr410504 Network Security and Cryptography
5 pages
Juniper Netscreen NS 5GT Series & GreenBow IPSec VPN Client Software Configuration
No ratings yet
Juniper Netscreen NS 5GT Series & GreenBow IPSec VPN Client Software Configuration
14 pages
IoT Development and Security Quiz
No ratings yet
IoT Development and Security Quiz
45 pages
FHR SOP With Flow
No ratings yet
FHR SOP With Flow
59 pages
Control System
No ratings yet
Control System
23 pages
Advanced Firepower IPS Deployment Guide
No ratings yet
Advanced Firepower IPS Deployment Guide
186 pages
Integrated Security Solutions
No ratings yet
Integrated Security Solutions
40 pages
Security Breach Prediction Using Artificial Neural Networks
No ratings yet
Security Breach Prediction Using Artificial Neural Networks
5 pages
Cybersecurity Engineer Profile & Experience
No ratings yet
Cybersecurity Engineer Profile & Experience
2 pages
CCSK Cloud Security Practice Questions
No ratings yet
CCSK Cloud Security Practice Questions
78 pages
OS Security Essentials
No ratings yet
OS Security Essentials
47 pages
UNIT - 2 CYBER SECURITY Cybercrime and Cyber Law
No ratings yet
UNIT - 2 CYBER SECURITY Cybercrime and Cyber Law
23 pages