The Portable Inventory Data format

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). JSON has become the most widely adopted data format for sharing complex data and is supported by modern enterprise applications, including service management software, configuration management database systems (CMDB), and more.

In the following documentation, labels in italics are placeholders for data that is expressed in JSON, always enclosed in quotation marks.

Portable Inventory Data Envelope

A Portable Inventory Data set is enclosed in an "envelope" that holds the inventory data content plus a metadata prefix. The metadata prefix specifies the software that was used to create data set (example: "OTbase 4.03"), the account that created the data set, and the time of creation.

The metadata prefix has the following format:

"meta":{
"origin":software product and version used to create the data set,    
"createdBy":user account that created the data set,
"organization":organization with which that user account is affiliated with,
"createdWhen":date and time of creation
}

Inventory data content can be of the type devices, hardware, software, or combinations thereof.

A complete Portable Inventory Data envelope hence looks like this:

{metadata prefix, content}

Device inventory

A device inventory is expressed as a list of device objects:

"devices":[{deviceObject}, ...]

Device identity and configuration data of individual devices as part of an asset inventory.

{
  "deviceRef": unique database reference for the device that never changes,
  "deviceId": unique identifier for the device that can be changed by the user,
  "name": device name (e.g. DNS name),
  "description": Description for the device,
  "installationDate": installation date,
  "stage": lifecycle stage,
  "serialNumber": serial number,
  "zone": network zone,
  "safety": safety certification,
  "criticality": criticality rating,
  "modified": timestamp when the asset's configuration was last modified,
  "exposure": network exposure of the asset, if known to OTbase (e.g. "local"),
  "hostedOn": device identifier of the virtualization host if known,
  "tags": [list of tags assigned to the device],
  "hardware":{
       "vendor": vendor name,
       "model": model,
       "type": type (PLC, RTU, ...),
       "version": product version,
       "orderNumber": order number,
       "description": product description,
       "endOfLife": published end-of-life for the product,
       "safety": safety certification,
       "lifecycle": product lifecycle stage,
  "context":{
       "location": hierarchical location name,
       "locationId": location identifier,
       "referenceLocation": reference location (usually: site name)
       "otSystem": OT system associated with the device,
       "deviceGroup": device group assigned to the device,
       "processes":[
             {"name": processes name associated with the device,
            "location": processes location,
            "locationId": processes locationId},
        ...]},
  "connections":[
       {"network": network name,
       "networkId": network identifier (auto-assigned by OTbase),
       "networkAddress": IP address of the network,
       "networkLocation": location name where the network resides,
       "networkLocationId": location ID where the network resides,
       "networkType": network type (IP, Profibus, ...),
       "medium": physical medium of the network (Copper, Fiber),
       "L2Address": MAC address of the network interface,
       "L3Address": IP address of the network interface,
       "ifName": interface name,
       "ifStatus": interface status (UP | Down),
       "port": port number/name of the interface,
       "vlan": VLAN ID of the interface,
       "speed": transmission speed of the interface,
       "duplex": duplex characteristic of the interface,
       "counterpart": device ID of the remote device,
       "remotePort": port number/name of the remote device,
       "remoteDesc": description of the remote device }
       ...],
  "software":[
       {"category": software category,
       "type": software type (OS, Firmware, Application, Patch, ...),
       "vendor": vendor name,
       "name": product name,
       "version": version,
       "licenseKey": license key,
       "installDate": installation date,
       "endOfSupport": published end of product support,
       "safety": safety certification,
       "description": description,
       "lifecycle": product lifecycle stage},
       ...],
  "vulnerabilities":[
       {"cveId":CVE identifier (e.g. CVE-2020-517),
       "baseScore": CVSS base score,
       "severity": CVSS severity (assigned by MITRE),
       "priority": CVE priority (assigned by the user),
       "datePublished": CVE publication date},
       "kev": indicates if there is a known exploit for the CVE,
       "fixed": indicates if the vulnerability is fixed for this device,
       ...],
  "modules":[
       {"slot": slot number,
       "hardware":{
            "vendor": vendor name,
            "model": model,
            "version": version,
            "name": module name,
            "orderNumber": order number,
            "serialNumber": serial number},
       "software":{
            "vendor": vendor name,
            "name": product name,
            "version": product version}
       },
       ...],
  "extended":{
       customField1: value,
       customField2: value,
       customField3: value,
       ...
       },
  "admins":[
       {"group_type": admin group type (built-in or not),
       "member_type": user or group,
       "name": administrator name,
       "approved": indicates if the administrator is approved,
       "approved_by": name of the user who approved the administrator,
       "is_local": indicates if the account is local or from AD},
       ...]
  "last_seen": timestamp when the asset was last seen by OTbase Discovery,
  "last_seen_by": name of the OTbase Discovery node that last saw the asset,
  "monitors":[
       {"monitor_name": name of an OTbase Discovery node that monitors the asset,
       "last_scan": timestamp of the last probe from this OTbase Discovery node,
       "last_version": version of the OTbase Discovery node,
       "last_result": last probing result,
       "last_seen": timestamp for this OTbase Discovery node when the asset was last seen
       },
       ...]
}

Hardware product inventory

A hardware product catalog contains a list of hardware product objects:

"hardware":[{hardwareObject}, ...]

A hardware product object documents metadata for hardware products.

{
  "vendor": vendor name,
  "model": model,
  "version": version,
  "type": type (PLC, RTU, Actuator, ...),
  "safety": safety certification,
  "orderNumber": order number,
  "description": product description,
  "vendorLink": vendor link (URL for product page),
  "endOfLife": published end-of-life,
  "lifecycle": published lifecycle stage,
  "tags":[list of tags assigned to the hardware product],
  "installations": [List of Device IDs indicating where the product is installed],
  "extended":{
          customField1: value,
          customField2: value,
          customField3: value,
          ...
          }
}

Software product inventory

A software product catalog contains a list of software product objects:

"software":[{softwareObject}, ...]

A software product object documents metadata for software products.

{
"vendor": vendor name,
"name": product name,
"version": product version,
"description": description,
"vendorLink": vendor link (URL for product page),
"category": product category,
"type": product type (OS, Application, Patch, ...),
"safety": safety certification,
"endOfSupport": published end-of-support date,
"lifecycle": published product lifecycle stage,
"tags":[list of tags assigned to the software product],
"installations": [List of Device IDs indicating where the product is installed],
"extended":{
        customField1: value,
        customField2: value,
        customField3: value,
        ...
        }
}

Vulnerabilities repository

The vulnerabilities repository contains a list of all published vulnerabilities that affect the installed base:

"vulnerabilities":[{vulnObject}, ...]

A vulnerability object contains information about a vulnerability that affects the installed base.

{
  "cveId": CVE identifier (e.g. CVE-2020-517),
  "baseScore": CVSS base score,
  "severity": CVSS severity (as assigned by MITRE),
  "priority": priority (as assigned by the user),
  "datePublished": publication date,
  "vector": CVSS vector,
  "description": vulnerability description,
  "devices": [List of device IDs for affected devices]
}

Location repository

A location repository contains a list of geo-locations:

"locations":[{locationObject}, ...]

A location object contains information about a geo-location:

{
  "locationId": location ID,
  "name": hierarchical location name,
  "referenceLocation": indicates if this is a reference location (Yes | No),
  "description": description,
  "address": street address,
  "gps": GPS coordinates,
  "company": company name,
  "extended":{
          customField1: value,
          customField2: value,
          customField3: value,
          ...
          }
 }

There is no need for a list of devices associated with a location as such a list can be obtained by querying the device inventory with a location or locationid filter.

System repository

A system repository contains a list of OT systems. An OT system can be a Distributed Control System, or a machine / production line in discrete manufacturing.

"systems":[{OTsystemObject}, ...]

An OT system object contains information about an OT system:

{
  "systemId": system identifier,
  "name": system name,
  "description": description,
  "locationId": process location identifier,
  "location": process location name,
  "extended":{
          customField1: value,
          customField2: value,
          customField3: value,
          ...
          }
}

There is no need for a list of devices associated with a system as such a list can be obtained by querying the device inventory with an otsystemid filter.

Video

The rationale and use cases for Portable Inventory Data are explained in this video: