通过

安全性：runHuntingQuery

命名空间：microsoft.graph.security

查询 Microsoft 365 Defender 支持的一组指定事件、活动或实体数据，以主动查找环境中的特定威胁。

此方法适用于 Microsoft 365 Defender 中的高级搜寻。 此方法在 KQL) Kusto 查询语言 (中包含查询。 它指定 高级搜寻架构 中的数据表和管道运算符序列，以筛选或搜索该数据，并按特定方式设置查询输出的格式。

详细了解如何 跨设备、电子邮件、应用和标识搜寻威胁。 了解 KQL。

有关在 Microsoft 365 Defender 门户中使用高级搜寻的信息，请参阅 在 Microsoft 365 Defender 中使用高级搜寻主动搜寻威胁。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ❌

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） ThreatHunting.Read.All 不可用。
委派（个人 Microsoft 帐户） 不支持。 不支持。
应用程序 ThreatHunting.Read.All 不可用。

HTTP 请求

POST /security/runHuntingQuery

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
Content-Type application/json. 必需。

注意

如果在查询中使用非 ANSI 字符，例如，要查询格式不正确或类似字符的电子邮件主题，请使用 application/json; charset=utf-8 作为 Content-Type 标头。

请求正文

在请求正文中，为 Query 参数提供 JSON 对象，并选择性地包含参数 Timespan 。

参数 类型 说明 示例
查询 String 必填。 Kusto 查询语言 (KQL 中的搜寻查询) 。 有关详细信息，请参阅 KQL 快速参考。
时间跨度 String 可选。 查询数据的时间间隔，采用 ISO 8601 格式。 默认值为 30 天，这意味着如果未指定 startTime，查询将从现在起查找 30 天。 如果在查询和 startTime 参数中都指定了时间筛选器，则会应用较短的时间跨度。 例如，如果查询具有过去 7 天的筛选器，而 startTime 是 10 天前，则查询仅回溯 7 天。

以下示例显示了 参数的可能格式 Timespan ：

  • 日期/日期：“2024-02-01T08：00：00Z/2024-02-15T08：00：00Z” - 开始和结束日期。
  • Duration/endDate：“P30D/2024-02-15T08：00：00Z” - 结束日期之前的时间段。
  • 开始/持续时间：“2024-02-01T08：00：00Z/P30D” - 开始日期和持续时间。
  • ISO8601持续时间：“P30D” - 从现在向后返回的持续时间。
  • 单个日期/时间：“2024-02-01T08：00：00Z”- 开始时间，结束时间默认为当前时间。

响应

如果成功，此作将在 200 OK 响应正文中返回响应代码和 huntingQueryResults 。

示例

示例 1：默认时间跨度查询

请求

以下示例指定 KQL 查询，并执行以下作：

  • 查看高级搜寻架构中的 DeviceProcessEvents 表。
  • 筛选 powershell.exe 进程启动事件的条件。
  • 为每个行指定同一表中三列的输出： Timestamp、 FileName、 InitiatingProcessFileName。
  • 按值对输出进行 Timestamp 排序。
  • 将输出限制为两个记录 (两行) 。
POST https://graph.microsoft.com/v1.0/security/runHuntingQuery

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

响应

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.security.huntingQueryResults",
    "schema": [
        {
            "name": "Timestamp",
            "type": "DateTime"
        },
        {
            "name": "FileName",
            "type": "String"
        },
        {
            "name": "InitiatingProcessFileName",
            "type": "String"
        }
    ],
    "results": [
        {
            "Timestamp": "2024-03-26T09:39:50.7688641Z",
            "FileName": "cmd.exe",
            "InitiatingProcessFileName": "powershell.exe"
        },
        {
            "Timestamp": "2024-03-26T09:39:49.4353788Z",
            "FileName": "cmd.exe",
            "InitiatingProcessFileName": "powershell.exe"
        }
    ]
}

示例 2：使用指定的时间跨度参数（可选）进行查询

请求

此示例指定 KQL 查询，并查看 60 天前高级搜寻架构中的 deviceProcessEvents 表。

POST https://graph.microsoft.com/v1.0/security/runHuntingQuery

{
    "Query": "DeviceProcessEvents",
    "Timespan": "P90D"
}

响应

注意：为了提高可读性，可能缩短了此处显示的响应对象。

HTTP/1.1 200 OK
Content-type: application/json

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