本地管理控制台的警报管理 API 参考

项目
06/13/2022

本文列出了Microsoft Defender for IoT 本地管理控制台支持的警报管理 REST API。

警报（检索警报信息）

使用此 API 从本地管理控制台检索所有或筛选的警报。

URI：/external/v1/alerts 或 /external/v2/alerts

获取

查询参数：

名字	描述	例	必需/可选
状态	仅获取已处理或未经处理的警报。支持的值： - `handled` - `unhandled` 将忽略所有其他值。	`/api/v1/alerts?state=handled`	自选
fromTime	获取从给定时间开始、从 Epoch 时间和 UTC 时区开始创建的警报（以毫秒为单位）。	`/api/v1/alerts?fromTime=<epoch>`	自选
toTime	仅在给定时间、Epoch 时间和 UTC 时区之前创建警报（以毫秒为单位）。	`/api/v1/alerts?toTime=<epoch>`	自选
siteId	发现警报的站点。	`/api/v1/alerts?siteId=1`	自选
zoneId	发现警报的区域。	`/api/v1/alerts?zoneId=1`	自选
sensorId	发现警报的传感器。	`/api/v1/alerts?sensorId=1`	自选

注意

你可能没有站点和区域 ID。如果是这种情况，请先查询所有设备以检索站点和区域 ID。有关详细信息，请参阅本地管理控制台（公共预览版）集成 API 参考。

类型： JSON

具有以下字段的警报列表：

名字	类型	可为 Null/不可为 null	值列表
ID	数值的	不可为 null	-
sensorId	数值的	不可为 null	-
zoneId	数值的	不可为 null	-
时间	数值的	不可为 null	以 UTC 时区表示的纪元时间毫秒
游戏	字符串	不可为 null	-
消息	字符串	不可为 null	-
严重性	字符串	不可为 null	`Warning`、`Minor`、`Major`或 `Critical`
引擎	字符串	不可为 null	`Protocol Violation`、`Policy Violation`、`Malware`、`Anomaly`或 `Operational`
sourceDevice	数值的	空	设备 ID
destinationDevice	数值的	空	设备 ID
remediationSteps	字符串	空	警报中显示的修正步骤
additionalInformation	其他信息对象	空	-
处理的	布尔值，警报的状态	不可为 null	`true` 或 `false`

其他信息字段：

名字	类型	可为 Null/不可为 null	值列表
说明	字符串	不可为 null	-
信息	JSON 数组	不可为 null	字符串

为 V2添加了：

名字	类型	可为 Null/不可为 null	值列表
sourceDeviceAddress	字符串	空	IP 或 MAC 地址
destinationDeviceAddress	字符串	空	IP 或 MAC 地址
remediationSteps	JSON 数组	不可为 null	字符串，警报中所述的修正步骤
sensorName	字符串	不可为 null	由用户定义的传感器的名称
zoneName	字符串	不可为 null	与传感器关联的区域的名称
siteName	字符串	不可为 null	与传感器关联的站点的名称

有关详细信息，请参阅传感器 API 版本参考。

响应示例

[
    {
        "engine": "Operational",
        "handled": false,
        "title": "Traffic Detected on sensor Interface",
        "additionalInformation": null,
        "sourceDevice": 0,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808245000,
        "sensorId": 1,
        "message": "The sensor resumed detecting network traffic on ens224.",
        "destinationDevice": 0,
        "id": 1,
        "severity": "Warning"
    },
    {
        "engine": "Anomaly",
        "handled": false,
        "title": "Address Scan Detected",
        "additionalInformation": null,
        "sourceDevice": 4,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808260000,
        "sensorId": 1,
        "message": "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.",
        "destinationDevice": 0,
        "id": 2,
        "severity": "Critical"
    },
    {
        "engine": "Operational",
        "handled": false,
        "title": "Suspicion of Unresponsive MODBUS Device",
        "additionalInformation": null,
        "sourceDevice": 194,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808285000,
        "sensorId": 1,
        "message": "Outstation device 10.13.10.1 (Protocol Address 53) seems to be unresponsive to MODBUS requests.",
        "destinationDevice": 0,
        "id": 3,
        "severity": "Minor"
    }
]

