你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

OT 监视传感器的库存管理 API 参考

2023-06-01

本文列出了 Defender for IoT OT 传感器支持的设备库存管理 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	值列表
firstDeviceId	Numeric	不可为 null	-
secondDeviceId	Numeric	不可为 null	-
lastSeen	Numeric	不可为 null	Epoch (UTC)
discovered	Numeric	不可为 null	Epoch (UTC)
ports	数字数组	Nullable	-
protocols	JSON 数组	Nullable	协议字段

协议字段

名称	类型	可为空/不可为 null
name	字符串	不可为 null
commands	字符串数组	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"
                ]
            }
        ]
    }
]

类型：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	值列表
firstDeviceId	Numeric	不可为 null	-
secondDeviceId	Numeric	不可为 null	-
lastSeen	Numeric	不可为 null	Epoch (UTC)
discovered	Numeric	不可为 null	Epoch (UTC)
ports	数字数组	Nullable	-
protocols	JSON 数组	Nullable	协议字段

协议字段

名称	类型	可为空/不可为 null
name	字符串	不可为 null
commands	字符串数组	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"
                ]
            }
        ]
    }
]

类型：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

cve（检索有关 CVE 的信息）

使用此 API 可请求在网络中的设备上发现的所有已知 CVE 的列表，按 CVE 分数降序排序。

URI：/api/v1/devices/cves

GET

示例：/api/v1/devices/cves

定义以下任何查询参数以筛选返回的结果。

名称	步骤	示例	必需/可选
返回页首	数值。确定要为每个设备 IP 地址获取多少个得分最高的 CVE。	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	可选。默认值 = `100`

类型：JSON

设备 CVE 对象的 JSON 数组，或以下失败消息：

消息	说明
失败 - 错误	操作失败

成功响应字段

名称	类型	可为空/不可为 null	值列表
cveId	字符串	不可为 null	给定 CVE 的行业标准规范 ID。
ipAddress	字符串	不可为 null	IP 地址
score	字符串	不可为 null	CVE 分数，介于 0.0 到 10.0 之间
attackVector	字符串	不可为 null	`Network`、`Adjacent Network`、`Local` 或 `Physical`
description	字符串	不可为 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.\""
    }
]

类型：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 地址的 cve（检索有 CVE 的具体信息）

使用此 API 可请求在网络中的设备上为特定 IP 地址发现的所有已知 CVE 的列表。

URI：/api/v1/devices/cves

GET

示例：/api/v1/devices/cves

路径参数

名称	步骤	示例	必需/可选
ipAddress	获取给定 IP 地址的 CVE。	`/api/v1/devices/<ipAddress>/cves`	必需

定义以下查询参数以筛选返回的结果。

名称	步骤	示例	必需/可选
返回页首	数值。确定要为每个设备 IP 地址获取多少个得分最高的 CVE。	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	可选。默认值 = `100`

类型：JSON

设备 CVE 对象的 JSON 数组，或以下失败消息：

消息	说明
失败 - 错误	操作失败

成功响应字段

名称	类型	可为空/不可为 null	值列表
cveId	字符串	不可为 null	给定 CVE 的行业标准规范 ID。
ipAddress	字符串	不可为 null	IP 地址
score	字符串	不可为 null	CVE 分数，介于 0.0 到 10.0 之间
attackVector	字符串	不可为 null	`Network`、`Adjacent Network`、`Local` 或 `Physical`
description	字符串	不可为 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.\""
    }
]

类型：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	值列表
id	数值。定义设备 ID。	不可为 null	-
ipAddresses	字符串的 JSON 数组。	Nullable	-
name	字符串。定义设备名称。	不可为 null	-
vendor	字符串。定义设备的供应商。	Nullable	-
operatingSystem	枚举。定义设备的操作系统。	Nullable	有关详细信息，请参阅支持的 operatingSystem 值。
macAddresses	字符串的 JSON 数组。	Nullable	-
类型	字符串。定义设备类型。	不可为 null	可以为 `Unknown`。有关详细信息，请参阅支持的 type 值。
engineeringStation	布尔值。定义设备是否定义为工程站。	不可为 null	- `true`：设备是一个工程工作站 - `false`：设备不是工程站。
已授权	布尔值。定义设备是否定义为工程站。	不可为 null	- `true`：设备是一个工程工作站 - `false`：设备不是工程站
扫描程序	布尔值。定义设备是否获得授权。	不可为 null	- `true`：设备已获授权 - `false`：设备未获授权
protocols	包含设备协议详细信息的对象。	Nullable	有关详细信息，请参阅 Microsoft Defender for IoT - 支持的 IoT、OT、ICS 和 SCADA 协议。
firmware	定义设备固件的 `firmware` 对象的 JSON 数组。	不可为 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` 值

本部分列出了 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
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

`protocols` 对象和协议 `name` 值支持的字段

本部分列出了 protocols 响应字段中的 protocols 对象支持的字段。

名称	类型	可为空/不可为 null	值列表
id	数值。定义协议的内部 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 响应字段中的 firmware 对象支持的字段。

名称	类型	可为空/不可为 null	值列表
address	字符串。定义固件 IP 地址。	不可为 null	-
moduleAddress	字符串。定义固件模块地址。	不可为 Null。	-
serial	字符串。定义固件的序列号。	Nullable	-
model	字符串。定义固件模型。	Nullable	-
firmwareVersion	字符串。定义固件版本。	Nullable	-
additionalData	字符串。定义固件的附加数据。	Nullable	-
rack	字符串。定义固件机架。	Nullable	-
slot	字符串。定义固件槽。	Nullable	-

类型：GET

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

后续步骤

有关详细信息，请参阅 Defender for IoT API 参考概述。

通过

OT 监视传感器的库存管理 API 参考

连接（检索设备连接信息）

GET

查询参数

每个设备的连接（检索特定设备连接信息）

GET

路径参数

查询参数

cve（检索有关 CVE 的信息）

GET

每个 IP 地址的 cve（检索有 CVE 的具体信息）

GET

路径参数

设备（检索设备信息）

GET

查询参数

后续步骤

反馈

其他资源