OT 監視感應器的警示管理 API 參考

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

警示 (擷取警示資訊)

使用此 API 來針對適用於 IoT 的 Defender 感應器，要求其偵測到的所有警示清單。

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/不可為 Null	值清單
識別碼	數值	不可為 Null	-
time	數值	不可為 Null	Epoch 時間的毫秒，以 UTC 時區為單位
title	String	不可為 Null	-
message	String	不可為 Null	-
severity	String	不可為 Null	Warning、Minor、Major 或 Critical
engine	String	不可為 Null	Protocol Violation、Policy Violation、Malware、Anomaly 或 Operational
sourceDevice	數值	Nullable	裝置識別碼
destinationDevice	數值	Nullable	裝置識別碼
additionalInformation	其他資訊物件	Nullable	-

其他資訊欄位

名稱	類型	可為 Null/不可為 Null	值清單
description	String	不可為 Null	-
information	JSON 陣列	不可為 Null	String

已針對 V2 新增：

名稱	類型	可為 Null/不可為 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

JSON 物件的陣列，代表最新的 100 個事件，依事件的時間戳記排序，並優先排序最新的事件。

事件欄位包含：

名稱	類型	可為 Null/不可為 Null	值清單
timestamp	數值	不可為 Null	Epoch 時間的毫秒，以 UTC 時區為單位
type	String	不可為 Null	其中一種支援的類型
title	String	不可為 Null	其中一種支援的標題
severity	String	不可為 Null	INFO、NOTICE 或 ALERT
擁有者	String	Nullable	字串。 如果事件是手動建立的，那麼此欄位將包含建立事件的使用者名稱。
content	String	不可為 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 參考

本節列出事件 API 的事件類型和標題值所支援的值。

事件類型	事件標題
DEVICE_CREATE	已偵測到裝置
DEVICE_UPDATE	已更新裝置
ALERT_REPORTED	已偵測到警示
ALERT_UPDATED	已更新警示
SCAN	已掃描到裝置
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	已上傳的資料情報套件
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	網際網路存取
CAMP_MEMORY_WRITE_OPERATION	常見的 ASCII 訊息通訊協定記憶體寫入作業
MUTED_ALERT	已偵測到事件並設為靜音
DHCP_UPDATE	更新位址
DIP_FAILURE	資料情報套件安裝失敗
DELETE_DEVICE_SCHEDULE	排程刪除的非使用中裝置
PLC_OPERATING_MODE_CHANGED	已偵測到的 PLC 作業模式變更
HARDWARE_UPDATE_BY_IDENTIFIER	更新位址

下一步

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