Vulnerability management API reference for OT monitoring sensors

2022-12-01

This article lists the vulnerability management REST APIs supported for Microsoft Defender for IoT OT monitoring sensors.

The data included in the API responses includes the same information as if you generated a vulnerability report from the OT sensor console.

devices (Retrieve device vulnerability information)

Use this API to request vulnerability assessment results for each device.

URI: /api/v1/reports/vulnerabilities/devices

GET

This API is called without any request parameters.

Type: JSON

Array of JSON objects that represent assessed devices and their reported vulnerabilities.

Devices that are found to have no vulnerabilities are not included in the result response.

Device fields

Name	Type	Nullable / Not nullable	List of values
name	String	Not nullable	-
ipAddresses	JSON array	Not nullable	-
securityScore	Numeric	Not nullable	-
vendor	String	Nullable
firmwareVersion	String	Nullable	-
model	String	Nullable	-
isWirelessAccessPoint	Boolean	Not nullable	`True` or `False`
operatingSystem	Operating system object	Nullable	-
vulnerabilities	Vulnerabilities object	Not nullable	-

Operating system fields

Name	Type	Nullable / Not nullable	List of values
name	String	Not nullable	-
type	String	Not nullable	-
version	String	Nullable	-
latestVersion	String	Nullable	-

Vulnerabilities fields

Name	Type	Nullable / Not nullable	List of values
antiViruses	JSON array of strings	Nullable	Antivirus names
plainTextPasswords	JSON array	Nullable	Password objects
remoteAccess	JSON array	Nullable	Remote access objects
isBackupServer	Boolean	Not nullable	`True` or `False`
openedPorts	JSON array	Nullable	Opened port objects
isEngineeringStation	Boolean	Not nullable	`True` or `False`
isKnownScanner	Boolean	Not nullable	`True` or `False`
cves	JSON array	Nullable	CVE objects
isUnauthorized	Boolean	Not nullable	`True` or `False`
malwareIndicationsDetected	Boolean	Not nullable	`True` or `False`
weakAuthentication	JSON array of strings	Nullable	Detected applications that are using weak authentication

Password fields

Name	Type	Nullable / Not nullable	List of values
password	String	Not nullable	-
protocol	String	Not nullable	-
strength	String	Not nullable	`Very weak`, `Weak`, `Medium`, `Strong`

Remote access fields

Name	Type	Nullable	List of values
port	Numeric	Not nullable	-
transport	String	Not nullable	`TCP`, `UDP`
client	String	Not nullable	IP address
clientSoftware	String	Not nullable	Name of the remote protocol, like `SSH`, `VNC`, `Remote desktop`, or `Team viewer`

Open port fields

Name	Type	Nullable / Not nullable	List of values
port	Numeric	Not nullable	-
transport	String	Not nullable	`TCP` or `UDP`
protocol	String	Nullable	-
isConflictingWithFirewall	Boolean	Not nullable	`True` or `False`

CVE fields

Name	Type	Nullable / Not nullable	List of values
id	String	Not nullable	-
score	Numeric, decimal value	Not nullable	-
description	String	Not nullable	-

Response example

