Inventory management API reference for OT monitoring sensors

2023-01-03

This article lists the device inventory management APIs supported for Defender for IoT OT sensors.

connections (Retrieve device connection information)

Use this API to request a list of all device connections.

URI: /api/v1/devices/connections

GET

Query parameters

Define any of the following query parameters to filter the results returned. If you don't set query parameters, all device connections are returned.

Name	Description	Example	Required / Optional
discoveredBefore	Numeric. Filter results that were detected before a given time, where the given time is defined in milliseconds from Epoch time, and in UTC timezone.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Optional
discoveredAfter	Numeric. Filter results that were detected after a given time, where the given time is defined in milliseconds from Epoch time, and in UTC timezone.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Optional
lastActiveInMinutes	Numeric. Filter results by a given time frame during which connections were active. Defined backwards, in minutes, from the current time.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Optional

Response type: JSON

Array of JSON objects that represent device connections, or the following failure message:

Message	Description
Failure – error	Operation failed

Success response fields

Name	Type	Nullable / Not nullable	List of values
firstDeviceId	Numeric	Not nullable	-
secondDeviceId	Numeric	Not nullable	-
lastSeen	Numeric	Not nullable	Epoch (UTC)
discovered	Numeric	Not nullable	Epoch (UTC)
ports	Number array	Nullable	-
protocols	JSON array	Nullable	Protocol field

Protocol fields

Name	Type	Nullable / Not nullable
name	String	Not nullable
commands	String array	Nullable

Response example

[
    {
        "firstDeviceId": 171,
        "secondDeviceId": 22,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
        {
            name: "modbus",
            commands: [
                "Read Coils"
            ]
        },
        {
            name: "ams",
            commands: [
                "AMS Write"
            ]
        },
        {
            name: "http",
            commands: [
            ]
        }
    ]
    },
    {
        "firstDeviceId": 171,
        "secondDeviceId": 23,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
            {
                name: "s7comm",
                commands: [
                    "Download block",
                    "Upload"
                ]
            }
        ]
    }
]

Type: GET

APIs:

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/connections

Examples:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/connections

connections per device (Retrieve specific device connection information )

Use this API to request a list of all the connections per device.

URI: /api/v1/devices/<deviceID>/connections

GET

Path parameter

Name	Description	Example	Required / Optional
deviceId	Get connections for the given device.	`/api/v1/devices/<deviceId>/connections`	Required

Query parameters

Name	Description	Example	Required / Optional
discoveredBefore	Numeric. Filter results that were detected before a given time, where the given time is defined in milliseconds from Epoch time, and in UTC timezone.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Optional
discoveredAfter	Numeric. Filter results that were detected after a given time, where the given time is defined in milliseconds from Epoch time, and in UTC timezone.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Optional
lastActiveInMinutes	Numeric. Filter results by a given time frame during which connections were active. Defined backwards, in minutes, from the current time.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Optional

Response type: JSON

Array of JSON objects that represent device connections, or the following failure message:

Message	Description
Failure – error	Operation failed

Success response fields

Name	Type	Nullable / Not nullable	List of values
firstDeviceId	Numeric	Not nullable	-
secondDeviceId	Numeric	Not nullable	-
lastSeen	Numeric	Not nullable	Epoch (UTC)
discovered	Numeric	Not nullable	Epoch (UTC)
ports	Number array	Nullable	-
protocols	JSON array	Nullable	Protocol field

Protocol fields

Name	Type	Nullable / Not nullable
name	String	Not nullable
commands	String array	Nullable

Response example

[
    {
        "firstDeviceId": 171,
        "secondDeviceId": 22,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
        {
            name: "modbus",
            commands: [
                "Read Coils"
            ]
        },
        {
            name: "ams",
            commands: [
                "AMS Write"
            ]
        },
        {
            name: "http",
            commands: [
            ]
        }
    ]
    },
    {
        "firstDeviceId": 171,
        "secondDeviceId": 23,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
            {
                name: "s7comm",
                commands: [
                    "Download block",
                    "Upload"
                ]
            }
        ]
    }
]

Type: GET

APIs:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/devices/<deviceId>/connections?lastActiveInMinutes=&discoveredBefore=&discoveredAfter=

Examples:

With given query parameters:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/devices/2/connections?lastActiveInMinutes=20&discoveredBefore=1594550986000&discoveredAfter=1594550986000

cves (Retrieve information on CVEs)

Use this API to request a list of all known CVEs discovered on devices in the network, sorted by descending CVE score.

URI: /api/v1/devices/cves

GET

Example: /api/v1/devices/cves

Define any of the following query parameters to filter the results returned.

Name	Description	Example	Required / Optional
top	Numeric. Determine how many top-scored CVEs to get for each device IP address.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Optional. Default = `100`

Type: JSON

JSON array of device CVE objects, or the following failure message:

Message	Description
Failure – error	Operation failed

Success response fields

Name	Type	Nullable / Not nullable	List of values
cveId	String	Not nullable	A canonical, industry-standard ID for the given CVE.
ipAddress	String	Not nullable	IP addresses
score	String	Not nullable	A CVE score, between 0.0 - 10.0
attackVector	String	Not nullable	`Network`, `Adjacent Network`, `Local`, or `Physical`
description	String	Not nullable	-

