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

OT 监视传感器的警报管理 API 参考

本文列出了 Microsoft Defender for IoT OT 监视传感器支持的警报管理 REST API。

警报（检索警报信息）

使用此 API 可请求已检测到 IoT 传感器的所有警报的列表。

URI：/api/v1/alerts

GET

请求

查询参数

名称	说明	示例	必需/可选
State	仅获取已处理或未处理的警报。 支持的值： - handled - unhandled	/api/v1/alerts?state=handled	可选
fromTime	获取从给定时间开始创建的警报，以毫秒为单位，采用 Epoch 时间和 UTC 时区。	/api/v1/alerts?fromTime=<epoch>	可选
toTime	获取仅在给定时间之前创建的警报，以毫秒为单位，采用 Epoch 时间和 UTC 时区。	/api/v1/alerts?toTime=<epoch>	可选
type	仅获取特定类型的警报。 支持的值： - unexpected new devices - disconnections 所有其他值都被忽略。	/api/v1/alerts?type=disconnections	可选

响应

类型：JSON

包含以下字段的警报列表：

名称	类型	可为空/不可为 null	值列表
ID	Numeric	不可为 null	-
time	Numeric	不可为 null	采用 Epoch 时间和 UTC 时区的毫秒数
title	字符串	不可为 null	-
message	String	不可为 null	-
severity	字符串	不可为 null	Warning、Minor、Major 或 Critical
engine	字符串	不可为 null	Protocol Violation、Policy Violation、Malware、Anomaly 或 Operational
sourceDevice	Numeric	Nullable	设备 ID
destinationDevice	Numeric	Nullable	设备 ID
additionalInformation	其他信息对象	Nullable	-

其他信息字段

名称	类型	可为空/不可为 null	值列表
description	字符串	不可为 null	-
information	JSON 数组	不可为 null	String

已为 V2 添加：

名称	类型	可为空/不可为 null	值列表
sourceDeviceAddress	String	Nullable	IP 或 MAC 地址
destinationDeviceAddress	String	Nullable	IP 或 MAC 地址
remediationSteps	JSON 数组	不可为 null	字符串，警报中所述的修正步骤

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

响应示例

[
    {
        "engine": "Policy Violation",
        "severity": "Major",
        "title": "Internet Access Detected",
        "additionalinformation": {
            "information": [
                "170.60.50.201 over port BACnet (47808)"
            ],
            "description": "External Addresses"
        },
        "sourceDevice": null,
        "destinationDevice": null,
        "time": 1509881077000,
        "message": "Device 192.168.0.13 tried to access an external IP address which is an address in the Internet and is not allowed by policy. It is recommended to notify the security officer of the incident.",
        "id": 1
    },
    {
        "engine": "Protocol Violation",
        "severity": "Major",
        "title": "Illegal MODBUS Operation (Exception Raised by Master)",
        "sourceDevice": 3,
        "destinationDevice": 4,
        "time": 1505651605000,
        "message": "A MODBUS master 192.168.110.131 attempted to initiate an illegal operation.\nThe operation is considered to be illegal since it incorporated function code \#129 which should not be used by a master.\nIt is recommended to notify the security officer of the incident.",
        "id": 2,
        "additionalInformation": null,
    }
]

cURL 命令

类型：GET

API：

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/alerts?state=<STATE>&fromTime=<FROM_TIME>&toTime=<TO_TIME>&type=<TYPE>'

示例：

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/alerts?state=unhandled&fromTime=1594550986000&toTime=1594550986001&type=disconnections'

事件（检索时间线事件）

使用此 API 可请求向事件时间线报告的事件列表。

注意

在同一小时内使用完全相同的参数值运行相同的 API，会返回一个缓存值。 如果在一小时内运行此 API 两次，建议修改查询参数以获取更新的响应。

URI：/api/v1/events

GET

请求

查询参数

