內部部署管理主控台的警示管理 API 參考
本文列出適用於IoT內部部署管理控制台Microsoft Defender 支援的警示管理 REST API。
使用此 API 可從內部部署管理控制台擷取所有或篩選的警示。
URI：/external/v1/alerts 或 /external/v2/alerts
獲取
查詢參數：
| 名字 |
描述 |
例 |
必要/ 選擇性 |
|
狀態 |
只取得已處理或未處理的警示。 支援的值：
- handled
- unhandled
所有其他值都會被忽略。 |
/api/v1/alerts?state=handled |
自選 |
| 從Time |
從指定時間開始，以毫秒為單位，從 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 |
自選 |
注意
您可能沒有網站和區域識別碼。 如果是這種情況，請先查詢所有裝置以擷取月臺和區域標識碼。 如需詳細資訊，請參閱內部部署管理主控台的 整合 API 參考。
類型： JSON
具有下列欄位的警示清單：
| 名字 |
類型 |
可為 Null/ 不可為 Null |
值清單 |
|
識別碼 |
數值的 |
不可為 Null |
- |
|
sensorId |
數值的 |
不可為 Null |
- |
|
zoneId |
數值的 |
不可為 Null |
- |
|
時間 |
數值的 |
不可為 Null |
以UTC時區為單位的 Epoch 時間 毫秒 |
|
標題 |
字串 |
不可為 Null |
- |
|
訊息 |
字串 |
不可為 Null |
- |
|
嚴重性 |
字串 |
不可為 Null |
Warning、Minor、Major或 Critical |
|
引擎 |
字串 |
不可為 Null |
Protocol Violation、Policy Violation、Malware、Anomaly或 Operational |
|
sourceDevice |
數值的 |
空 |
裝置標識碼 |
|
destinationDevice |
數值的 |
空 |
裝置標識碼 |
|
remediationSteps |
字串 |
空 |
警示中顯示的補救步驟 |
|
其他資訊 |
其他信息物件 |
空 |
- |
|
處理 |
布爾值，警示的狀態 |
不可為 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 對適用於 IoT 的 Defender 偵測到的特定警示採取指定動作。
例如，您可以使用此 API 來建立轉送資料至 QRadar 的轉送規則。 如需詳細資訊，請參閱 整合 Qradar 與適用於 IoT 的 Microsoft Defender。
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 來定義和更新觸發警示時應排除的停止和啟動時間、裝置或子網，或定義和更新應排除的 IoT 引擎 Defender。
例如，在維護期間，您可能會想要停止所有警示的警示傳遞，但重要裝置上的惡意代碼警示除外。
使用 maintenanceWindow API 定義的維護時段會出現在內部部署管理主控台的 [警示排除] 視窗中，以下列語法命名為唯讀排除規則：Maintenance-{token name}-{ticket ID}。
重要
此 API 僅支持維護用途，且在有限的期間內，並不適用於警示排除規則。 只針對一次性暫時性維護作業使用此 API。
URI： /external/v1/maintenanceWindow
發佈
建立新的維護期間。
主體參數：
| 名字 |
描述 |
例 |
必要/ 選擇性 |
|
ticketId |
字串。 定義用戶系統中的維護票證標識碼。 請確定票證標識碼未連結至現有的開啟視窗。 |
2987345p98234 |
必填 |
|
ttl |
正整數。 定義 TTL （存留時間），這是維護時段的持續時間，以分鐘為單位。 完成定義的時間週期之後，維護期間就會結束，而且系統會正常運作。 |
180 |
必填 |
|
引擎 |
字串的 JSON 陣列。 定義在維護期間隱藏警示的引擎。 可能的值：
- ANOMALY
- MALWARE
- OPERATIONAL
- POLICY_VIOLATION
- PROTOCOL_VIOLATION |
ANOMALY,OPERATIONAL |
自選 |
|
sensorIds |
字串的 JSON 陣列。 定義在維護期間隱藏警示的感測器。 您可以從 裝置 （管理 OT 感測器裝置） API 取得這些感測器識別碼。 |
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 （找不到） |
未知的感測器識別碼 |
要求中列出的其中一個感測器不存在。 |
|
409 （衝突） |
票證標識碼已經有開啟的視窗。 |
票證標識碼會連結到另一個開啟的維護時段。 |
|
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 |
定義用戶系統中的維護票證標識碼。 請確定票證標識碼已連結至現有的開啟視窗。 |
2987345p98234 |
必填 |
錯誤碼：
| 法典 |
消息 |
描述 |
|
200 （確定） |
- |
動作已成功完成。 |
|
400 （不正確的要求） |
No TicketId |
要求遺漏 ticketId 參數。 |
|
404 （找不到）： |
找不到維護期間。 |
票證標識碼未連結至開啟的維護期間。 |
|
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
獲取
擷取所有 開啟 的記錄（POST）、關閉DELETE，以及 更新（PUT）動作，這些動作是使用此 API 來處理維護時段。 T
查詢參數：
| 名字 |
描述 |
例 |
必要/ 選擇性 |
| 從Date |
從預先定義的日期和更新版本篩選記錄。 格式為 YYYY-MM-DD。 |
2022-08-10 |
自選 |
|
toDate |
將記錄篩選到預先定義的日期。 格式為 YYYY-MM-DD。 |
2022-08-10 |
自選 |
|
ticketId |
篩選與特定票證標識碼相關的記錄。 |
9a5fe99c-d914-4bda-9332-307384fe40bf |
自選 |
|
tokenName |
篩選與特定令牌名稱相關的記錄。 |
quarterly-sanity-window |
自選 |
錯誤碼：
| 法典 |
消息 |
描述 |
|
200 |
還行 |
動作已成功完成。 |
|
204： |
無內容 |
沒有數據可顯示。 |
|
400 |
不正確的要求 |
日期格式不正確。 |
|
500 |
內部伺服器錯誤 |
任何其他未預期的錯誤。 |
類型： JSON
表示維護時段作業的 JSON 物件陣列。
回應結構：
| 名字 |
類型 |
可為 Null/ 不可為 Null |
值清單 |
|
識別碼 |
長整數 |
不可為 Null |
目前記錄檔的內部識別碼 |
|
dateTime |
字串 |
不可為 Null |
活動發生的時間，例如：2022-04-23T18:25:43.511Z |
|
ticketId |
字串 |
不可為 Null |
維護時段標識碼。 例如：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 |
字串。 定義用戶系統中的維護票證標識碼。 |
2987345p98234 |
必填 |
|
ttl |
正整數。 以分鐘為單位定義視窗的持續時間。 |
210 |
必填 |
錯誤碼：
| 法典 |
消息 |
描述 |
|
200 （確定） |
- |
動作已成功完成。 |
|
400 （不正確的要求） |
No TicketId |
要求遺漏 ticketId 值。 |
|
400 （不正確的要求） |
非法 TTL |
定義的 TTL 不是數值，也不是正整數。 |
|
400 （不正確的要求） |
無法剖析要求 |
要求遺漏 ttl 參數值。 |
|
404 （找不到） |
找不到維護期間 |
票證標識碼未連結至開啟的維護期間。 |
|
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/
獲取
查詢參數：
| 名字 |
描述 |
例 |
必要/ 選擇性 |
|
識別碼 |
來自內部部署管理主控台的警示標識碼 |
/external/v2/alerts/pcap/<id> |
必填 |
類型： JSON
具有作業狀態詳細資料的訊息字串：
| 狀態代碼 |
消息 |
描述 |
|
200 （確定） |
- |
JSON 物件，其中包含所要求PCAP檔案的相關數據。 如需詳細資訊，請參閱 資料欄位。 |
|
500 （內部伺服器錯誤） |
找不到警示 |
在內部部署管理控制臺上找不到提供的警示標識碼。 |
|
500 （內部伺服器錯誤） |
取得 xsense 識別碼 <number> 令牌時發生錯誤 |
取得指定感測器識別碼的感測器令牌時發生錯誤 |
|
500 （內部伺服器錯誤） |
- |
任何其他未預期的錯誤。 |
數據欄位
| 名字 |
類型 |
可為 Null/ 不可為 Null |
值清單 |
|
識別碼 |
數值的 |
不可為 Null |
內部部署管理主控台警示標識碼 |
|
xsenseId |
數值的 |
不可為 Null |
感測器標識碼 |
|
xsenseAlertId |
數值的 |
不可為 Null |
感測器主控台警示標識碼 |
|
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'
後續步驟
如需詳細資訊，請參閱適用於IoT API的 Defender 參考概觀。