Поделиться через


Использование 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
  • ina.api.security.microsoft.com

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

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

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

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

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

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

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

Примечание.

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

Совет

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

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

  1. Войдите на портал Azure.

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

    Страница

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

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

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


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

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

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

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

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

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

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

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

      • Для общедоступных клиентских приложений укажите универсальный код ресурса (URI), используемый идентификатором Microsoft Entra для возврата ответов маркера. Укажите значение, специфичное для вашего приложения, например 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
    

См. также

Совет

Хотите узнать больше? Обратитесь к сообществу Майкрософт по безопасности в техническом сообществе Microsoft Defender для конечной точки Tech Community.