Response example

[
    {

        "cveId": "CVE-2007-0099",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Race condition in the msxml3 module in Microsoft XML Core
        Services 3.0, as used in Internet Explorer 6 and other
        applications, allows remote attackers to execute arbitrary
        code or cause a denial of service (application crash) via many
        nested tags in an XML document in an IFRAME, when synchronous
        document rendering is frequently disrupted with asynchronous
        events, as demonstrated using a JavaScript timer, which can
        trigger NULL pointer dereferences or memory corruption, aka
        \"MSXML Memory Corruption Vulnerability.\""
    },
    {
        "cveId": "CVE-2009-1547",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Unspecified vulnerability in Microsoft Internet Explorer 5.01
        SP4, 6, 6 SP1, and 7 allows remote attackers to execute
        arbitrary code via a crafted data stream header that triggers
        memory corruption, aka \"Data Stream Header Corruption
        Vulnerability.\""
    }
]

Type: GET

APIs:

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/cves

Examples:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/cves

cves per IP address (Retrieve specific information on CVEs)

Use this API to request a list of all known CVEs discovered on devices in the network for a specific IP address.

URI: /api/v1/devices/cves

GET

Example: /api/v1/devices/cves

Path parameter

Name	Description	Example	Required / Optional
ipAddress	Get CVEs for the given IP address.	`/api/v1/devices/<ipAddress>/cves`	Required

Define the following query parameter to filter the results returned.

Name	Description	Example	Required / Optional
top	Numeric. Determine how many top-scored CVEs to get for each device IP address.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Optional. Default = `100`

Type: JSON

JSON array of device CVE objects, or the following failure message:

Message	Description
Failure – error	Operation failed

Success response fields

Name	Type	Nullable / Not nullable	List of values
cveId	String	Not nullable	A canonical, industry-standard ID for the given CVE.
ipAddress	String	Not nullable	IP addresses
score	String	Not nullable	A CVE score, between 0.0 - 10.0
attackVector	String	Not nullable	`Network`, `Adjacent Network`, `Local`, or `Physical`
description	String	Not nullable	-

Response example

[
    {

        "cveId": "CVE-2007-0099",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Race condition in the msxml3 module in Microsoft XML Core
        Services 3.0, as used in Internet Explorer 6 and other
        applications, allows remote attackers to execute arbitrary
        code or cause a denial of service (application crash) via many
        nested tags in an XML document in an IFRAME, when synchronous
        document rendering is frequently disrupted with asynchronous
        events, as demonstrated using a JavaScript timer, which can
        trigger NULL pointer dereferences or memory corruption, aka
        \"MSXML Memory Corruption Vulnerability.\""
    },
    {
        "cveId": "CVE-2009-1547",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Unspecified vulnerability in Microsoft Internet Explorer 5.01
        SP4, 6, 6 SP1, and 7 allows remote attackers to execute
        arbitrary code via a crafted data stream header that triggers
        memory corruption, aka \"Data Stream Header Corruption
        Vulnerability.\""
    }
]

Type: GET

APIs:

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/<deviceIpAddress>/cves?top=

Examples:

With given query parameters:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/10.10.10.15/cves?top=50

devices (Retrieve device information)

Use this API to request a list of all devices detected by this sensor.

URI: api/v1/devices/

GET

Query parameter

Define the following query parameter to filter the results returned. If you don't set query parameters, all device connections are returned.

Name	Description	Example	Required / Optional
authorized	Boolean: - `true`: Filter for data on authorized devices only. - `false`: Filter for data on unauthorized devices only.	`/api/v1/devices/`	Optional

Response type: JSON

Array of JSON objects that represent device objects, or the following failure message:

Message	Description
Failure – error	Operation failed

Success response fields

Name	Type	Nullable / Not nullable	List of values
id	Numeric. Defines the device ID.	Not nullable	-
ipAddresses	JSON array of strings.	Nullable	-
name	String. Defines the device name.	Not nullable	-
vendor	String. Defines the device's vendor.	Nullable	-
operatingSystem	Enum. Defines the device's operating system.	Nullable	For more information, see Supported operatingSystem values.
macAddresses	JSON array of strings.	Nullable	-
type	String. Defines the device type.	Not nullable	Can be `Unknown`. For more information, see Supported type values.
engineeringStation	Boolean. Defines whether the device is defined as an engineering station or not.	Not nullable	- `true`: Device is an engineering station - `false`: Device is not an engineering station.
authorized	Boolean. Defines whether the device is defined as an engineering station or not.	Not nullable	- `true`: Device is an engineering station - `false`: Device is not an engineering station
scanner	Boolean. Defines whether the device is authorized or not.	Not nullable	- `true`: Device is authorized - `false`: Device is not authorized
protocols	Object that contains the device's protocol details.	Nullable	For more information, see Microsoft Defender for IoT - supported IoT, OT, ICS, and SCADA protocols.
firmware	JSON array of a `firmware` object that defies the device's firmware.	Not nullable	For more information, see Supported firmware fields.
hasDynamicAddress	Boolean. Defines whether the device has a dynamic address or not.	Not nullable	- `true`: Device has a dynamic address - `false`: Device does not have a dynamic address

