Создание API оповещений

Статья
05/03/2024

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

Хотите попробовать Microsoft Defender для конечной точки? Зарегистрироваться для бесплатной пробной версии.

Примечание.

Если вы являетесь клиентом для государственных организаций США, используйте URI, перечисленные в Microsoft Defender для конечной точки для клиентов государственных организаций США.

Совет

Для повышения производительности можно использовать сервер ближе к географическому расположению:

us.api.security.microsoft.com
eu.api.security.microsoft.com
uk.api.security.microsoft.com
au.api.security.microsoft.com
swa.api.security.microsoft.com
ina.api.security.microsoft.com

Описание API

Создает новое оповещение поверх события.

Для создания оповещений требуется событие Microsoft Defender для конечной точки.
Необходимо указать три параметра из события в запросе: время события, идентификатор компьютера и идентификатор отчета. См. приведенный ниже пример.
Можно использовать событие, которое можно найти в API расширенной охоты или на портале.
Если на том же устройстве с тем же названием существует открытое оповещение, новое созданное оповещение объединяется с ним.
Автоматическое исследование автоматически запускается для оповещений, созданных с помощью API.

Ограничения

Ограничения скорости для этого API — 15 вызовов в минуту.

Разрешения

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

Тип разрешения	Разрешение	Отображаемое имя разрешения
Приложение	Alert.ReadWrite.All	"Чтение и запись всех оповещений"
Делегированные (рабочая или учебная учетная запись)	Alert.ReadWrite	"Чтение и запись оповещений"

Примечание.

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

Пользователь должен иметь по крайней мере следующее разрешение роли: исследование оповещений. Дополнительные сведения см. в разделе Создание ролей и управление ими.
Пользователь должен иметь доступ к устройству, связанному с оповещением, на основе параметров группы устройств. Дополнительные сведения см. в статье Создание групп устройств и управление ими.

Создание группы устройств поддерживается как в Defender для конечной точки плана 1, так и в плане 2

HTTP-запрос

POST https://api.securitycenter.microsoft.com/api/alerts/CreateAlertByReference

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

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

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

В тексте запроса укажите следующие значения (все обязательные):

Свойство	Тип	Описание
eventTime	DateTime(UTC)	Точное время события в виде строки, полученное в результате расширенной охоты. Например, `2018-08-03T16:45:21.7115183Z`обязательный.
reportId	String	Идентификатор отчета о событии, полученный в результате расширенной охоты. Обязательное поле.
machineId	String	Идентификатор устройства, на котором было определено событие. Обязательное поле.
severity	String	Степень серьезности оповещения. Значения свойств: "Low", "Medium" и "High". Обязательное поле.
title	String	Заголовок оповещения. Обязательное поле.
description	String	Описание оповещения. Обязательное поле.
recommendedAction	String	Сотруднику службы безопасности необходимо выполнить это действие при анализе оповещения. Обязательное поле.
category	String	Категория оповещения. Значения свойств: "General", "CommandAndControl", "Collection", "CredentialAccess", "DefenseEvasion", "Discovery", "Exfiltration", "Exploit", "Execution", "InitialAccess", "LateralMovement", "Malware", "Persistence", "PrivilegeEscalation", "Ransomware", "SuspiciousActivity" Required.

Отклик

В случае успешного выполнения этот метод возвращает значение 200 ОК и новый объект оповещения в тексте ответа. Если событие с указанными свойствами (reportId, eventTime и machineId) не найдено — 404 Не найдено.

Пример

Запрос

Ниже приведен пример запроса.

POST https://api.securitycenter.microsoft.com/api/alerts/CreateAlertByReference

{
    "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
    "severity": "Low",
    "title": "example",
    "description": "example alert",
    "recommendedAction": "nothing",
    "eventTime": "2018-08-03T16:45:21.7115183Z",
    "reportId": "20776",
    "category": "Exploit"
}