OT 監視感應器的庫存管理 API 參考

本文列出適用于 IoT OT 感應器的 Defender 支援的裝置清查管理 API。

連線 （擷取裝置連線資訊）

使用此 API 來要求所有裝置連線的清單。

URI ： /api/v1/devices/connections

GET

要求

查詢參數

定義下列任何查詢參數，以篩選傳回的結果。 如果您未設定查詢參數，則會傳回所有裝置連線。

名稱	描述:	範例	必要/ 選擇性
discoveredBefore	數位。 篩選在指定時間之前偵測到的結果，其中指定的時間是以 Epoch 時間 及 UTC 時區的毫秒 為單位來定義。	/api/v1/devices/2/connections?discoveredBefore=<epoch>	選擇性
discoveredAfter	數位。 篩選在指定時間之後偵測到的結果，其中指定的時間是以 Epoch 時間 及 UTC 時區的毫秒 為單位來定義。	/api/v1/devices/2/connections?discoveredAfter=<epoch>	選擇性
lastActiveInMinutes	數位。 依作用中連線的指定時間範圍來篩選結果。 從目前時間向後定義，以分鐘為單位。	/api/v1/devices/2/connections?lastActiveInMinutes=20	選擇性

回應

回應類型 ：JSON

代表裝置連線的 JSON 物件陣列，或下列失敗訊息：

訊息	描述
失敗 – 錯誤	作業失敗

成功回應欄位

名稱	類型	可為 Null/ 不可為 Null	值清單
firstDeviceId	數值	不可為 Null	-
secondDeviceId	數值	不可為 Null	-
lastSeen	數值	不可為 Null	Epoch （UTC）
發現	數值	不可為 Null	Epoch （UTC）
港口	數位陣列	Nullable	-
協定	JSON 陣列	Nullable	通訊協定欄位

通訊協定欄位

名稱	類型	可為 Null/ 不可為 Null
name	String	不可為 Null
命令	字串陣列	Nullable

回應範例

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

cURL 命令

類型 ：GET

API ：

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

範例：

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

每個裝置的連線 （擷取特定裝置連線資訊）

使用此 API 來要求每個裝置的所有連線清單。

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

GET

要求

路徑參數

名稱	描述:	範例	必要/ 選擇性
deviceId	取得指定裝置的連線。	/api/v1/devices/<deviceId>/connections	必要

查詢參數

名稱	描述:	範例	必要/ 選擇性
discoveredBefore	數位。 篩選在指定時間之前偵測到的結果，其中指定的時間是以 Epoch 時間 及 UTC 時區的毫秒 為單位來定義。	/api/v1/devices/2/connections?discoveredBefore=<epoch>	選擇性
discoveredAfter	數位。 篩選在指定時間之後偵測到的結果，其中指定的時間是以 Epoch 時間 及 UTC 時區的毫秒 為單位來定義。	/api/v1/devices/2/connections?discoveredAfter=<epoch>	選擇性
lastActiveInMinutes	數位。 依作用中連線的指定時間範圍來篩選結果。 從目前時間向後定義，以分鐘為單位。	/api/v1/devices/2/connections?lastActiveInMinutes=20	選擇性

回應

回應類型 ：JSON

代表裝置連線的 JSON 物件陣列，或下列失敗訊息：

訊息	描述
失敗 – 錯誤	作業失敗

成功回應欄位

名稱	類型	可為 Null/ 不可為 Null	值清單
firstDeviceId	數值	不可為 Null	-
secondDeviceId	數值	不可為 Null	-
lastSeen	數值	不可為 Null	Epoch （UTC）
發現	數值	不可為 Null	Epoch （UTC）
港口	數位陣列	Nullable	-
協定	JSON 陣列	Nullable	通訊協定欄位

通訊協定欄位

名稱	類型	可為 Null/ 不可為 Null
name	String	不可為 Null
命令	字串陣列	Nullable

回應範例

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

cURL 命令

類型 ：GET

API ：

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

範例：

使用指定的查詢參數：

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

cves （擷取 CVE 的相關資訊）

使用此 API 來要求網路上裝置上探索到的所有已知 CVE 清單，依遞減 CVE 分數排序。

URI ： /api/v1/devices/cves

GET

要求

範例： /api/v1/devices/cves

定義下列任何查詢參數，以篩選傳回的結果。

名稱	描述:	範例	必要/ 選擇性
top	數位。 判斷每個裝置 IP 位址要取得多少最高評分的 CVE。	/api/v1/devices/cves?top=50 /api/v1/devices/<ipAddress>/cves?top=50	選擇性。 預設值 = 100

回應

類型 ：JSON

裝置 CVE 物件的 JSON 陣列，或下列失敗訊息：

訊息	描述
失敗 – 錯誤	作業失敗

成功回應欄位

名稱	類型	可為 Null/ 不可為 Null	值清單
cveId	String	不可為 Null	指定 CVE 的標準業界標準識別碼。
ipAddress	String	不可為 Null	IP 位址
得分	String	不可為 Null	CVE 分數，介於 0.0 - 10.0 之間
attackVector	String	不可為 Null	Network、Adjacent Network、Local 或 Physical
description	String	不可為 Null	-

回應範例

[
    {

        "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.\""
    }
]

cURL 命令

類型 ：GET

API ：

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

範例：

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

每個 IP 位址的 cves （擷取 CVE 的特定資訊）

