內部部署管理主控台的警示管理 API 參考

發行項
06/01/2023

本文列出適用於 IoT 的 Microsoft Defender 內部部署管理主控台支援的警示管理 REST API。

警示 (擷取警示資訊)

使用此 API 可從內部部署管理主控台擷取所有或篩選過的警示。

URI：/external/v1/alerts 或 /external/v2/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>`	選擇性
siteId	探索到警示的網站。	`/api/v1/alerts?siteId=1`	選擇性
zoneId	探索到警示的區域。	`/api/v1/alerts?zoneId=1`	選擇性
sensorId	探索到警示的感應器。	`/api/v1/alerts?sensorId=1`	選用

注意

您可能沒有網站和區域識別碼。如果是這種情況，請先查詢所有裝置以擷取網站和區域識別碼。如需詳細資訊，請參閱內部部署管理主控台的整合 API 參考 (公開預覽版)。

類型：JSON

具有下欄欄位的警示清單：

名稱	類型	可為 Null/不可為 Null	值清單
Id	數值	不可為 Null	-
sensorId	數值	不可為 Null	-
zoneId	數值	不可為 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	裝置識別碼
remediationSteps	String	Nullable	警示中顯示的補救步驟
additionalInformation	其他資訊物件	Nullable	-
handled	布林值，警示的狀態	不可為 Null	`true` 或 `false`

其他資訊欄位：

名稱	類型	可為 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	警示中描述的字串、補救步驟
sensorName	String	不可為 Null	使用者所定義的感應器名稱
zoneName	String	不可為 Null	與感應器相關聯的區域名稱
siteName	String	不可為 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>

PUT

類型：JSON

查詢參數：

名稱	描述	範例	必要/選用
UUID	為您要處理或處理和學習的警示定義通用唯一識別碼 (UUID)。	`/api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0`	必要

本文參數

名稱	描述	範例	必要/選用
action	String	`handle` 或 `handleAndLearn`	必要

要求範例

{
    "action": "handle"
}

類型：JSON

代表裝置的 JSON 物件陣列。

回應欄位：

名稱	類型	必要/選用	描述
content / error	String	必要	如果要求成功，內容屬性隨即出現。否則，錯誤屬性隨即出現。

可能的內容值：

狀態碼	訊息	描述
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

POST

建立新的維護期間。

主體參數：

名稱	描述	範例	必要/選用
ticketId	字串。定義使用者系統中的維護票證識別碼。請確定票證識別碼未連結至現有的開啟視窗。	`2987345p98234`	必要
ttl	正整數。定義 TTL (存留時間)，這是維護期間的持續時間，以分鐘為單位。完成定義的時機範圍之後，維護期間就會結束，而且系統會再次正常運作。	`180`	必要
engines	字串的 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 (不正確的要求)	沒有 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

DELETE

關閉現有維護視窗。

查詢參數：

名稱	描述	範例	必要/選用
ticketId	定義使用者系統中的維護票證識別碼。請確定票證識別碼連結至現有的開啟視窗。	`2987345p98234`	必要

錯誤碼：

程式碼	訊息	描述
200 (確定)	-	動作已順利完成。
400 (不正確的要求)	沒有 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

GET

擷取所有使用此 API 處理維護期間時執行的開啟 (POST)、關閉 (DELETE) 和更新 (PUT) 動作記錄。 T

查詢參數：

名稱	描述	範例	必要/選用
fromDate	篩選預先定義日期之後的記錄。格式為 `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	值清單
id	長整數	不可為 Null	目前記錄的內部識別碼
dateTime	String	不可為 Null	活動發生的時間，例如：`2022-04-23T18:25:43.511Z`
ticketId	String	不可為 Null	維護期間識別碼。例如： `9a5fe99c-d914-4bda-9332-307384fe40bf`
tokenName	String	不可為 Null	維護期間權杖名稱。例如： `quarterly-sanity-window`
engines	字串陣列	Nullable	套用維護時段的引擎 (於維護期間建立時提供)：`Protocol Violation`、`Policy Violation`、`Malware`、`Anomaly` 或 `Operational`
sensorIds	字串陣列	Nullable	套用維護時段的感應器 (於維護期間建立時提供)。
子網路	字串陣列	Nullable	套用維護時段的子網路 (於維護期間建立時提供)。
ttl	數值	Nullable	維護時段的存留時間 (於維護期間建立時提供)。
operationType	String	不可為 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'

PUT

可讓您藉由變更 ttl 參數，在啟動維護程序之後更新維護期間的持續時間。新的持續時間定義會覆寫上一個持續時間定義。

當您想要設定的持續時間比目前設定的持續時間還長時，這個方法很有用。例如，如果您原本已定義 180 分鐘，但 90 分鐘過後您想要新增另外 30 分鐘，請將 ttl 更新為 120 分鐘以重設持續時間計數。

查詢參數：

名稱	描述	範例	必要/選用
ticketId	字串。定義使用者系統中的維護票證識別碼。	`2987345p98234`	必要
ttl	正整數。定義維護期間的持續時間 (以分鐘為單位)。	`210`	必要

錯誤碼：

程式碼	訊息	描述
200 (確定)	-	動作已順利完成。
400 (不正確的要求)	沒有 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/

GET

查詢參數：

名稱	描述	範例	必要/選用
id	來自內部部署管理主控台的警示識別碼	`/external/v2/alerts/pcap/<id>`	必要

類型：JSON

含有作業狀態詳細資料的訊息字串：

狀態碼	訊息	描述
200 (確定)	-	JSON 物件，其中包含所要求 PCAP 檔案的相關資料。如需詳細資訊，請參閱資料欄位。
500 (內部伺服器錯誤)	找不到警示	在內部部署管理主控台上找不到提供的警示識別碼。
500 (內部伺服器錯誤)	取得 XSense 識別碼的權杖時發生錯誤 `<number>`	取得指定感應器識別碼的感應器權杖時發生錯誤
500 (內部伺服器錯誤)	-	任何其他未預期的錯誤。

資料欄位

名稱	類型	可為 Null/不可為 Null	值清單
id	數值	不可為 Null	內部部署管理主控台警示識別碼
xsenseId	數值	不可為 Null	感應器識別碼
xsenseAlertId	數值	不可為 Null	感應器主控台警示識別碼
downloadUrl	String	不可為 Null	用來下載 PCAP 檔案的 URL
token	String	不可為 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 的 Defender API 參考概觀。

共用方式為

內部部署管理主控台的警示管理 API 參考

警示 (擷取警示資訊)

GET

回應範例

UUID (根據 UUID 管理警示)

PUT

回應範例：成功

回應範例：失敗

maintenanceWindow (建立警示排除項目)

POST

DELETE

GET

PUT

pcap (要求警示 PCAP)

GET

資料欄位

回應範例：成功

回應範例：錯誤

下一步

意見反應

其他資源