类型：GET

API：

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<>IP_ADDRESS>/external/v1/alerts?state=&zoneId=&fromTime=&toTime=&siteId=&sensor='

示例：

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/alerts?state=unhandled&zoneId=1&fromTime=0&toTime=1594551777000&siteId=1&sensor=1'

UUID （基于 UUID 管理警报）

使用此 API 对 Defender for IoT 检测到的特定警报执行指定操作。

例如，可以使用此 API 创建将数据转发到 QRadar 的转发规则。有关详细信息，请参阅将 Qradar 与 Microsoft Defender for IoT集成。

URI：/external/v1/alerts/<UUID>

放

类型： JSON

查询参数：

名字	描述	例	必需/可选
UUID	为要处理或处理和学习的警报定义通用唯一标识符（UUID）。	`/api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0`	必填

正文参数

名字	描述	例	必需/可选
操作	字符串	`handle` 或 `handleAndLearn`	必填

请求示例

{
    "action": "handle"
}

类型： JSON

表示设备的 JSON 对象的数组。

响应字段：

名字	类型	必需/可选	描述
内容/错误	字符串	必填	如果请求成功，将显示内容属性。否则，将显示错误属性。

可能的内容值：

状态代码	消息	描述
200	警报更新请求成功完成。	更新请求成功完成。无注释。
200	警报已处理（句柄）。	收到警报的句柄请求时，已处理该警报。警报仍处理。
200	警报已处理并已获知（handleAndLearn）。	收到 handleAndLearn 的请求时，已处理并了解警报。警报保留在 handledAndLearn 状态中。
200	警报已处理（处理）。处理和学习（handleAndLearn）是在警报上执行的。	收到 handleAndLearn 的请求时，已处理警报。警报 handleAndLearn。
200	警报已处理并已获知（handleAndLearn）。忽略的句柄请求。	收到处理警报的请求时，警报已 handleAndLearn。警报保持 handleAndLearn。
500	操作无效。	发送的操作不是对警报执行的有效操作。
500	发生意外错误。	发生意外错误。若要解决此问题，请联系技术支持。
500	无法执行请求，因为找不到此 UUID 的警报。	在系统中找不到指定的警报 UUID。

响应示例：成功

{
    "content": "Alert update request finished successfully"
}

响应示例：失败

{
    "error": "Invalid action"
}

类型： PUT

API：

curl -k -X PUT -d '{"action": "<ACTION>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/external/v1/alerts/<UUID>

示例：

curl -k -X PUT -d '{"action": "handle"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/alerts/1-1594550943000

maintenanceWindow （创建警报排除项）

管理维护时段，在该时段下不会发送警报。使用此 API 定义和更新在触发警报时应排除的停止和启动时间、设备或子网，或定义和更新应排除的 Defender for IoT 引擎。

例如，在维护时段内，你可能想要停止所有警报的警报传递，但关键设备上的恶意软件警报除外。

使用 maintenanceWindow API 定义的维护时段将作为只读排除规则显示在本地管理控制台的“警报排除”窗口中，其语法如下：Maintenance-{token name}-{ticket ID}。

重要

此 API 仅用于维护目的和有限的时间段，不应使用，而不是警报排除规则。仅将此 API 用于一次性临时维护操作。

URI：/external/v1/maintenanceWindow

发布

创建新的维护时段。

正文参数：

名字	描述	例	必需/可选
ticketId	字符串。定义用户系统中的维护票证 ID。确保票证 ID 未链接到现有的打开窗口。	`2987345p98234`	必填
ttl	正整数。定义 TTL（生存时间），即维护时段的持续时间（以分钟为单位）。在定义的时间段完成后，维护时段已结束，系统会再次正常运行。	`180`	必填
引擎	字符串的 JSON 数组。定义在维护时段内禁止发出警报的引擎。可能的值： - `ANOMALY` - `MALWARE` - `OPERATIONAL` - `POLICY_VIOLATION` - `PROTOCOL_VIOLATION`	`ANOMALY,OPERATIONAL`	自选
sensorIds	字符串的 JSON 数组。定义要在维护时段内禁止发出警报的传感器。可以从设备（管理 OT 传感器设备） API 获取这些传感器 ID。	`1,35,63`	自选
子网	字符串的 JSON 数组。定义在维护时段内禁止发出警报的子网。在 CIDR 表示法中定义每个子网。	`192.168.0.0/16,138.136.80.0/14,112.138.10.0/8`	自选