使用此 API 來要求網路上針對特定 IP 位址在裝置上探索到的所有已知 CVE 清單。

URI ： /api/v1/devices/cves

GET

要求

範例： /api/v1/devices/cves

路徑參數

名稱	描述:	範例	必要/ 選擇性
ipAddress	取得指定 IP 位址的 CVE。	/api/v1/devices/<ipAddress>/cves	必要

定義下列查詢參數，以篩選傳回的結果。

名稱	描述:	範例	必要/ 選擇性
top	數位。 判斷每個裝置 IP 位址要取得多少最高評分的 CVE。	/api/v1/devices/cves?top=50 /api/v1/devices/<ipAddress>/cves?top=50	選擇性。 預設值 = 100

回應

類型 ：JSON

裝置 CVE 物件的 JSON 陣列，或下列失敗訊息：

訊息	描述
失敗 – 錯誤	作業失敗

成功回應欄位

名稱	類型	可為 Null/ 不可為 Null	值清單
cveId	String	不可為 Null	指定 CVE 的標準業界標準識別碼。
ipAddress	String	不可為 Null	IP 位址
得分	String	不可為 Null	CVE 分數，介於 0.0 - 10.0 之間
attackVector	String	不可為 Null	Network、Adjacent Network、Local 或 Physical
description	String	不可為 Null	-

回應範例

[
    {

        "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.\""
    }
]

cURL 命令

類型 ：GET

API ：

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

範例：

使用指定的查詢參數：

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

裝置 （擷取裝置資訊）

使用此 API 來要求此感應器偵測到的所有裝置清單。

URI ： api/v1/devices/

GET

要求

查詢參數

定義下列查詢參數，以篩選傳回的結果。 如果您未設定查詢參數，則會傳回所有裝置連線。

名稱	描述:	範例	必要/ 選擇性
授權	布林值： - true：僅篩選授權裝置上的資料。 - false：僅篩選未經授權裝置上的資料。	/api/v1/devices/	選擇性

回應

回應類型 ：JSON

代表裝置物件的 JSON 物件陣列，或下列失敗訊息：

訊息	描述
失敗 – 錯誤	作業失敗

成功回應欄位

名稱	類型	可為 Null/ 不可為 Null	值清單
id	數位。 定義裝置識別碼。	不可為 Null	-
ipAddresses	字串的 JSON 陣列。	Nullable	-
name	字串。 定義裝置名稱。	不可為 Null	-
供應商	字串。 定義裝置的廠商。	Nullable	-
operatingSystem	枚舉。 定義裝置的作業系統。	Nullable	如需詳細資訊，請參閱 支援的 operatingSystem 值 。
macAddresses	字串的 JSON 陣列。	Nullable	-
type	字串。 定義裝置類型。	不可為 Null	可以是 Unknown。 如需詳細資訊，請參閱 支援的型別值 。
engineeringStation	布林值。 定義裝置是否定義為工程站。	不可為 Null	- true：裝置是工程站 - false：裝置不是工程站。
授權	布林值。 定義裝置是否定義為工程站。	不可為 Null	- true：裝置是工程站 - false：裝置不是工程站
掃描器	布林值。 定義裝置是否已獲得授權。	不可為 Null	- true：裝置已獲授權 - false：裝置未獲授權
協定	物件，其中包含裝置的通訊協定詳細資料。	Nullable	如需詳細資訊，請參閱 適用于 IoT 的 Microsoft Defender - 支援的 IoT、OT、ICS 和 SCADA 通訊協定 。
固件	物件的 JSON 陣列 firmware ，該物件不符合裝置的韌體。	不可為 Null	如需詳細資訊，請參閱 支援的韌體欄位 。
hasDynamicAddress	布林值。 定義裝置是否有動態位址。	不可為 Null	- true：裝置具有動態位址 - false：裝置沒有動態位址

operatingSystem支援的值

本節列出 operatingSystem 回應欄位支援的值 。

• 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

type支援的值

本節列出類型 回應欄位的支援值 。

• 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
• Uninterruptable 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

物件和通訊協定 name 值的支援欄位 protocols

本節列出回應欄位中通訊協定 物件的 protocols 支援欄位 。

名稱	類型	可為 Null/ 不可為 Null	值清單
id	數位。 定義通訊協定的內部識別碼。	不可為 Null	-
name	字串。 定義裝置名稱。	不可為 Null	如需詳細資訊，請參閱以下的＜＞。
ipAddresses	通訊協定 IP 位址字串的 JSON 陣列。	不可為 Null	-

下列值支援為 現成的通訊協定名稱 ：

• 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

支援的韌體欄位

本節列出回應欄位中韌體 物件的 firmware 支援欄位 。

名稱	類型	可為 Null/ 不可為 Null	值清單
address	字串。 定義韌體 IP 位址。	不可為 Null	-
moduleAddress	字串。 定義韌體模組位址。	不可為 Null。	-
串列	字串。 定義韌體序號。	Nullable	-
model	字串。 定義韌體模型。	Nullable	-
firmwareVersion	字串。 定義韌體版本。	Nullable	-
additionalData	字串。 定義韌體的其他資料。	Nullable	-
架	字串。 定義韌體機架。	Nullable	-
槽	字串。 定義韌體位置。	Nullable	-

cURL 命令

類型 ：GET

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

下一步

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