名称	说明	示例	必需/可选
minutesTimeFrame	按报告事件的给定时间范围筛选结果。 从当前时间向后定义。 最大值 = 4320（3 天）。 任何更大的值都看作 4320，没有错误	/api/v1/events?minutesTimeFrame=20	可选
type	仅筛选特定类型的结果。 忽略除支持类型以外的任何值。 有关详细信息，请参阅事件 type 和 title 参考。	/api/v1/events?type=DEVICE_CONNECTION_CREATED /api/v1/events?type=REMOTE_ACCESS&minutesTimeFrame	可选

响应

类型：JSON

表示最新 100 个事件的 JSON 对象的数组，按事件时间戳排序，最新事件在前。

事件字段包括：

名称	类型	可为空/不可为 null	值列表
timestamp	Numeric	不可为 null	采用 Epoch 时间和 UTC 时区的毫秒数
type	字符串	不可为 null	支持的类型之一
title	字符串	不可为 null	支持的标题之一
severity	字符串	不可为 null	INFO、NOTICE 或 ALERT
所有者	字符串	Nullable	字符串。 如果事件是手动创建的，则此字段将包含创建该事件的用户名。
content	字符串	不可为 null	描述事件的字符串。

响应示例

[
    {
        "severity": "INFO",
        "title": "Back to Normal",
        "timestamp": 1504097077000,
        "content": "Device 10.2.1.15 was found responsive, after being suspected as disconnected",
        "owner": null,
        "type": "BACK_TO_NORMAL"
    },
    {
        "severity": "ALERT",
        "title": "Alert Detected",
        "timestamp": 1504096909000,
        "content": "Device 10.2.1.15 is suspected to be disconnected (unresponsive).",
        "owner": null,
        "type": "ALERT_REPORTED"
    },
    {
        "severity": "ALERT",
        "title": "Alert Detected",
        "timestamp": 1504094446000,
        "content": "A DNP3 Master 10.2.1.14 attempted to initiate a request which is not allowed by policy.\nThe policy indicates the allowed function codes, address ranges, point indexes and time intervals.\nIt is recommended to notify the security officer of the incident.",
        "owner": null,
        "type": "ALERT_REPORTED"
    },
    {
        "severity": "NOTICE",
        "title": "PLC Program Update",
        "timestamp": 1504094344000,
        "content": "Program update detected, sent from 10.2.1.25 to 10.2.1.14",
        "owner": null,
        "type": "PROGRAM_DEVICE"
    }
]

cURL 命令

类型：GET

API：

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/events?minutesTimeFrame=<TIME_FRAEM>&type=<TYPE>'

示例：

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/events?minutesTimeFrame=20&type=DEVICE_CONNECTION_CREATED'`

事件 type 和 title 参考

本部分列出了支持的值作为 events API 的事件类型和标题值。