[
    {
        "name": "IED \#10",
        "ipAddresses": ["10.2.1.10"],
        "securityScore": 100,
        "vendor": "ABB Switzerland Ltd, Power Systems",
        "firmwareVersion": null,
        "model": null,
        "operatingSystem": {
            "name": "ABB Switzerland Ltd, Power Systems",
            "type": "abb",
            "version": null,
            "latestVersion": null
        },
        "vulnerabilities": {
        "antiViruses": [
        "McAfee"
        ],
        "plainTextPasswords": [
            {
                "password": "123456",
                "protocol": "HTTP",
                "strength": "Very Weak"
            }
        ],
        "remoteAccess": [
            {
                "port": 5900,
                "transport": "TCP",
                "clientSoftware": "VNC",
                "client": "10.2.1.20"
            }
        ],
        "isBackupServer": true,
        "openedPorts": [
            {
                "port": 445,
                "transport": "TCP",
                "protocol": "SMP Over IP",
                "isConflictingWithFirewall": false
            },
            {
                "port": 80,
                "transport": "TCP",
                "protocol": "HTTP",
                "isConflictingWithFirewall": false
            }
        ],
        "isEngineeringStation": false,
        "isKnownScanner": false,
        "cves": [
            {
                "id": "CVE-2015-6490",
                "score": 10,
                "description": "Frosty URL - Stack-based buffer overflow on Allen-Bradley MicroLogix 1100 devices before B FRN 15.000 and 1400 devices through B FRN 15.003 allows remote attackers to execute arbitrary code via unspecified vectors"
            },
            {
                "id": "CVE-2012-6437",
                "score": 10,
                "description": "MicroLogix 1100 and 1400 do not properly perform authentication for Ethernet firmware updates, which allows remote attackers to execute arbitrary code via a Trojan horse update image"
            },
            {
                "id": "CVE-2012-6440",
                "score": 9.3,
                "description": "MicroLogix 1100 and 1400 allows man-in-the-middle attackers to conduct replay attacks via HTTP traffic."
            }
        ],
        "isUnauthorized": false,
        "malwareIndicationsDetected": true
        }
    }
]

Type: GET

API:

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

Example:

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

security (Retrieve security vulnerabilities)

Use this API to request results of a general vulnerability assessment report. This assessment provides insight into your system's security level.

This assessment is based on general network and system information and not on a specific device evaluation.

URI: /api/v1/reports/vulnerabilities/security

GET

This API is called without any request parameters.

Type: JSON representation of one or more data tables, each with specific and potentially different structures.

The response is displayed in a map view, which maps table titles to table rows. Rows are represented as a list of objects with the same structures.

unauthorizedDevices fields

Name	Type	Nullable / Not nullable	List of values
address	String	Nullable	IP or MAC address of the unauthorized device
name	String	Nullable	Name of the unauthorized device
firstDetectionTime	Numeric	Nullable	Timestamp the device was first detected, in milliseconds from Epoch time and in UTC timezone
lastSeen	Numeric	Nullable	Timestamp that traffic was last detected as sent to or from the device, in milliseconds from Epoch time and in UTC timezone

illegalTrafficByFirewallRules fields

Name	Type	Nullable / Not nullable	List of values
server	String	Nullable	Server IP address
client	String	Nullable	Client IP address
port	Numeric	Nullable	The server port
transport	String	Nullable	`TCP`, `UDP`, or `ICMP`

weakFirewallRules fields

Name	Type	Nullable / Not nullable	List of values
sources	JSON array of sources	Nullable	JSON array of sources in any of the following formats: - `Any` - `ip address (host)` - `from ip-to ip (RANGE)` - `ip address, subnet mask (NETWORK)`
destinations	JSON array of destinations	Nullable	JSON array of destination objects, in any of the following formats: - `Any` - `ip address (host)` - `from ip-to ip (RANGE)` - `ip address, subnet mask (NETWORK)`
ports	JSON array of ports	Nullable	JSON array of port objects, in any of the following formats: - `Any` - `port (protocol, if detected)` - `from port-to port (protocol, if detected)`

accessPoints fields

Name	Type	Nullable / Not nullable	List of values
macAddress	String	Nullable	The access point's MAC address
vendor	String	Nullable	The access point's vendor name
ipAddress	String	Nullable	The access point's IP address, or N/A
name	String	Nullable	The access point's device name, or N/A
wireless	String	Nullable	Whether the access point is connected to a wireless network: `No`, `Suspected`, or `Yes`

connectionsBetweenSubnets fields

Name	Type	Nullable / Not nullable	List of values
server	String	Nullable	The server's IP address
client	String	Nullable	The client's IP address

industrialMalwareIndicators fields

