OT 監視感應器的弱點管理 API 參考

發行項
06/01/2023

本文列出支援適用於 IoT 的 Microsoft Defender 監視感應器的弱點管理 REST API。

API 回應中包含的資料包括與您從內部部署管理主控台產生弱點報告相同的資訊。

devices (擷取裝置弱點資訊)

使用此 API 來要求每個裝置的弱點評估結果。

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

GET

呼叫此 API 不需要任何要求參數。

類型：JSON

表示已評估裝置及其回報弱點的 JSON 物件陣列。

發現沒有弱點的裝置不會包含在結果回應中。

裝置欄位

名稱	類型	可為 Null/不可為 Null	值清單
name	String	不可為 Null	-
ipAddresses	JSON 陣列	不可為 Null	-
securityScore	數值	不可為 Null	-
vendor	String	Nullable
firmwareVersion	String	Nullable	-
model	String	Nullable	-
isWirelessAccessPoint	Boolean	不可為 Null	`True` 或 `False`
operatingSystem	作業系統物件	Nullable	-
vulnerabilities	弱點物件	不可為 Null	-

作業系統欄位

名稱	類型	可為 Null/不可為 Null	值清單
name	String	不可為 Null	-
type	String	不可為 Null	-
version	String	Nullable	-
latestVersion	String	Nullable	-

弱點欄位

名稱	類型	可為 Null/不可為 Null	值清單
antiViruses	字串的 JSON 陣列	Nullable	防毒軟體名稱
plainTextPasswords	JSON 陣列	Nullable	密碼物件
remoteAccess	JSON 陣列	Nullable	遠端存取物件
isBackupServer	Boolean	不可為 Null	`True` 或 `False`
openedPorts	JSON 陣列	Nullable	已開啟連接埠物件
isEngineeringStation	Boolean	不可為 Null	`True` 或 `False`
isKnownScanner	Boolean	不可為 Null	`True` 或 `False`
cves	JSON 陣列	Nullable	CVE 物件
isUnauthorized	Boolean	不可為 Null	`True` 或 `False`
malwareIndicationsDetected	Boolean	不可為 Null	`True` 或 `False`
weakAuthentication	字串的 JSON 陣列	Nullable	偵測到使用弱式驗證的應用程式

密碼欄位

名稱	類型	可為 Null/不可為 Null	值清單
password	String	不可為 Null	-
protocol	String	不可為 Null	-
strength	String	不可為 Null	`Very weak`, `Weak`, `Medium`, `Strong`

遠端存取欄位

名稱	類型	Nullable	值清單
port	數值	不可為 Null	-
transport	String	不可為 Null	`TCP`, `UDP`
client	String	不可為 Null	IP 位址
clientSoftware	String	不可為 Null	遠端通訊協定的名稱，例如 `SSH`、`VNC`、`Remote desktop` 或 `Team viewer`

開放的連接埠欄位

名稱	類型	可為 Null/不可為 Null	值清單
port	數值	不可為 Null	-
transport	String	不可為 Null	`TCP` 或 `UDP`
protocol	String	Nullable	-
isConflictingWithFirewall	Boolean	不可為 Null	`True` 或 `False`

CVE 欄位

名稱	類型	可為 Null/不可為 Null	值清單
id	String	不可為 Null	-
score	數值，小數值	不可為 Null	-
description	String	不可為 Null	-

回應範例

[
    {
        "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
        }
    }
]

類型：GET

API：

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

範例：

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

security (擷取安全性弱點)

使用此 API 來要求一般弱點評量報告的結果。此評量可讓您深入了解系統的安全性層級。

此評量是以一般網路和系統資訊為基礎，且沒有根據特定的裝置評量。

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

GET

呼叫此 API 不需要任何要求參數。

類型：一或多個資料表的 JSON 標記法，每個資料表都有特定且可能不同的結構。

回應會顯示在對應檢視中，它會將表格標題對應至資料表資料列。資料列會以具有相同結構的物件清單表示。

unauthorizedDevices 欄位