状态代码	消息	描述
201 （已创建）	-	操作已成功完成。
400 （错误请求）	No TicketId	API 请求缺少 `ticketId` 值。
400 （错误请求）	非法 TTL	API 请求包括非正值或非数值 TTL 值。
400 （错误请求）	无法分析请求。	分析正文时出现问题，例如不正确的参数或无效值。
400 （错误请求）	已存在具有相同参数的维护时段。	当现有维护时段已存在且具有相同的详细信息时显示。
404 （找不到）	未知传感器 ID	请求中列出的其中一个传感器不存在。
409 （冲突）	票证 ID 已有一个打开的窗口。	票证 ID 链接到另一个打开的维护时段。
500 （内部服务器错误）	-	任何其他意外错误。

类型： POST

API：

curl -k -X POST -d '{"ticketId": "<TICKET_ID>",ttl": <TIME_TO_LIVE>,"engines": [<ENGINE1, ENGINE2...ENGINEn>],"sensorIds": [<SENSOR_ID1, SENSOR_ID2...SENSOR_IDn>],"subnets": [<SUBNET1, SUBNET2....SUBNETn>]}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

示例：

curl -k -X POST -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20","engines": ["ANOMALY"],"sensorIds": ["5","3"],"subnets": ["10.0.0.0/16"]}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

删除

关闭现有维护时段。

查询参数：

名字	描述	例	必需/可选
ticketId	定义用户系统中的维护票证 ID。确保票证 ID 链接到现有的打开窗口。	`2987345p98234`	必填

错误代码：

法典	消息	描述
200 （正常）	-	操作已成功完成。
400 （错误请求）	No TicketId	请求中缺少 ticketId 参数。
404 （找不到）：	找不到维护时段。	票证 ID 未链接到打开的维护时段。
500 （内部服务器错误）	-	任何其他意外错误。

类型： DELETE

API：

curl -k -X DELETE -d '{"ticketId": "<TICKET_ID>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

示例：

curl -k -X DELETE -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

获取

检索已使用此 API 处理维护时段的所有打开（POST）、关闭（DELETE）和更新（PUT）操作的日志。 T

查询参数：

名字	描述	例	必需/可选
fromDate	筛选预定义日期和时间的日志。格式为 `YYYY-MM-DD`。	`2022-08-10`	自选
toDate	将日志筛选为预定义日期。格式为 `YYYY-MM-DD`。	`2022-08-10`	自选
ticketId	筛选与特定票证 ID 相关的日志。	`9a5fe99c-d914-4bda-9332-307384fe40bf`	自选
tokenName	筛选与特定令牌名称相关的日志。	quarterly-sanity-window	自选

错误代码：

法典	消息	描述
200	还行	操作已成功完成。
204：	无内容	没有要显示的数据。
400	请求错误	日期格式不正确。
500	内部服务器错误	任何其他意外错误。

类型： JSON

表示维护时段操作的 JSON 对象的数组。

响应结构：

名字	类型	可为 Null/不可为 null	值列表
id	长整数	不可为 null	当前日志的内部 ID
dateTime	字符串	不可为 null	活动发生的时间，例如：`2022-04-23T18:25:43.511Z`
ticketId	字符串	不可为 null	维护时段 ID。例如：`9a5fe99c-d914-4bda-9332-307384fe40bf`
tokenName	字符串	不可为 null	维护时段令牌名称。例如：`quarterly-sanity-window`
引擎	字符串数组	空	维护时段适用的引擎（在创建维护时段期间提供）：`Protocol Violation`、`Policy Violation`、`Malware`、`Anomaly`或 `Operational`
sensorIds	字符串数组	空	维护时段适用的传感器，在创建维护时段期间提供。
子网	字符串数组	空	维护时段适用的子网，在创建维护时段期间提供。
ttl	数值的	空	维护时段的生存时间（TTL），如维护时段创建或更新期间提供。
operationType	字符串	不可为 null	以下值之一：`OPEN`、`UPDATE`和 `CLOSE`