Name	Type	Nullable / Not nullable	List of values
detectionTime	Numeric	Nullable	Timestamp the malware was first detected, in milliseconds from Epoch time and in UTC timezone
alertMessage	String	Nullable	The alert message sent
description	String	Nullable	The alert message description
devices	JSON array	Not nullable	A JSON array of strings representing device names

internetConnections fields

Name	Type	Nullable / Not nullable	List of values
internalAddress	String	Nullable	The connection's internal IP address
authorized	Boolean	Nullable	`Yes` or `No`
externalAddresses	JSON array	Not nullable	A JSON array of the connection's external IP addresses

Response example

{
    "unauthorizedDevices": [
        {
            "address": "10.2.1.14",
            "name": "PLC \#14",
            "firstDetectionTime": 1462645483000,
            "lastSeen": 1462645495000,
        }
    ],
    "redundantFirewallRules": [
        {
            "sources": "170.39.3.0/255.255.255.0",
            "destinations": "Any",
            "ports": "102"
        }
    ],
    "connectionsBetweenSubnets": [
        {
            "server": "10.2.1.22",
            "client": "170.39.2.0"
        }
    ],
    "industrialMalwareIndications": [
        {
            "detectionTime": 1462645483000,
            "alertMessage": "Suspicion of Malicious Activity (Regin)",
            "description": "Suspicious network activity was detected. Such behavior might be attributed to the Regin malware.",
            "addresses": [
                "10.2.1.4",
                "10.2.1.5"
            ]
        }
    ],
    "illegalTrafficByFirewallRules": [
        {
            "server": "10.2.1.7",
            "port": "20000",
            "client": "10.2.1.4",
            "transport": "TCP"
        },
        {
            "server": "10.2.1.8",
            "port": "20000",
            "client": "10.2.1.4",
            "transport": "TCP"
        },
        {
            "server": "10.2.1.9",
            "port": "20000",
            "client": "10.2.1.4",
            "transport": "TCP"
        }
    ],
    "internetConnections": [
        {
            "internalAddress": "10.2.1.1",
            "authorized": "Yes",
            "externalAddresses": ["10.2.1.2",”10.2.1.3”]
        }
    ],
    "accessPoints": [
        {
            "macAddress": "ec:08:6b:0f:1e:22",
            "vendor": "TP-LINK TECHNOLOGIES",
            "ipAddress": "173.194.112.22",
            "name": "Enterprise AP",
            "wireless": "Yes"
        }
    ],
    "weakFirewallRules": [
        {
            "sources": "170.39.3.0/255.255.255.0",
            "destinations": "Any",
            "ports": "102"
        }
    ]
}

Type: GET

APIs:

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/reports/vulnerabilities/security

Example:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/reports/vulnerabilities/security

operational (Retrieve operational vulnerabilities)

Use this API to request results of a general vulnerability assessment. This assessment provides insight into the operational status of your network. It's based on general network and system information and not on a specific device evaluation.

URI: /api/v1/reports/vulnerabilities/operational

GET

This API is called without any request parameters.

Type: JSON representation of one or more data tables, each with specific and potentially different structures.

The response is displayed in a map view, which maps table titles to table rows. Rows are represented as a list of objects with the same structures.

backupServer result fields

Name	Type	Nullable / Not nullable	List of values
source	String	Nullable	The source IP address
destination	String	Nullable	The destination IP address
port	Numeric	Nullable	The backup server port
transport	String	Nullable	The backup server transport protocol `TCP` or `UDP`
backupMaximalInterval	String	Nullable	The maximum interval time between backups
lastSeenBackup	Numeric	Nullable	Timestamp that a backup was last seen, in milliseconds from Epoch time and in UTC timezone

ipNetworks result fields

Name	Type	Nullable / Not nullable	List of values
addresses	Numeric	Not nullable	The number of IP addresses discovered in the subnet range.
network	String	Not nullable	The subnet base IP address.
mask	String	Not nullable	The subnet mask.

