Microsoft 365 Defender 高级搜寻 APIMicrosoft 365 Defender Advanced hunting API

重要

改进的 Microsoft 365 安全中心现在可用。The improved Microsoft 365 security center is now available. 此新体验将 Defender for Endpoint、Defender for Office、365 Microsoft 365 Defender 等引入了 Microsoft 365 安全中心。This new experience brings Defender for Endpoint, Defender for Office 365, Microsoft 365 Defender, and more into the Microsoft 365 security center. 了解新增功能Learn what's new.

适用于:Applies to:

  • Microsoft 365 DefenderMicrosoft 365 Defender

重要

某些信息与预发布的产品有关,在商业发布之前可能有重大修改。Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft 对此处所提供的信息不作任何明示或默示的保证。Microsoft makes no warranties, express or implied, with respect to the information provided here.

高级搜寻是一种威胁搜寻工具,它使用专门构造的查询来检查 Microsoft 365 Defender 中过去 30 天的事件数据。Advanced hunting is a threat-hunting tool that uses specially constructed queries to examine the past 30 days of event data in Microsoft 365 Defender. 可以使用高级搜寻查询来检查异常活动、检测可能的威胁,甚至响应攻击。You can use advanced hunting queries to inspect unusual activity, detect possible threats, and even respond to attacks. 高级搜寻 API 允许你以编程方式查询事件数据。The advanced hunting API allows you to programatically query event data.

配额和资源分配Quotas and resource allocation

下列条件与所有查询相关。The following conditions relate to all queries.

  1. 查询将浏览并返回过去 30 天的数据。Queries explore and return data from the past 30 days.
  2. 结果最多返回 100,000 行。Results can return up to 100,000 rows.
  3. 每个租户每分钟最多可以拨打 15 次呼叫。You can make up to 15 calls per minute per tenant.
  4. 每个租户每小时有 10 分钟的运行时间。You have 10 minutes of running time per hour per tenant.
  5. 每个租户每天的总运行时间为四小时。You have four total hours of running time per day per tenant.
  6. 如果单个请求运行的时间超过 10 分钟,它将退出并返回错误。If a single request runs for more than 10 minutes, it will time out and return an error.
  7. HTTP 响应代码指示你已按发送的请求数或按分配的运行时间 429 达到配额。A 429 HTTP response code indicates that you've reached a quota, either by number of requests sent, or by allotted running time. 阅读响应正文,了解已达到的限制。Read the response body to understand the limit you have reached.

备注

上面列出的所有配额 (例如,每个租户大小每) 15 次呼叫。All quotas listed above (for example 15 calls per min) are per tenant size. 这些配额是最小值。These quotas are the minimum.

权限Permissions

调用高级搜寻 API 需要以下权限之一。One of the following permissions is required to call the advanced hunting API. 若要了解更多信息(包括如何选择权限),请参阅 访问 Microsoft 365 Defender Protection APITo learn more, including how to choose permissions, see Access the Microsoft 365 Defender Protection APIs

权限类型Permission type 权限Permission 权限显示名称Permission display name
应用程序Application AdvancedHunting.Read.AllAdvancedHunting.Read.All 运行高级查询Run advanced queries
委派(工作或学校帐户)Delegated (work or school account) AdvancedHunting.ReadAdvancedHunting.Read 运行高级查询Run advanced queries

备注

使用用户凭据获取令牌时:When obtaining a token using user credentials:

  • 用户需要具有"查看数据"AD 角色The user needs to have the 'View Data' AD role
  • 用户需要基于设备组设置访问设备。The user needs to have access to the device, based on device group settings.

HTTP 请求HTTP request

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

请求标头Request headers

标头Header Value
AuthorizationAuthorization Bearer {token} 注意:必需Bearer {token} Note: required
Content-TypeContent-Type application/jsonapplication/json

请求正文Request body

在请求正文中,提供具有以下参数的 JSON 对象:In the request body, supply a JSON object with the following parameters:

参数Parameter 类型Type 说明Description
查询Query 文本Text 要运行的查询。The query to run. 注意:必需Note: required

响应Response

如果成功,此方法将在响应正文中 200 OK 返回 和 QueryResponse 对象。If successful, this method will return 200 OK, and a QueryResponse object in the response body.

response 对象包含三个顶级属性:The response object contains three top-level properties:

  1. Stats - 查询性能统计信息的字典。Stats - A dictionary of query performance statistics.
  2. Schema - 响应的架构,每个列Name-Type对的列表。Schema - The schema of the response, a list of Name-Type pairs for each column.
  3. 结果 - 高级搜寻事件列表。Results - A list of advanced hunting events.

示例Example

在下面的示例中,用户发送下面的查询并接收包含 、 和 的 API 响应 Stats Schema 对象 ResultsIn the following example, a user sends the query below and receives an API response object containing Stats, Schema, and Results.

查询Query

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

Response 对象Response object

{
    "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"
        }
    ]
}