The Portable Inventory Data format was invented by Langner as an easy way to share asset inventory data between applications. Simply put, Portable Inventory Data is a set of inventory data represented in JSON (JavaScript Object Notation).
PID envelope
When exporting Portable Inventory Data from OTbase Inventory, content is put in an "envelope" that consists of a data object and an info object.
The data object can contain device data, location data, system data, or vulnerability data -- depending on which REST endpoint you query, or where you export inventory data as a file.
The info object contains information about the account that was used to generate the data, where it originates from (usually OTbase Inventory, along with a version number), the number of retrieved items, and paging information when using the REST API (this allows you to make sure that neither your client application nor OTbase Inventory is experiencing resource exhaustion during the GET operation -- note that the full data set may be 1+ GB in size).
When importing asset information into OTbase Inventory, the envelope is not used, i.e. you simply send a list of device/system/location objects.
Device data
When importing data to OTbase Inventory, only the device list is used, not the "info" object.
[
{
"deviceRef": unique database reference for the device that never changes (READ ONLY),
"deviceId": unique identifier for the device that can be changed by the user,
"hostedOn": device identifier of the virtualization host if known,
"name": device name (e.g. hostname, DNS name),
"description": "description of the device,
"documentation": URL for the asset's documentation inside a document management system,
"installationDate": installation date,
"creationDate": timestamp when the device was created in OTbase (READ ONLY),
"manufactureDate": manufacture date of the device (READ ONLY),
"warranty": warranty details for the device (READ ONLY),
"stage": device lifecycle stage (e.g. Planned),
"lifecycle": product lifecycle stage (READ ONLY),
"serialNumber": serial number,
"owner": owner of the asset,
"last_seen": timestamp when the asset was last seen by OTbase Discovery (READ ONLY),
"zone": network zone,
"safety": safety certification, e.g. SIL2,
"security": target security level of the device,
"runMode": last PLC run mode / key switch position (READ ONLY),
"release": release version,
"criticality": citicality rating, e.g. SAFETY,
"modified": timestamp when the asset's configuration was last modified (READ ONLY),
"exposure": network exposure of the asset (e.g. \"local\"),
"hardware": { // hardware product attributes
"vendor": vendor name,
"model": model name,
"type": hardware type (PLC, RTU, ...),
"category": hardware category (computer, automation device, ...),
"version": product version,
"orderNumber": order number,
"vendorLink": link to vendor's product page (READ ONLY),
"description": product description (READ ONLY),
"endOfLife": published end-of-life for the product (READ ONLY),
"lifecycle": product lifecycle stage (READ ONLY),
"cpe": CPE for the product (READ ONLY),
"extended": {
user-defined fields for the hardware product (READ ONLY)
}
},
"context": {
"location": hierarchical location name (e.g. Boston/Building 3),
"locationId": unique location identifier (e.g. (B-B3),
"referenceLocation": reference location (usually: site name) (READ ONLY),
"referenceLocationId": reference location identifier (READ ONLY),
"otSystem": OT system associated with the device,
"otSystemId": OT system identifier,
"deviceGroup": device group assigned to the device,
"processes": [
{
"name": processes name associated with the device,
"location": processes location name,
"locationId": processes locationId
}
]
},
"os_firmware": OS or firmware version,
"software":[ // list with software products installed on the asset
{
"vendor": software vendor name,
"name": software product name,
"version": software product version,
"licenseKey": software license key,
"lastRun": timestamp when the software was last executed (READ ONLY),
"daysSinceLastRun": number of days since the software was last executed (READ ONLY),
"description": description,
"vendorLink": vendor link (URL for product page) (READ ONLY),
"category": product category (READ ONLY),
"type": product type (OS, Application, Patch, ...) (READ ONLY),
"safety": safety certification (READ ONLY),
"endOfSupport": published end-of-support date (READ ONLY),
"lifecycle": published product lifecycle stage (READ ONLY),
"cpe": CPE of the software product (READ ONLY),
"hashValue": hash for the software installation,
"hashMethod": hash method used to compute the hash value
}, ...
],
"tags": [
list of tags assigned to the device
],
"connections": [ // list with network interfaces and connections
{
"network": network name,
"networkId": network identifier (READ ONLY),
"networkGroup": network group name,
"medium": network medium (Copper, Fiber, ...),
"L2Address": Level 2 address (usually IP address),
"L3Address": Level 3 address (usually MAC address),
"networkAddress": "P address of the network,
"networkType": network type (IP, Profibus, ...),
"port": port number,
"vlan": VLAN ID,
"counterpart": counterpart device identifier,
"remotePort": remote port number,
"remoteDesc": remote device description,
"ifName": interface name,
"ifStatus": interface status,
"ifDHCP": DHCP status,
"speed": interface speed,
"duplex": duplex mode,
"networkLocation": location name where the network resides,
"networkLocationId": location ID where the network resides
}
],
"modules": [ // list of rack modules (for control system racks)
{
"name": module name,
"slot": slot number of module,
"hardware": {
"vendor": vendor name,
"model": model,
"version": version,
"type": module type,
"category": category type,
"orderNumber": order number,
"serialNumber" serial number,
"description": product description,
"manufactureDate": date of manufacture,
"warranty": warranty information
},
"software": {
"vendor": vendor name,
"name": firmware name,
"version": firmware version number
}
}, ...
],
"vulnerabilities": [ // list of known vulnerabilities for this asset (READ ONLY)
{
"cveId": CVE ID,
"kev": flag if there are known exploits (Yes|No),
"baseScore": CVSS base score,
"riskScore": user-asssigned risk score,
"severity": CVSS severity,
"priority": user-assgined priority,
"relevant": user-assigned relevancy assessment,
"comment": comment,
"datePublished": CVE publication date,
"fixed": flag if the vulnerability is mitigated (true|false)
},
...
]
"extended": { // extended (user defined) fields
"custom field": "value", ...
},
"last_seen_by": "name of the OTbase Discovery node that last saw the asset (READ ONLY)",
"monitors": [
{
"monitor_name": "name of an OTbase Discovery node that monitors the asset (READ ONLY)",
"last_scan": "timestamp of the last probe from this OTbase Discovery node (READ ONLY)",
"last_version": "version of the OTbase Discovery node (READ ONLY)",
"last_result": "last probing result (READ ONLY",
"last_seen": "timestamp for this OTbase Discovery node when the asset was last seen (READ ONLY)"
}
],
"last_patch_date": "date when the last patch was applied (READ ONLY)",
"days_since_last_patch": "number of days since the last patch (READ ONLY)"
}
]System data
OTbase allows you to model the plant components that your OT devices belong to, which provides for much better documentation quality (an OT device never acts alone but always as part of a plant component), and helps a lot when determining security and business continuity risk.
[
{
"systemId": unique alphanumeric ID of the system
"parent_systemId": unique alphanumeric ID of parent system (can be empty string),
"name": system name,
"full_name": full system path with parent's name and own name at the end (separated by "/"),
"description": system description,
"locationId": location ID of the system,
"location": full path name of the system's location,
"group_name": name of the system group that this system belongs to,
"approved": configuration approval status ("Yes"|"No") (READ ONLY),
"approved_on": approval timestamp (READ ONLY),
"approved_by": name of the account who approved the system configuration (READ ONLY),
"release": release version of the system configuration (READ ONLY),
"criticality": criticality of the system (inherited by devices),
"process": full pathname of a linked physical process,
"extended": { // custom fields along with their values
"custom field 1": value, "custom field n": value
}
"relations": [ // list of relationships to other systems
{
"relation_group_name": relation group name (e.g. "Material"),
"counterpart": name of the relation counterpart system,
"counterpartId": ID of the relation counterpart system,
"counterpart_full_name": full pathname of the relation counterpart system,
"direction": relationship direction ("consumes"|"provides"|"interacts"),
"description": relationship description,
"criticality": relationship criticality ("None"|"Low"|"Medium"|"High")
}, ...
]
}, ...
]
Comments
0 comments
Please sign in to leave a comment.