protocolProblems result fields

Name	Type	Nullable / Not nullable	List of values
protocol	String	Not nullable	A protocol for which a protocol violation alert was triggered
addresses	JSON array of IP addresses	Not nullable	JSON array of IP addresses where the violation originated
alert	String	Not nullable	The title of the alert triggered
reportTime	Numeric	Not nullable	Timestamp that a report was last generated, in milliseconds from Epoch time and in UTC timezone

protocolDataVolumes result fields

Name	Type	Nullable / Not nullable	List of values
protocol	String	Nullable	A protocol that was detected on the network by the OT network sensor
volume	String	Nullable	The volume of protocol packets captured by the OT network sensor, in MB

disconnections result fields

Name	Type	Nullable / Not nullable	List of values
assetAddress	String	Nullable	The IP address of the disconnected asset
assetName	String	Nullable	The name of the disconnected asset
lastDetectionTime	Numeric	Nullable	Timestamp that the disconnect was last detected, in milliseconds from Epoch time and in UTC timezone
backToNormalTime	Numeric	Nullable	Timestamp that the connection returned, in milliseconds from Epoch time and in UTC timezone

Response example

{
    "backupServer": [
        {
            "backupMaximalInterval": "1 Hour, 29 Minutes",
            "source": "10.2.1.22",
            "destination": "170.39.2.14",
            "port": 10000,
            "transport": "TCP",
            "lastSeenBackup": 1462645483000
        }
    ],
    "ipNetworks": [
        {
            "addresses": "21",
            "network": "10.2.1.0",
            "mask": "255.255.255.0"
        },
        {
            "addresses": "3",
            "network": "170.39.2.0",
            "mask": "255.255.255.0"
        }
    ],
    "protocolProblems": [
        {
            "protocol": "DNP3",
            "addresses": [
                "10.2.1.7",
                "10.2.1.8"
            ],
            "alert": "Illegal DNP3 Operation",
            "reportTime": 1462645483000
        },
        {
            "protocol": "DNP3",
            "addresses": [
                "10.2.1.15"
            ],
            "alert": "Master Requested an Application Layer Confirmation",
            "reportTime": 1462645483000
        }
    ],
    "protocolDataVolumes": [
        {
            "protocol": "MODBUS (502)",
            "volume": "21.07 MB"
        },
        {
            "protocol": "SSH (22)",
            "volume": "0.001 MB"
        }
    ],
    "disconnections": [
        {
            "assetAddress": "10.2.1.3",
            "assetName": "PLC \#3",
            "lastDetectionTime": 1462645483000,
            "backToNormalTime": 1462645484000
        }
    ]
}

Type: GET

APIs:

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/reports/vulnerabilities/operational

Example:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/reports/vulnerabilities/operational

mitigation (Retrieve mitigation steps)

Use this API to request a mitigation assessment. This assessment provides recommended steps for mitigating detected vulnerabilities. It's based on general network and system information and not on a specific device evaluation.

URI: /api/v1/reports/vulnerabilities/mitigation

GET

This API is called without any request parameters.

Type: JSON

JSON object that represents recommended mitigation steps.

Response fields

Field name	Type	Nullable	List of values
notifications	JSON array of strings	Not nullable	Recommended mitigation steps for detected vulnerabilities
mitigation	JSON array	Not nullable	mitigation objects

mitigation fields

Field name	Type	Nullable	List of values
content	String	Not nullable	Recommended mitigation steps for detected vulnerabilities
scoreImprovement	Integer	Nullable	Expected percentage of security improvement after mitigation steps are taken.
details	Table	Nullable	A table listing mitigation recommendations, such as would be generated in the Risk assessment report. Each recommendation includes details about possible security impact if the action is performed and more. For more information, see Risk mitigation.

Note

You might have multiple mitigation steps, with some returned in the notifications field, and others returned in the mitigation field. Items with scoreImprovement and details data is returned only in the mitigation field. Items without scoreImprovement and details data is returned only in the notifications field.