Supported `operatingSystem` values

This section lists the supported values for the operatingSystem response field.

Windows 10
Windows 10 32
Windows 10 64
Windows 2000
Windows 7
Windows 7 32
Windows 7 64
Windows 8
Windows 8 32
Windows 8 64
Windows 8.1
Windows 8.1 32

Windows 8.1 64
Windows NT
Windows Server 2003
Windows Server 2003 R2
Windows Server 2008
Windows Server 2008 32
Windows Server 2008 64
Windows Server 2008 R2
Windows Server 2012
Windows Server 2012 R2
Windows Server 2016
Windows Vista

Windows Vista 32
Windows Vista 64
Windows XP
Mac OS
Mac OS X
Linux
Windows Server 2019
HP UX
Windows 11
Windows 11 32
Windows 11 64

Supported `type` values

This section lists the supported values for the type response field.

Engineering Station
PLC
Historian
HMI
Domain Controller
DB Server
Wireless Access Point
Router
Switch
Workstation
Server
IP Camera
Printer
Multicast/Broadcast
Internet
Firewall
Terminal Station
VPN Gateway
Group

IED
DCS Controller
RTU
NTP Server
Storage
Industrial Packaging System
Industrial Scale
Industrial Robot
Slot
Punch Clock
ATM
Smart TV
Game console
DVR
Door Control Panel
HVAC
Thermostat
Fire Alarm
Smart Light

Smart Switch
Fire Detector
IP Telephone
Alarm System
Alarm Siren
Smart Phone
Tablet
Wifi Pineapple
Motion Detector
Elevator
Humidity Sensor
Physical Location
Backup Server
Meter
Barcode Scanner
Uninterruptible Power Supply

Variable Frequency Drive
Robot Controller
Servo Drive
Pneumatic Device
Marquee
People Counter System
Intercom
Turnstile
I/O Adapter
Protocol Converter
KVM
Web Guiding System
Turbine
External Management
Embedded Device
Unknown

Supported fields for the `protocols` object and protocol `name` values

This section lists the supported fields for the protocols object in the protocols response field.

Name	Type	Nullable / Not nullable	List of values
id	Numeric. Defines the protocol's internal ID.	Not nullable	-
name	String. Defines the device name.	Not nullable	For more information, see below.
ipAddresses	JSON array of strings of protocol IP addresses.	Not nullable	-

The following values are supported as protocol names out-of-the-box:

Unknown
DNP3
MODBUS
C37.118
SSH
HTTP
SYSLOG
GENERIC
ICMP
DNS
GOOSE
MMS
MALFORMED
IEC-60870
OPC UA
Siemens S7
ARP
Sampled Values
EtherNet/IP

Siemens S7 Plus
Motorola MDLC
Netbios Name Service
Netbios Datagram Service
Lightweight Access Point
CAPWAP
SNMP
DTLS
TNS
Database
SRTP
RPC
OPC
DF-1
DH-485
TDS
SMB
Suitelink
ControlNet

FTP
CDP
Profinet DCP
Profinet Real-Time
LLDP
Telnet
DeltaV
BACNet
AMS
TwinCAT
Ovation ADMD
Ovation SSRPC
Ovation DPUSTAT
Port Map
STP
Telvent OASyS Tags
Mitsubishi MELSEC
Honeywell Control Data Access

ARP
Yokogawa HIS Equalize
Emerson OpenBSI
Siemens SICAM
Omron FINS
Toshiba Computer Link
Foxboro I/A
Yokogawa VNet/IP
Emerson ROC
ABB Totalflow
Siemens Process Historian Discovery
Siemens WinCC Agent
LonTalk
Common ASCII Message
CodeSys
SAIA S-Bus
MDNS
Bently Nevada

Supported firmware fields

This section lists the supported fields for the firmware object in the firmware response field.

Name	Type	Nullable / Not nullable	List of values
address	String. Defines the firmware IP address.	Not nullable	-
moduleAddress	String. Defines the firmware's module address.	Not nullable.	-
serial	String. Defines the firmware's serial number.	Nullable	-
model	String. Defines the firmware model.	Nullable	-
firmwareVersion	String. Defines the firmware version.	Nullable	-
additionalData	String. Defines additional data for the firmware.	Nullable	-
rack	String. Defines the firmware rack.	Nullable	-
slot	String. Defines the firmware slot.	Nullable	-

Type: GET

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/devices/'

Next steps

For more information, see the Defender for IoT API reference overview.

Share via

Inventory management API reference for OT monitoring sensors

connections (Retrieve device connection information)

GET

Query parameters

connections per device (Retrieve specific device connection information )

GET

Path parameter

Query parameters

cves (Retrieve information on CVEs)

GET

cves per IP address (Retrieve specific information on CVEs)

GET

Path parameter

devices (Retrieve device information)

GET

Query parameter

Next steps

Feedback

Additional resources