名稱	類型	可為 Null/不可為 Null	值清單
address	String	Nullable	未經授權裝置的 IP 或 MAC 位址
name	String	Nullable	未經授權裝置的名稱
firstDetectionTime	數值	Nullable	第一次已偵測到裝置的時間戳記，從 Epoch 時間開始，以毫秒為單位，時區為 UTC
lastSeen	數值	Nullable	上次偵測到流量傳送至裝置或從裝置傳出的時間戳記，從 Epoch 時間開始，以毫秒為單位，時區為 UTC

illegalTrafficByFirewallRules 欄位

名稱	類型	可為 Null/不可為 Null	值清單
伺服器	String	Nullable	伺服器 IP 位址
client	String	Nullable	用戶端 IP 位址
port	數值	Nullable	伺服器連接埠
transport	String	Nullable	`TCP`、`UDP` 或 `ICMP`

weakFirewallRules 欄位

名稱	類型	可為 Null/不可為 Null	值清單
sources	來源的 JSON 陣列	Nullable	下列任何格式的來源 JSON 陣列： - `Any` - `ip address (host)` - `from ip-to ip (RANGE)` - `ip address, subnet mask (NETWORK)`
destinations	目的地的 JSON 陣列	Nullable	目的地物件的 JSON 陣列，格式如下： - `Any` - `ip address (host)` - `from ip-to ip (RANGE)` - `ip address, subnet mask (NETWORK)`
ports	連接埠的 JSON 陣列	Nullable	連接埠物件的 JSON 陣列，格式如下： - `Any` - `port (protocol, if detected)` - `from port-to port (protocol, if detected)`

accessPoints 欄位

名稱	類型	可為 Null/不可為 Null	值清單
macAddress	String	Nullable	存取點的 MAC 位址
vendor	String	Nullable	存取點的廠商名稱
ipAddress	String	Nullable	存取點的 IP 位址或 N/A
name	String	Nullable	存取點的裝置名稱或 N/A
wireless	String	Nullable	無論存取點是否已連線到無線網路：`No`、`Suspected` 或 `Yes`

connectionsBetweenSubnets 欄位

名稱	類型	可為 Null/不可為 Null	值清單
伺服器	String	Nullable	伺服器的 IP 位址
client	String	Nullable	用戶端的 IP 位址

industrialMalwareIndicators 欄位

名稱	類型	可為 Null/不可為 Null	值清單
detectionTime	數值	Nullable	第一次偵測到惡意程式碼的時間戳記，從 Epoch 時間開始，以毫秒為單位，時區為 UTC
alertMessage	String	Nullable	已傳送的警示訊息
description	String	Nullable	警示訊息描述
devices	JSON 陣列	不可為 Null	字串的 JSON 陣列，表示裝置名稱

internetConnections 欄位

名稱	類型	可為 Null/不可為 Null	值清單
internalAddress	String	Nullable	連線的內部 IP 位址
authorized	Boolean	Nullable	`Yes` 或 `No`
externalAddresses	JSON 陣列	不可為 Null	連線外部 IP 位址的 JSON 陣列

回應範例

{
    "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"
        }
    ]
}

類型：GET

API：

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

範例：

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

operational (擷取作業弱點)

使用此 API 來要求一般弱點評量的結果。此評量針對網路作業狀態提供了深入解析。這是以一般網路和系統資訊為基礎的，且沒有根據特定的裝置評量。

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

GET

呼叫此 API 不需要任何要求參數。

類型：一或多個資料表的 JSON 標記法，每個資料表都有特定且可能不同的結構。

回應會顯示在對應檢視中，它會將表格標題對應至資料表資料列。資料列會以具有相同結構的物件清單表示。

backupServer 結果欄位

名稱	類型	可為 Null/不可為 Null	值清單
source	String	Nullable	來源 IP 位址
destination	String	Nullable	目的地 IP 位址
port	數值	Nullable	備份伺服器連接埠
transport	String	Nullable	備份伺服器傳輸通訊協定 `TCP` 或 `UDP`
backupMaximalInterval	String	Nullable	備份之間的間隔時間上限
lastSeenBackup	數值	Nullable	上次看到備份的時間戳記，從 Epoch 時間開始，以毫秒為單位，時區為 UTC

ipNetworks 結果欄位