Response example

{
    "notifications": ["Firewall policy import", "Marking \"important devices\"", "Further device information import"],
    "mitigation": [{
        "content": "Install an Antivirus solution to increase protection of the workstations",
        "details": null,
        "scoreImprovement": 10
    }, {
        "content": "Investigate all malware indicators (Contact your incident response team or support.microsoft.com). When assured the problem is solved, acknowledge the alert",
        "details": {
            "name": "",
            "description": {
                "name": "",
                "important": false,
                "warning": false
            },
            "headers": ["Detection Time", "Alert Message", "Description", "Devices"],
            "rows": [
                ["03/10/2022 07:10:24", "Address Scan Detected", "Address scan detected.\nScanning address: 10.10.10.22\nScanned subnet: 10.11.0.0/16\nScanned addresses: 10.11.1.1, 10.11.20.1, 10.11.20.10, 10.11.20.100, 10.11.20.2, 10.11.20.3, 10.11.20.4, 10.11.20.5, 10.11.20.6, 10.11.20.7...\nIt is recommended to notify the security officer of the incident.", ""],
            ]
        },
        "scoreImprovement": 8
    }, {
        "content": "Install a backup server in the network",
        "details": null,
        "scoreImprovement": 5
    }, {
        "content": "Install latest security updates (Devices: 2)",
        "details": {
            "name": "",
            "description": {
                "name": "",
                "important": false,
                "warning": false
            },
            "headers": ["Name", "Address"],
            "rows": [
                ["10.13.10.5", "10.13.10.5"],
                ["192.168.1.127", "192.168.1.127"]
            ]
        },
        "scoreImprovement": 2
    }, {
        "content": "Increase password complexity for authentication (Devices: 53)",
        "details": {
            "name": "",
            "description": {
                "name": "",
                "important": false,
                "warning": false
            },
            "headers": ["Name", "Address"],
            "rows": [
                ["10.10.10.13", "10.10.10.13"],
                ["10.10.10.14", "10.10.10.14"],
                ["10.10.10.15", "10.10.10.15"],
                ["10.13.10.3", "10.13.10.3"],
                ["10.13.10.40", "10.13.10.40"],
                ["10.13.10.5", "10.13.10.5"],
                ["10.13.11.2", "10.13.11.2"],
                ["10.13.11.3", "10.13.11.3"],
                ["192.168.1.100", "192.168.1.100"],
                ["192.168.1.242", "192.168.1.242"]
            ]
        },
        "scoreImprovement": 2
    }, {
        "content": "Investigate and acknowledge all unacknowledge alerts",
        "details": {
            "name": "",
            "description": {
                "name": "",
                "important": false,
                "warning": false
            },
            "headers": ["Detection Time", "Alert Message", "Description"],
            "rows": [
                ["03/10/2022 07:10:24", "Address Scan Detected", "Address scan detected.\nScanning address: 10.10.10.22\nScanned subnet: 10.11.0.0/16\nScanned addresses: 10.11.1.1, 10.11.20.1, 10.11.20.10, 10.11.20.100, 10.11.20.2, 10.11.20.3, 10.11.20.4, 10.11.20.5, 10.11.20.6, 10.11.20.7...\nIt is recommended to notify the security officer of the incident."],
                ["03/10/2022 07:44:52", "No Traffic Detected on Sensor Interface", "The sensor stopped detecting network traffic on local_listener."]
            ]
        },
        "scoreImprovement": 1
    }]
}

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" "https://<IP address>/api/v1/reports/vulnerabilities/mitigation"

Next steps

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

Feedback

Was this page helpful?

Share via

Vulnerability management API reference for OT monitoring sensors

devices (Retrieve device vulnerability information)

GET

security (Retrieve security vulnerabilities)

GET

operational (Retrieve operational vulnerabilities)

GET

mitigation (Retrieve mitigation steps)

GET

Next steps

Feedback

Additional resources