Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Пространство имен: microsoft.graph.security
Важно!
API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.
Запросите указанный набор данных о событиях, действиях или сущностях, поддерживаемых 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. | |
| Интервал времени | String | Необязательный параметр. Интервал времени запроса данных в формате ISO 8601. Значение по умолчанию — 30 дней. Если startTime не указано, запрос выполняется через 30 дней. Если фильтр времени указан как в запросе, так и в параметре startTime, применяется более короткий период времени. Например, если в запросе есть фильтр за последние 7 дней, а значение 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/beta/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/beta/$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/beta/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"
}
]
}