Использование API Microsoft Defender для конечной точки

  • Статья

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

Важно!

Расширенные возможности охоты не включены в Defender для бизнеса.

Хотите попробовать 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

На этой странице описывается создание приложения для получения программного доступа к Defender для конечной точки от имени пользователя.

Если вам нужен программный доступ Microsoft Defender для конечной точки без пользователя, см. раздел Доступ Microsoft Defender для конечной точки с контекстом приложения.

Если вы не знаете, какой доступ вам нужен, прочитайте страницу Введение.

Microsoft Defender для конечной точки предоставляет большую часть своих данных и действий с помощью набора программных API. Эти API-интерфейсы позволяют автоматизировать рабочие потоки и внедрять инновации на основе Microsoft Defender для конечной точки возможностей. Для доступа к API требуется проверка подлинности OAuth2.0. Дополнительные сведения см. в разделе Поток кода авторизации OAuth 2.0.

Как правило, для использования API необходимо выполнить следующие действия:

  • Create приложения Microsoft Entra
  • Получение маркера доступа с помощью этого приложения
  • Использование маркера для доступа к API Defender для конечной точки

На этой странице объясняется, как создать приложение Microsoft Entra, получить маркер доступа для Microsoft Defender для конечной точки и проверить маркер.

Примечание.

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

Совет

Если у вас есть разрешение на выполнение действия на портале, у вас есть разрешение на выполнение действия в API.

Создать приложение

  1. Войдите в Azure с учетной записью пользователя с ролью глобального администратора .

  2. Перейдите в раздел Microsoft Entra ID>Регистрация приложений>Новая регистрация.

    Страница Регистрация приложений в microsoft портал Azure

  3. После появления страницы Регистрация приложения введите сведения о регистрации приложения:

    • Имя — введите информативное имя приложения, которое будет отображаться пользователям приложения.

    • Поддерживаемые типы учетных записей — выберите учетные записи, которые должно поддерживать приложение.


      Поддерживаемые типы учетных записей Описание
      Учетные записи только в этом каталоге организации Этот вариант подходит для создания бизнес-приложений. Он будет недоступен, если приложение не регистрируется в каталоге.

      Этот параметр сопоставляется с Microsoft Entra только с одним клиентом.

      Этот параметр используется по умолчанию, если только приложение не регистрируется за пределами каталога. В случаях, когда приложение зарегистрировано вне каталога, по умолчанию используется Microsoft Entra мультитенантных и личных учетных записей Майкрософт.
      Учетные записи в любом каталоге организации Выберите этот параметр, если вы хотите выбрать в качестве целевой аудитории предприятия и учебные заведения.

      Этот параметр сопоставляется с Microsoft Entra мультитенантом.

      Если вы зарегистрировали приложение как Microsoft Entra только с одним клиентом, его можно обновить, чтобы оно было Microsoft Entra мультитенантным и обратно в один клиент с помощью колонки Проверка подлинности.
      Учетные записи в любом каталоге организации и личные учетные записи Майкрософт Выберите этот параметр для широкого круга пользователей.

      Этот параметр сопоставляется с Microsoft Entra мультитенантными и личными учетными записями Майкрософт.

      Если вы зарегистрировали приложение как Microsoft Entra мультитенантные и личные учетные записи Майкрософт, изменить это в пользовательском интерфейсе нельзя. Вместо этого необходимо использовать редактор манифеста приложения для изменения типов поддерживаемых учетных записей.

    • URI перенаправления (необязательно) — выберите тип приложения, которое вы создаете — Веб или Общедоступный клиент (мобильный и классический), а затем введите универсальный код ресурса (URI) перенаправления (или URL-адрес ответа) приложения.

      • Для веб-приложений укажите основной URL-адрес приложения. Например, http://localhost:31544 может быть URL-адресом веб-приложения, выполняемого на локальном компьютере. Пользователи будут использовать этот URL-адрес для входа в приложение веб-клиента.

      • Для общедоступных клиентских приложений укажите универсальный код ресурса (URI), используемый Microsoft Entra ID для возврата ответов маркера. Укажите значение, специфичное для вашего приложения, например myapp://auth.

      Конкретные примеры для веб-приложений или собственных приложений см. в наших кратких руководствах.

      По завершении щелкните Зарегистрировать.

  4. Разрешите приложению доступ к Microsoft Defender для конечной точки и назначьте ему разрешение "Чтение оповещений":

    • На странице приложения выберите Разрешения> APIДобавить API разрешений>API, которые моя организация использует>, введите WindowsDefenderATP и выберите WindowsDefenderATP.

      Примечание.

      WindowsDefenderATP не отображается в исходном списке. Начните писать его имя в текстовом поле, чтобы увидеть его появление.

      добавить разрешение.

    • Выберите Пункт Оповещения о делегированных разрешениях.Чтение>> выберите Добавить разрешения.

      Области

    Важно!

    Выберите соответствующие разрешения. Примером является только чтение оповещений.

    Например:

    • Чтобы выполнить расширенные запросы, выберите Разрешение На выполнение расширенных запросов .

    • Чтобы изолировать устройство, выберите Изолировать разрешение компьютера .

    • Чтобы определить, какое разрешение вам нужно, просмотрите раздел Разрешения в API, который требуется вызвать.

    • Выберите Предоставить согласие.

      Примечание.

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

      Вариант согласия администратора Grand

  5. Запишите идентификатор приложения и идентификатор клиента.

    На странице приложения перейдите в раздел Обзор и скопируйте следующие сведения:

    Идентификатор созданного приложения

Получение токена доступа

Дополнительные сведения о маркерах Microsoft Entra см. в руководстве по Microsoft Entra.

Использование C#

  • Скопируйте или вставьте приведенный ниже класс в приложение.

  • Используйте метод AcquireUserTokenAsync с идентификатором приложения, идентификатором клиента, именем пользователя и паролем, чтобы получить маркер.

    namespace WindowsDefenderATP
{
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json.Linq;

    public static class WindowsDefenderATPUtils
    {
        private const string Authority = "https://login.microsoftonline.com";

        private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";

                var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");

                using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                {
                    response.EnsureSuccessStatusCode();

                    var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);

                    var jObject = JObject.Parse(json);

                    return jObject["access_token"].Value<string>();
                }
            }
        }
    }
}

Проверка маркера

Убедитесь, что вы получили правильный маркер:

  • Скопируйте или вставьте в JWT маркер, полученный на предыдущем шаге, чтобы декодировать его.

  • Проверьте получение утверждения "scp" с требуемыми разрешениями приложения.

  • На снимке экрана ниже вы можете увидеть декодированные маркеры, полученные из приложения в этом руководстве:

    Страница проверки маркера

Использование маркера для доступа к API Microsoft Defender для конечной точки

  • Выберите API, который вы хотите использовать, — поддерживаемые API Microsoft Defender для конечной точки.

  • Задайте заголовок Authorization в HTTP-запросе, отправляемом по адресу Bearer {token}( Bearer — это схема авторизации).

  • Срок действия маркера составляет 1 час (можно отправить несколько запросов с одним и тем же маркером).

  • Пример отправки запроса на получение списка оповещений с помощью C#:

    var httpClient = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");

request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

// Do something useful with the response

См. также

Совет

Хотите узнать больше? Engage с сообществом Microsoft Security в нашем техническом сообществе: Microsoft Defender для конечной точки Техническое сообщество.