Vulnerability management API reference for OT monitoring sensors
- Article
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 on-premises management console.
Use this API to request vulnerability assessment results for each device.
URI: /api/v1/reports/vulnerabilities/devices
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.
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 | - |
Name | Type | Nullable / Not nullable | List of values |
---|---|---|---|
name | String | Not nullable | - |
type | String | Not nullable | - |
version | String | Nullable | - |
latestVersion | String | Nullable | - |
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 |
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 |
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 |
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 |
Name | Type | Nullable / Not nullable | List of values |
---|---|---|---|
id | String | Not nullable | - |
score | Numeric, decimal value | Not nullable | - |
description | String | Not nullable | - |
[
{
"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
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
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.
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 |
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 |
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) |
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 |
Name | Type | Nullable / Not nullable | List of values |
---|---|---|---|
server | String | Nullable | The server's IP address |
client | String | Nullable | The client's IP address |
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 |
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 |
{
"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
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
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.
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 |
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. |
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 |
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 |
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 |
{
"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
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
This API is called without any request parameters.
Type: JSON
JSON object that represents recommended mitigation steps.
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 |
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.
{
"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"
For more information, see the Defender for IoT API reference overview.
Feedback
Was this page helpful?