事件类型	活动标题
DEVICE_CREATE	检测到的设备
DEVICE_UPDATE	已更新设备
ALERT_REPORTED	检测到警报
ALERT_UPDATED	已更新警报
扫描	检测到扫描设备
PROGRAM_DEVICE	PLC 编程
MMS_PROGRAM_DEVICE	PLC 程序更新
SCL_UPLOADED	已上传 SCL
EXCLUSION_RULE_CREATED	已创建排除规则
EXCLUSION_RULE_REMOVED	已删除排除规则
EXCLUSION_RULE_UPDATED	已更新排除规则
DEVICE_CONNECTION_CREATED	检测到设备连接
USER_LOGIN	用户登录尝试
FILE_TRANSFER	检测到文件传输
CUSTOM_EVENT	用户定义事件
REMOTE_ACCESS	已建立远程访问连接
BACK_TO_NORMAL	恢复正常
MMS_MEMORY_BLOCK_OPERATION	MMS 内存块操作
MMS_PROGRAM_OPERATION	MMS 程序操作
HTTP_BASIC_AUTHENTICATION	HTTP 基本身份验证
SIEMENS_S_7_MEMORY_BLOCK_OPERATION	Siemens S7 内存块操作
SIEMENS_S_7_AUTHENTICATION	Siemens S7 身份验证
REPORT_CREATED	已创建报表
SNMP_TRAP	检测到 SNMP 陷阱
DATABASE_ACTION	数据库结构操作
PLC_MODULE_CHANGE	PLC 模块更改
FIRMWARE_UPDATE	固件更新
PLC_START	PLC 启动
SRTP_PLC_RESET	PLC 重置
SRTP_PLC_COPY_FIRMWARE	固件更新
SRTP_LOGIN_PROGRAMMING	PLC 编程模式集
SRTP_PLC_CHANGE_PASSWORD	PLC 密码更改
OPC_DATA_ACCESS_GROUP_MANAGEMENT_OPERATION	OPC 数据访问组管理操作
OPC_DATA_ACCESS_ITEM_MANAGEMENT_OPERATION	OPC 数据访问项管理操作
OPC_DATA_ACCESS_IO_SUBSCRIPTION_MANAGEMENT_OPERATION	OPC 数据访问 IO 订阅管理操作
OPC_AE_EVENT_SUBSCRIPTION	OPC AE 事件订阅
OPC_AE_EVENT_CONDITION_MANAGEMENT_OPERATION	OPC AE 事件条件管理操作
OPC_AE_EVENT	OPC AE 事件
SRTP_CHANGE_PRIVILEGE	PLC 更改访问级别
SRTP_CHANGE_LEVEL_FAILED	PLC 更改访问级别失败
SUITELINK_INIT_CONNECTION	已初始化 Wonderware 会话
USER_OPERATION	用户操作
DIP_UPLOADED	已上传 Data Intelligence 包
FTP_AUTHENTICATION_FAILURE	FTP 身份验证失败
PROFINET_DPC_VALUE_SET	Profinet 设置操作
S7PLUS_PLC_MODE_CHANGE	PLC 模式更改
S7_PLC_MODE_CHANGE	PLC 模式更改
DELETE_DEVICE	已删除设备
S7PLUS_PROGRAMMING	PLC 编程
FIRMWARE_CHANGED	已更改 PLC 固件
DELTAV_PROGRAMMING	DeltaV 安装脚本
USER_DEFINED_RULE_CREATED	已创建用户定义规则
USER_DEFINED_RULE_EDITED	已编辑用户定义规则
USER_DEFINED_RULE_DELETED	已删除用户定义规则
USER_DEFINED_RULE_OPERATION	用户定义规则操作
REMOTE_PROCESS_EXECUTION	远程进程执行
DEVICE_UNIFICATION	已更新设备
通知	已手动解决通知
ENIP_CONTROLLER_PROGRAM_DELETE	控制器程序删除
ENIP_CONTROLLER_PROGRAM_RESET	控制器程序重置
ENIP_CONTROLLER_GENERIC_RESET	控制器重置
ENIP_CONTROLLER_GENERIC_STOP	控制器停止
ENIP_CONTROLLER_GENERIC_START	控制器启动
TELNET_AUTHENTICATION_FAILURE	Telnet 身份验证失败
CONFIGURATION_OF_CLEARTEXT_PASSWORD	明文密码配置
CLEARTEXT_AUTHENTICATION	明文身份验证
PROGRAM_UPLOAD_DEVICE	PLC 程序上传
CONFIGURATION_CHANGE	PLC 配置写入
CONFIGURATION_READ	PLC 配置读取
SYSLOG_MSG	Syslog 消息
INTERNET_ACCESS	Internet 访问
CAMP_MEMORY_WRITE_OPERATION	通用 ASCII 消息协议内存写入操作
MUTED_ALERT	检测到但已屏蔽的事件
DHCP_UPDATE	地址更新
DIP_FAILURE	Data Intelligence 包安装失败
DELETE_DEVICE_SCHEDULE	计划删除的非活动设备
PLC_OPERATING_MODE_CHANGED	已检测到 PLC 操作模式更改
HARDWARE_UPDATE_BY_IDENTIFIER	地址更新

后续步骤

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