The devices resource allows you to retrieve data related to devices within the scope of the access rights of the account that is issuing the REST API call. It provides several options to access the device data including:
- Retrieving data for all devices
- Retrieving data for a specific device identified by its unique device ID
- Retrieving data for devices that use a particular IP address
- Retrieving information about the software installed on a specific device identified by its unique device ID
- Retrieving information about the hardware modules installed in a specific device identified by its unique device ID.
All of the above-mentioned operations are performed using the GET method. The resulting content adheres to the Portable Inventory Data format. and is designed to be easily readable and understood. With this resource, you can gather comprehensive information about the devices that are associated with your account and manage them accordingly.
Basic queries
Retrieving a single inventory item
GET ot-base/api/v1/devices/{deviceID}
Individual devices can be retrieved by specifying the device identifier in the API call. This will result in only the metadata for this particular device being returned.
Retrieving multiple inventory items
GET ot-base/api/v1/devices
Retrieves all devices within the scope of the access rights for the account that is issueing the API call.
The envelope, and output paging
The result contains an info element after the devices element which informs you about
- the total number of items for this query (total),
- the offset with which this query was started (offset), and
- the next offset that you need to use if you want to continue the listing (next_offset).
In the interest of not overloading the client, output will contain device data for a maximum of 100 devices by default. You can control the number of records that are transmitted by using the count parameter, followed by the desired number of records. In the following example, output stops after 300 records:
GET ot-base/api/v1/devices/?count=300
For an iterative download of device data you can define an offset from where you want OT-BASE to start data output. This is achieved by using the offset parameter, followed by the offset of the starting record. (Note that the numbering counts with zero.) You don't even need to keep track of the offset in your own software, OT-BASE takes care of that for you. The info item in the REST response shows in the next_offset field which offset you need to use to continue the listing.
In this example, OT-BASE tells us that output would resume at offset 300:
Hence, if we want to continue the listing, our API call would be
GET ot-base/api/v1/devices/?offset=300
Search filters
Retrieving devices at a particular location
GET ot-base/api/v1/devices/?locationid=locationID
The locationid filter allows you to retrieve asset data for devices at a particular location, referenced by its location identifer. Output includes devices at any sub-location.
Retrieving devices associated with a particular OT system
GET ot-base/api/v1/devices/?otsystem=OTsystemName
Returns devices associated with a particular OT system, as referenced by its system name.
GET ot-base/api/v1/devices/?otsystemid=OTsystemID
Returns devices associated with a particular OT system, as referenced by its system identifier.
Retrieving devices with a particular IP address
The ipaddress filter can be used to search for devices that use a particular IP address:
GET ot-base/api/v1/devices/?ipaddress=X.X.X.X
where X.X.X.X is substituted by the IP address that you are searching.
Note that an IP address is not necessarily unique, therefore the search may return multiple results.
Retrieving devices that belong to a particular network
The networkid filter can be used to search for devices that belong to a particular network:
GET ot-base/api/v1/devices/?networkid=NetworkId
where NetworkId is substituted by the internal network ID that is automatically assigned by OT-BASE uses to reference the network. Note that this is not the IP address of the network.
Retrieving devices with a particular name
The name filter can be used to search for devices with a particular name:
GET ot-base/api/v1/devices/?name=xyz
where xyz is substituted by the name of the device that you are searching.
Note that a device name is not necessarily unique, therefore the search may return multiple results.
Retrieving only devices that have been changed since a particular point in time
GET ot-base/api/v1/devices/?modified=timestamp
will return only asset data for devices that have been changed since the specified timestamp, or have been added to the inventory since the timestamp.
The timestamp is specified in the ISO 8601 format and is based on UTC (Universal Time Coordinated). Higher-precision parts of the time stamp can be omitted, i.e. you don't have to specifiy milliseconds, seconds, minutes etc.
Example:
GET ot-base/api/v1/devices/?modified=2020-03-31T08:30
will retrieve devices that have changed or have been added since March 31, 2020, 8:30 a.m.
Output modifiers
By default, OT-BASE does not return software, module, administrator, or vulnerability data associated with inventory items. This data can be obtained by addressing sub-resources for individual devices, or by using output modifiers for bulk queries.
Retrieving the software or firmware associated with a single inventory item
GET ot-base/api/v1/devices/{deviceID}/software
The software installed on your Windows or *nix computers can be extensive, therefore software is not included in the inventory output by default. However you can retrieve software installed on any single device by accessing the software sub-resource, as in the command line above.
In the following example, we are retrieving the firmware installed on a device identified as "LU.BK12":
Retrieving the hardware modules associated with a single inventory item
GET ot-base/api/v1/devices/{deviceID}/modules
Hardware modules such as I/O interfaces are also not part of the standard output for the devices resource but can be retrieved using the modules sub-resource.
In the next example, we are retrieving the I/O modules of a device identified as "LU.BK12":
Retrieving known vulnerabilities for a single inventory item
GET ot-base/api/v1/devices/{deviceID}/vulnerabilities
Known vulnerabilities for a specific device can be queried by accessing the vulnerabilities sub-resource, as in the command line above.
Requesting software and firmware data
GET ot-base/api/v1/devices/?include=software
GET ot-base/api/v1/devices/{deviceID}/?include=software
Causes software and firmware data to be included in the response.
Requesting vulnerability data
GET ot-base/api/v1/devices/?include=vulnerabilities
GET ot-base/api/v1/devices/{deviceID}/?include=vulnerabilities
Causes vulnerability data to be included in the response.
Requesting hardware module data
GET ot-base/api/v1/devices/?include=modules
GET ot-base/api/v1/devices/{deviceID}/?include=modules
Causes hardware module data to be included in the response.
Requesting local administrators
GET ot-base/api/v1/devices/?include=admins
GET ot-base/api/v1/devices/{deviceID}/?include=admins
causes data on local administrative accounts to be included in the response.
Requesting multiple sub-resources
"Include" modifiers can be combined in order to request the inclusion of multiple sub-resources. For example,
GET ot-base/api/v1/devices/?include=software,vulnerabilities
GET ot-base/api/v1/devices/{deviceID}/?include=software,vulnerabilities
will cause both software and vulnerability data to be included in the response.
When all sub-resources shall be included, the following query can be used:
GET ot-base/api/v1/devices/?include=all
GET ot-base/api/v1/devices/{deviceID}/?include=all
Comments
0 comments
Please sign in to leave a comment.