名稱	類型	可為 Null/不可為 Null	值清單
addresses	數值	不可為 Null	子網路範圍中探索到的 IP 位址數目。
network	String	不可為 Null	子網路基礎 IP 位址。
mask	String	不可為 Null	子網路遮罩。

protocolProblems 結果欄位

名稱	類型	可為 Null/不可為 Null	值清單
protocol	String	不可為 Null	觸發通訊協定違規警示的通訊協定
addresses	IP 位址的 JSON 陣列	不可為 Null	發生違規的 IP 位址 JSON 陣列
alert	String	不可為 Null	觸發的警示標題
reportTime	數值	不可為 Null	上次產生報表的時間戳記，從 Epoch 時間開始，以毫秒為單位，時區為 UTC

protocolDataVolumes 結果欄位

名稱	類型	可為 Null/不可為 Null	值清單
protocol	String	Nullable	OT 網路感應器在網路上偵測到的通訊協定
磁碟區	String	Nullable	OT 網路感應器擷取的通訊協定封包數量，以 MB 為單位

disconnections 結果欄位

名稱	類型	可為 Null/不可為 Null	值清單
assetAddress	String	Nullable	已中斷連線資產的 IP 位址
assetName	String	Nullable	已中斷連線資產的名稱
lastDetectionTime	數值	Nullable	上次偵測到中斷連線的時間戳記，從 Epoch 時間開始，以毫秒為單位，時區為 UTC
backToNormalTime	數值	Nullable	連線傳回的時間戳記，從 Epoch 時間開始，以毫秒為單位，時區為 UTC

回應範例

{
    "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
        }
    ]
}

類型：GET

API：

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

範例：

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

mitigation (擷取風險降低步驟)

使用此 API 以要求風險降低評量。此評量提供降低已偵測到弱點風險的建議步驟。這是以一般網路和系統資訊為基礎的，且沒有根據特定的裝置評量。

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

GET

呼叫此 API 不需要任何要求參數。

類型：JSON

表示建議風險降低步驟的 JSON 物件。

回應欄位

欄位名稱	類型	Nullable	值清單
通知	字串的 JSON 陣列	不可為 Null	對於已偵測到弱點的建議風險降低步驟
風險降低	JSON 陣列	不可為 Null	風險降低物件

mitigation 欄位

欄位名稱	類型	Nullable	值清單
content	String	不可為 Null	對於已偵測到弱點的建議風險降低步驟
scoreImprovement	整數	Nullable	在採取風險降低步驟之後，預期的安全性改進百分比。
details	資料表	Nullable	列出風險降低建議的資料表，例如會在風險評估報告中產生。每個建議包含如果執行動作可能產生的安全性影響的詳細資料。如需詳細資訊，請參閱風險降低。

注意

您可能有多個風險降低步驟，其中一些會在 notifications 欄位中傳回，而其他則會在 mitigation 欄位中傳回。具有 scoreImprovement 和 details 資料的項目只會在 mitigation 欄位中傳回。沒有 scoreImprovement 和 details 資料的項目只會在 notifications 欄位中傳回。

回應範例

{
    "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"

下一步

如需詳細資訊，請參閱適用於 IoT 的 Defender API 參考概觀。

共用方式為

OT 監視感應器的弱點管理 API 參考

devices (擷取裝置弱點資訊)

GET

裝置欄位

作業系統欄位

弱點欄位

密碼欄位

遠端存取欄位

開放的連接埠欄位

CVE 欄位

回應範例

security (擷取安全性弱點)

GET

unauthorizedDevices 欄位

illegalTrafficByFirewallRules 欄位

weakFirewallRules 欄位

accessPoints 欄位

connectionsBetweenSubnets 欄位

industrialMalwareIndicators 欄位

internetConnections 欄位

回應範例

operational (擷取作業弱點)

GET

backupServer 結果欄位

ipNetworks 結果欄位

protocolProblems 結果欄位

protocolDataVolumes 結果欄位

disconnections 結果欄位

回應範例

mitigation (擷取風險降低步驟)

GET

回應欄位

mitigation 欄位

回應範例

下一步

意見反應

其他資源