Microsoft Defender 全面偵測回應 進階搜捕 API

  • 發行項

適用於：

  • Microsoft Defender XDR

警告

此進階搜捕 API 是功能有限的舊版。 Microsoft Graph 安全性 API 已提供更完整的進階搜捕 API 版本。 請參閱 使用 Microsoft Graph 安全性 API 進行進階搜捕

重要事項

部分資訊與發行前版本產品有關，在正式發行之前可能會實質上進行修改。 Microsoft 對此處提供的資訊，不提供任何明確或隱含的瑕疵擔保。

進階搜捕是一種威脅搜捕工具，會使用特別建構的查詢來檢查 Microsoft Defender 全面偵測回應 中過去 30 天的事件數據。 您可以使用進階搜捕查詢來檢查異常活動、偵測可能的威脅，甚至回應攻擊。 進階搜捕 API 可讓您以程式設計方式查詢事件數據。

配額和資源配置

下列條件與所有查詢相關。

  1. 查詢會探索並傳回過去 30 天的數據。
  2. 結果最多可傳回 100,000 個數據列。
  3. 每個租使用者每分鐘最多可以撥打 45 次電話。 每個租用戶的呼叫數目會根據其大小而有所不同。
  4. 每個租用戶都會根據租使用者大小配置 CPU 資源。 如果租使用者已達到 100% 的已配置資源，直到下一個 15 分鐘週期之後，查詢就會遭到封鎖。 若要避免因耗用量過高而封鎖的查詢，請遵循 優化查詢以避免達到CPU配額中的指引。
  5. 如果單一要求執行超過三分鐘，則會逾時並傳回錯誤。
  6. 429 HTTP 回應碼表示您已依傳送的要求數目或分配的運行時間，達到已配置的 CPU 資源。 閱讀回應本文以瞭解您已達到的限制。

權限

呼叫進階搜捕 API 需要下列其中一個許可權。 若要深入瞭解，包括如何選擇許可權，請參閱存取 Microsoft Defender 全面偵測回應 保護 API。

許可權類型 權限 許可權顯示名稱
應用程式 AdvancedHunting.Read.All 執行進階查詢
委派 (公司或學校帳戶) AdvancedHunting.Read 執行進階查詢

注意事項

使用使用者認證取得權杖時：

  • 用戶必須具有「檢視數據」角色。
  • 用戶必須根據裝置群組設定來存取裝置。

HTTP 要求

POST https://api.security.microsoft.com/api/advancedhunting/run

要求標頭

頁首 值
授權 持有人 {token} 注意： 必要
Content-Type application/json

要求內文

在要求本文中，提供具有下列參數的 JSON 物件：

參數 Type 描述
查詢 Text 要執行的查詢。 (必要)

回應

如果成功，這個方法會傳回 200 OK響應主體中的 QueryResponse 物件。

回應物件包含三個最上層屬性：

  1. 統計數據 - 查詢效能統計數據的字典。
  2. 架構 - 回應的架構，每個數據行的 Name-Type 組清單。
  3. 結果 - 進階搜捕事件的清單。

範例

在下列範例中，用戶會傳送下列查詢，並接收包含 Stats、 Schema和 Results的 API 回應物件。

查詢

{
    "Query":"DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
}

Response 物件

{
    "Stats": {
        "ExecutionTime": 4.621215,
        "resource_usage": {
            "cache": {
                "memory": {
                    "hits": 773461,
                    "misses": 4481,
                    "total": 777942
                },
                "disk": {
                    "hits": 994,
                    "misses": 197,
                    "total": 1191
                }
            },
            "cpu": {
                "user": "00:00:19.0468750",
                "kernel": "00:00:00.0156250",
                "total cpu": "00:00:19.0625000"
            },
            "memory": {
                "peak_per_node": 236822432
            }
        },
        "dataset_statistics": [
            {
                "table_row_count": 2,
                "table_size": 102
            }
        ]
    },
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2020-08-30T06:38:35.7664356Z",
            "FileName": "conhost.exe",
            "InitiatingProcessFileName": "powershell.exe"
        },
        {
            "Timestamp": "2020-08-30T06:38:30.5163363Z",
            "FileName": "conhost.exe",
            "InitiatingProcessFileName": "powershell.exe"
        }
    ]
}

提示

想要深入了解? Engage 技術社群中的 Microsoft 安全性社群：Microsoft Defender 全面偵測回應 技術社群。