Microsoft Defender XDR高级搜寻 API

  • 项目

适用于：

  • Microsoft Defender XDR

警告

此高级搜寻 API 是功能有限的旧版本。 Microsoft Graph 安全 API 中已提供了更全面的高级搜寻 API 版本。 请参阅 使用 Microsoft Graph 安全 API 的高级搜寻

重要

某些信息与预发布的产品有关，在商业发布之前可能有重大修改。 Microsoft 对此处所提供的信息不作任何明示或默示的保证。

高级搜寻是一种威胁搜寻工具，它使用专门构造的查询来检查Microsoft Defender XDR中过去 30 天的事件数据。 可以使用高级搜寻查询来检查异常活动、检测可能的威胁，甚至对攻击做出响应。 高级搜寻 API 允许以编程方式查询事件数据。

配额和资源分配

以下条件与所有查询相关。

  1. 查询浏览并返回过去 30 天的数据。
  2. 结果最多可返回 100,000 行。
  3. 每个租户每分钟最多可以进行 45 次调用。 每个租户的调用次数因大小而异。
  4. 根据租户大小为每个租户分配 CPU 资源。 如果租户在下一个 15 分钟周期之后达到已分配资源的 100% 时，将阻止查询。 若要避免因过度消耗而阻止查询，请遵循 优化查询以避免达到 CPU 配额中的指导。
  5. 如果单个请求运行时间超过三分钟，则会超时并返回错误。
  6. 429 HTTP 响应代码指示已按发送的请求数或分配的运行时间到达分配的 CPU 资源。 阅读响应正文以了解已达到的限制。

权限

调用高级搜寻 API 需要以下权限之一。 若要了解详细信息（包括如何选择权限），请参阅访问Microsoft Defender XDR保护 API。

权限类型 权限 权限显示名称
应用程序 AdvancedHunting.Read.All 运行高级查询
委派（工作或学校帐户） AdvancedHunting.Read 运行高级查询

注意

使用用户凭据获取令牌时：

  • 用户需要具有“查看数据”角色。
  • 用户需要根据设备组设置拥有对设备的访问权限。

HTTP 请求

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

请求标头

标头 值
Authorization 持有者 {token} 注意：必需
Content-Type application/json

请求正文

在请求正文中，提供具有以下参数的 JSON 对象：

参数 类型 说明
查询 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"
}

响应对象

{
    "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 XDR技术社区。