безопасность: runHuntingQuery

Пространство имен: microsoft.graph.security

Запрашивает указанный набор данных о событиях, действиях или сущностях, поддерживаемых Microsoft 365 Defender, для упреждающего поиска конкретных угроз в вашей среде.

Этот метод предназначен для расширенной охоты в Microsoft 365 Defender. Этот метод включает запрос на языке запросов Kusto (KQL). Он задает таблицу данных в схеме расширенной охоты и последовательность операторов по каналу для фильтрации или поиска этих данных, а также форматирования выходных данных запроса определенными способами.

Узнайте больше о поиске угроз на разных устройствах, электронных письмах, приложениях и удостоверениях. Сведения о KQL.

Сведения об использовании расширенной охоты на портале Microsoft 365 Defender см. в статье Упреждающая охота на угрозы с помощью расширенной охоты в Microsoft 365 Defender.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба Правительство США L4 Правительство США L5 (DOD) Китай управляется 21Vianet

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения Разрешения с наименьшими привилегиями Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись) ThreatHunting.Read.All Недоступно.
Делегированные (личная учетная запись Майкрософт) Не поддерживается. Не поддерживается.
Приложение ThreatHunting.Read.All Недоступно.

HTTP-запрос

POST /security/runHuntingQuery

Заголовки запросов

Имя Описание
Авторизация Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
Content-Type application/json. Обязательно.

Примечание.

Если в запросе используются символы, отличные от ANSI, например для запроса субъектов электронной почты с неправильно сформированными или похожими символами, используйте для application/json; charset=utf-8 заголовка Content-Type.

Текст запроса

В тексте запроса укажите объект JSON для Query параметра и при необходимости добавьте Timespan параметр .

Параметр Тип Описание Пример
Запрос String Обязательный. Запрос охоты на языке запросов Kusto (KQL). Дополнительные сведения см. в кратком справочнике по KQL.
Timespan String Необязательный параметр. Интервал времени запроса данных в формате ISO 8601. Значение по умолчанию — 30 дней. Если startTime не указано, запрос выполняется через 30 дней. Если фильтр времени указан как в запросе, так и в параметре startTime, применяется более короткий период времени. Например, если в запросе есть фильтр за последние семь дней, а значение startTime — 10 дней назад, запрос выполняется только семь дней назад.

В следующих примерах показаны возможные форматы для Timepsan параметра:

  • Дата и дата: "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. Запрос с необязательным параметром timespan

Запрос

В этом примере задается запрос KQL и выполняется поиск в таблице deviceProcessEvents в схеме расширенной охоты 60 дней назад.

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