类型：GET

API：

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v1/maintenanceWindow?fromDate=&toDate=&ticketId=&tokenName='

示例：

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/maintenanceWindow?fromDate=2020-01-01&toDate=2020-07-14&ticketId=a5fe99c-d914-4bda-9332-307384fe40bf&tokenName=a'

放

通过更改 ttl 参数，可以在启动维护过程后更新维护时段持续时间。新的持续时间定义将替代上一个持续时间定义。

如果要设置比当前配置的持续时间更长的持续时间，此方法非常有用。例如，如果最初定义了 180 分钟、90 分钟，并且想要再添加 30 分钟，请将 ttl 更新为 120 分钟以重置持续时间计数。

查询参数：

名字	描述	例	必需/可选
ticketId	字符串。定义用户系统中的维护票证 ID。	`2987345p98234`	必填
ttl	正整数。定义窗口的持续时间（以分钟为单位）。	`210`	必填

错误代码：

法典	消息	描述
200 （正常）	-	操作已成功完成。
400 （错误请求）	No TicketId	请求缺少 `ticketId` 值。
400 （错误请求）	非法 TTL	定义的 TTL 不是数值型整数，也不是正整数。
400 （错误请求）	无法分析请求	请求缺少 `ttl` 参数值。
404 （找不到）	找不到维护时段	票证 ID 未链接到打开的维护时段。
500 （内部服务器错误）	-	任何其他意外错误。

类型： PUT

API：

curl -k -X PUT -d '{"ticketId": "<TICKET_ID>",ttl": "<TIME_TO_LIVE>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

示例：

curl -k -X PUT -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

pcap （请求警报 PCAP）

使用此 API 请求与警报相关的 PCAP 文件。

URI：/external/v2/alerts/

获取

查询参数：

名字	描述	例	必需/可选
id	来自本地管理控制台的警报 ID	`/external/v2/alerts/pcap/<id>`	必填

类型： JSON

包含操作状态详细信息的消息字符串：

状态代码	消息	描述
200 （正常）	-	包含有关所请求 PCAP 文件数据的 JSON 对象。有关详细信息，请参阅数据字段。
500 （内部服务器错误）	找不到警报	在本地管理控制台上找不到提供的警报 ID。
500 （内部服务器错误）	获取 xsense id `<number>` 令牌时出错	获取指定传感器 ID 的传感器令牌时出错
500 （内部服务器错误）	-	任何其他意外错误。

数据字段

名字	类型	可为 Null/不可为 null	值列表
id	数值的	不可为 null	本地管理控制台警报 ID
xsenseId	数值的	不可为 null	传感器 ID
xsenseAlertId	数值的	不可为 null	传感器控制台警报 ID
downloadUrl	字符串	不可为 null	用于下载 PCAP 文件的 URL
令牌	字符串	不可为 null	下载 PCAP 文件时要使用的传感器令牌

响应示例：成功

{
  "downloadUrl": "https://10.1.0.2/api/v2/alerts/pcap/1",
  "xsenseId": 1,
  "token": "d2791f58-2a88-34fd-ae5c-2651fe30a63c",
  "id": 1,
  "xsenseAlertId": 1
}

响应示例：错误

{
  "error": "alert not found"
}

类型：GET

API

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v2/alerts/pcap/<ID>'

* 示例：

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://10.1.0.1/external/v2/alerts/pcap/1'

后续步骤

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

通过

本地管理控制台的警报管理 API 参考

警报（检索警报信息）

获取

UUID （基于 UUID 管理警报）

放

maintenanceWindow （创建警报排除项）

发布

删除

获取

放

pcap （请求警报 PCAP）

获取

后续步骤

其他资源