Claroty Web API User
Guide
CTD Version 4.3.0
Confidential & Proprietary
July 2021
Web API User Guide
TABLE OF CONTENTS
1. API Explorer ...................................................................................................................... 4
2. Accessing the API Explorer ................................................................................................ 5
3. Using the API Explorer ...................................................................................................... 6
4. Authentication .................................................................................................................. 9
4.1. Authentication steps .............................................................................................. 9
5. Overview ......................................................................................................................... 12
5.1. Permissions ......................................................................................................... 12
5.2. Separators ........................................................................................................... 12
5.3. Models ................................................................................................................. 12
6. Example of Get Asset Type - Exact Match ........................................................................ 13
7. Example of Get Alerts ...................................................................................................... 14
8. Example: Retrieve the Assets of an Insight ...................................................................... 18
8.1. GET /ranger/insights_summary ............................................................................ 18
8.2. GET /ranger/insight_details-{insight_name} .......................................................... 18
8.3. GET /ranger/assets ............................................................................................... 18
8.4. Asset Filter Information Fields .............................................................................. 19
Rev 6 CTD Version 4.3.0 Page 2 of 21
Web API User Guide
Rev Date Owner Author Description
Rev 6 July 2021 Moshe Alvoer Beth Stolper No change
Rev 5 December 2020 Daniel Ashual Beth Stolper Clarified the Assets API
Rev 4 November 2020 Daniel Ashual Beth Stolper Screens updated for v4.2.1. Insights APIs
added
Rev 3 July 2020 Daniel Ashual Beth Stolper Included general statement re permissions
for methods. Added description of Models.
Removed list and description of Methods.
Revised Alerts example
Rev 2 July 2020 Daniel Ashual Beth Stolper Added Note re user/admin usage
Rev 1 June 2020 Daniel Ashual Beth Stolper Initial release
Rev 6 CTD Version 4.3.0 Page 3 of 21
Web API User Guide API Explorer
1. API Explorer
These instructions cover the API Explorer for Continuous Threat Detection (CTD).
This Web API reference provides all the information needed for application developers to imple-
ment calls for Claroty's endpoints. Use these RESTful APIs to access Claroty routes for enhancing
your system.
Rev 6 CTD Version 4.3.0 Page 4 of 21
Web API User Guide Accessing the API Explorer
2. Accessing the API Explorer
Log in to CTD with your username and password.
NOTE
This functionality is relevant for only for Admins.
Figure 1. API Explorer
1. On the far right edge of the Activity bar at the top of the screen, click on your username to
open the user dialog
2. Select the API Explorer button.
3. The API Explorer opens in Swagger as shown in the figure below.
Rev 6 CTD Version 4.3.0 Page 5 of 21
Web API User Guide Using the API Explorer
3. Using the API Explorer
The API Explorer opens in a separate tab as follows:
Figure 2. Opening Page
Rev 6 CTD Version 4.3.0 Page 6 of 21
Web API User Guide Using the API Explorer
Rev 6 CTD Version 4.3.0 Page 7 of 21
Web API User Guide Using the API Explorer
Figure 4. API Models
Figure 3. APIs: Main Page
Rev 6 CTD Version 4.3.0 Page 8 of 21
Web API User Guide Authentication
4. Authentication
Most of the Claroty routes are token-based. You need to have the token and be logged into the
system to use these calls.
Before using these APIs, authenticate yourself as a user using a JSON web token, as described be-
low.
4.1. Authentication steps
Figure 5. Authentication
1. Click on the POST /auth/authenticate route, and then click the Try it out button
2. The Set License parameters appear. Input your username and password credentials, and
then click the Execute button
3. The Response Body appears with the result. Select and copy to your clipboard the entire to-
ken string (between the quote marks), as shown in the example below:
Rev 6 CTD Version 4.3.0 Page 9 of 21
Web API User Guide Authentication steps
Figure 6. Copying the token from the response body
4. On the top right corner of the main API page, click the green Authorize button
5. The Available Authorization pops up.
Figure 7. Authorization popup
6. Enter your token in the Value window
7. Click Authorize
8. Now that you have authenticated, you can use the calls.
9. Each function call that is available is indicated by a black lock icon.
Rev 6 CTD Version 4.3.0 Page 10 of 21
Web API User Guide Authentication steps
Figure 8. Black lock icons appear once the User is authenticated
Rev 6 CTD Version 4.3.0 Page 11 of 21
Web API User Guide Overview
5. Overview
5.1. Permissions
Admins can access all the routes. Other users can obtain all the information they can access in the
CTD UI.
5.2. Separators
,;$ is used for separating multiple values when filtering.
For example:
• /assets?asset_type__exact=1,;$2,;$4
• Will search for all assets but return just the assets of type 1, 2, 4.
• /ranger/assets?fields=vendor,;$id
• Will search for all assets but return just the vendor and ID fields
5.3. Models
The Response Body is usually a JSON document, and the structure of that JSON document is de-
fined in the Models provided in the API Explorer, immediately below the area of the function calls:
Figure 9. Models
Rev 6 CTD Version 4.3.0 Page 12 of 21
Web API User Guide Example of Get Asset Type - Exact
Match
6. Example of Get Asset Type - Exact Match
The following example shows how to retrieve an exact match:
Figure 10. Get Assets method
1. Select the method to use (e.g. Get Assets)
2. Click Try it Out to make the method available
3. Select the filter you want. You can search for the filter, e.g:
• asset_type_exact
4. Enter the filter you want using the separator, e.g.
• 1,;$2,;$4,;$5
Figure 11. Specifying an Asset Type - Exact Match
5. Press Execute
6. The system responds with:
• the resulting CURL statement
• the Request URL
• the Server Response Body, which you can copy or download as a json file or copy
Rev 6 CTD Version 4.3.0 Page 13 of 21
Web API User Guide Example of Get Alerts
7. Example of Get Alerts
The following example shows how to retrieve all assets:
Figure 12. Get Alerts method
1. Open the Get Alerts method
2. Click Try it Out
3. Enter the filter/s you want, using the separators where needed, e.g.:
Rev 6 CTD Version 4.3.0 Page 14 of 21
Web API User Guide Example of Get Alerts
Figure 13. Filters for Get Alerts
a. For Site ID = 1
b. For Severity Levels of 2 and 3
c. With Exact Resolved = false
d. With Qualified Alert = true
4. This selection runs the following command:
Rev 6 CTD Version 4.3.0 Page 15 of 21
Web API User Guide Example of Get Alerts
ranger/alerts?fields=
&format=alert_list
&sort=-score
&page=1
&per_page=20
&resolved__exact=false
&is_qualified__exact=true
&severity__exact=2,;$3
&site_id__exact=1
5. Press the Execute button at the bottom of the method
6. The system responds with:
Figure 14. Get Alerts - Response
• The resulting CURL statement
• The Request URL
• The Server Response Body, which you can copy or download as a JSON file
Rev 6 CTD Version 4.3.0 Page 16 of 21
Web API User Guide Example of Get Alerts
• The Server Response Header
• The Code and Description, e.g. 200 Successful Operation
• The Example Value / Model
Rev 6 CTD Version 4.3.0 Page 17 of 21
Web API User Guide Example: Retrieve the Assets of an
Insight
8. Example: Retrieve the Assets of an Insight
The following example shows how use the following sequence of functions to retrieve all the as-
sets associated with a specific Insight, using the following sequence of methods:
• GET /ranger/insights_summary
• GET /ranger/insight_details-{insight_name}
• GET /ranger/assets
8.1. GET /ranger/insights_summary
1. Open the GET /ranger/insights_summary method
2. Click Try it Out
3. Apply the relevant site number in the field site_id__exact
4. Click Execute
5. From the Response body, select the insight of interest
• e.g. Assets Accessed SMB shares
• Copy the string of the insight name
8.2. GET /ranger/insight_details-{insight_name}
1. Open the GET /ranger/insight_details-{insight_name} method
2. Click Try it Out
3. Enter (paste) the insight name from above into the insight name field
4. Apply the relevant site number in the site_id__exact field
5. Click Execute
6. From the Response Body, select the filter_key
7. Copy the string of the filter_key
8.3. GET /ranger/assets
1. Open the GET /ranger/assets method
2. Click Try it Out
3. Enter (paste) the filter_key from above into the INSIGHT_ROW_KEY_EXACT field
4. Apply the relevant site number in the site_id__exact field
5. Enter VALID_TRUE to the valid_exact field in order to filter the assets accordingly
6. Enter APPROVED_TRUE to the approved_exact field in order to filter the assets accordingly
7. Enter other relevant filters as needed
8. Click Execute
• The requested assets for this Insight appear in the Response Body:
Rev 6 CTD Version 4.3.0 Page 18 of 21
Web API User Guide Asset Filter Information Fields
Figure 15. Get Assets for an Insight – Response
• The resulting CURL statement
• The Request URL
• The Server Response Body, which you can copy or download as a JSON file
• The Server Response Header
• The Code and Description, e.g. 200 Successful Operation
• The Example Value / Model
8.4. Asset Filter Information Fields
The asset filters are shown below.
Table 1. Asset Filter Information Fields
Code Means
format Specifies the type of response (list of fields) returned by the query.
If not provided, all asset properties will return and could affect performance
Rev 6 CTD Version 4.3.0 Page 19 of 21
Web API User Guide Asset Filter Information Fields
Code Means
Responsible for which columns will be returned by using the asset’s API call:
• asset_list – all columns, as if you are in the assets page
• insight_assets – the set of columns that relate to insights and assets
• rids – only the RIDs are returned. A rid is a combination of the resource
(asset) ID and the site ID
page The actual page offset.
per_page The number of assets to pull on each page (the maximum is 500)
ipv4__exact The IPV4 protocol
ipv6__exact The IPV6 protocol
mac__icontains The MAC address of the device (free text)
vlan__exact The VLAN/s of the device
address__exact The IP address of this device in the network
gateway__exact The gateway of this device in the network
asset_type__exact The asset type for this asset
host_name__exact The host name for this asset
os__exact The name of the Operating System
model__icontains The model of this asset (free text)
vendor__icontains The vendor of this asset (free text)
state__exact The dropdown of the asset states:
0 = Training
1 = Maintenance
2 = Guest
domain_names__exact The exact domain name(s) of the asset
firmware__exact The exact firmware name of the asset
serial__exact The exact serial number for the asset
generic__icontains Custom information (free text)
display_name__icontains The name of the asset (free text)
criticality__exact Low, Medium, or High. These CTD values represent how critical the asset it-
self is to the operation. CTD assigns criticality automatically to certain types
of assets but enables you to edit the value
old_ip__exact The former IPs this asset has used
protocol__exact The list of protocols in which this asset communicates
last_seen__exact The Timestamp of the last instance when this device was seen in the network
q__icontains Free text for the following asset info: name, IP, version, Model and MAC
fields
alert_id__exact The IDs of the alerts triggered by this asset
baseline__exact The baseline for this asset
arp_baselines__exact Whether this asset has ARP baselines
True = ARP
insight_status__exact integer The status of the insight associated with this asset – this is a dropdown for
choosing the integer type:
0 = Open
1 = Hidden
2 = Completed
Rev 6 CTD Version 4.3.0 Page 20 of 21
Web API User Guide Asset Filter Information Fields
Code Means
insight_insight_name__exact The name of the insight associated with this asset
insight_timestamp__gte When this insight was detected; greater than or equal to a specific time-
stamp
insight_timestamp__lte When this insight was detected; lower than or equal to a specific timestamp
baseline_category__exact The category of the baseline for this asset
baseline_access_type__exact The access type for the baseline for this asset
insight_name__exact The name of the insight associated with this asset
insight_row_key_exact The row key of the related insight
ghost__exact Whether or not this is a ghost asset
TRUE = Ghost
tasks__exact The Resource ID of the Active tasks running on this asset
active_queries__exact The Resource ID of the Active queries running on this asset
subnet_tag__exact The device’s network location
custom_attributes__exact The value of the user defined custom attributes for this asset
class_type__exact The class type of this asset (IT, OT, IoT)
domain_name__exact The domain name of this asset
involved_in_tags_rid__exact The tag artifact Resource IDs
hosted_tags__icontains The artifact name (free text)
id__exact The device’s unique identifier in the system
site_id__exact The identifier of the site in which this device resides
timestamp__exact The timestamp of when this asset was detected
approved__exact If this asset has been approved
valid__exact If this asset is valid
True = valid
parsed__exact Whether or not parsed information (numerical or textual value from the pro-
tocols) have been incorporated by CTD into the asset’s baseline
special_hint__exact integer The address type
0 = unicast
1 = broadcast
2= multicast
risk_level__exact The CTD level of risk for this device, based on its vulnerabilities, insights,
alerts, policies, asset criticality, and network location
network_id__exact The ID of the network in which this device is located
virtual_zone_id__exact The group of related assets this device belongs to (e.g. PLC Modbus)
subnet_id__exact The device’s network location
purdue_level__exact The Purdue model level of this specific device (0-6). This value is automatical-
ly determined based on the various characteristics of the asset and its pur-
pose. Can be adjusted to reflect the true asset behavior. Also note that inter-
im Purdue levels can also be used, e.g. 1.5, 2.5, 3.5
Rev 6 CTD Version 4.3.0 Page 21 of 21
