MICROSOFT DEFENDER XDR API расширенной охоты

  • Статья

Область применения:

  • Microsoft Defender XDR

Предупреждение

Этот API расширенной охоты является более старой версией с ограниченными возможностями. Более полная версия API расширенной охоты уже доступна в API безопасности Microsoft Graph. См . раздел Расширенная охота с помощью API безопасности Microsoft Graph

Важно!

Некоторые сведения относятся к предварительным выпускам продуктов, которые могут быть существенно изменены до коммерческого выпуска. Корпорация Майкрософт не дает никаких гарантий, явных или подразумеваемых, относительно предоставленных здесь сведений.

Расширенная охота — это средство охоты на угрозы, которое использует специально созданные запросы для изучения данных о событиях за последние 30 дней в Microsoft Defender XDR. Расширенные запросы охоты можно использовать для проверки необычных действий, обнаружения возможных угроз и даже реагирования на атаки. API расширенной охоты позволяет программно запрашивать данные о событиях.

Квоты и выделение ресурсов

Следующие условия относятся ко всем запросам.

  1. Запросы изучают и возвращают данные за последние 30 дней.
  2. Результаты могут возвращать до 100 000 строк.
  3. На каждого клиента можно выполнить не менее 45 вызовов в минуту. Количество вызовов зависит от размера каждого клиента.
  4. Каждому клиенту выделяются ресурсы ЦП в зависимости от размера клиента. Запросы блокируются, если клиент достиг 100 % выделенных ресурсов до следующего 15-минутного цикла. Чтобы избежать блокировки запросов из-за чрезмерного потребления, следуйте инструкциям в разделе Оптимизация запросов, чтобы избежать превышения квот ЦП.
  5. Если один запрос выполняется более трех минут, время ожидания истекает и возвращает ошибку.
  6. Код 429 ответа HTTP указывает, что вы достигли выделенных ресурсов ЦП по количеству отправленных запросов или выделенному времени выполнения. Прочтите текст ответа, чтобы понять достигнутое ограничение.

Разрешения

Для вызова API расширенной охоты требуется одно из следующих разрешений. Дополнительные сведения, включая выбор разрешений, см. в статье Доступ к API защиты Microsoft Defender XDR.

Тип разрешения Разрешение Отображаемое имя разрешения
Приложение AdvancedHunting.Read.All Выполнение расширенных запросов
Делегированные (рабочая или учебная учетная запись) AdvancedHunting.Read Выполнение расширенных запросов

Примечание.

При получении маркера с использованием учетных данных пользователя:

  • У пользователя должна быть роль "Просмотр данных".
  • Пользователь должен иметь доступ к устройству на основе параметров группы устройств.

HTTP-запрос

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

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

Заголовок Значение
Авторизация Носитель {token} Примечание: обязательный
Content-Type application/json

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

В тексте запроса укажите объект JSON со следующими параметрами:

Параметр Тип Описание
Запрос Текст Выполняемый запрос. (обязательно)

Отклик

В случае успешного выполнения этот метод вернет 200 OKобъект и QueryResponse в тексте ответа.

Объект ответа содержит три свойства верхнего уровня:

  1. Stats — словарь статистики производительности запросов.
  2. Schema — схема ответа, список Name-Type пар для каждого столбца.
  3. Результаты — список расширенных событий охоты.

Пример

В следующем примере пользователь отправляет запрос ниже и получает объект ответа API, содержащий Stats, Schemaи Results.

Запрос

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

Объект Response

{
    "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 Security в нашем техническом сообществе: Microsoft Defender XDR Техническое сообщество.