API Microsoft Defender для конечной точки — Hello World

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

• Microsoft Defender для конечной точки (план 1)
• Microsoft Defender для конечной точки (план 2)

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

Получение оповещений с помощью простого скрипта PowerShell

Сколько времени занимает этот пример?

Это займет всего 5 минут в два этапа:

• Регистрация приложения
• Примеры использования: требуется только копирование и вставка короткого скрипта PowerShell

Требуется ли разрешение на подключение?

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

Шаг 1. Создание приложения в Идентификаторе Microsoft Entra

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

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

   

3. В форме регистрации выберите имя приложения и нажмите кнопку Зарегистрировать.

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

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

     Примечание.

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

     

   • Выберите Разрешения приложений>Alert.Read.All, а затем выберите Добавить разрешения.

     

     Важно!

     Необходимо выбрать соответствующие разрешения. Чтение всех оповещений — это только пример.

     Например:

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

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

   Примечание.

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

   

6. Добавьте секрет в приложение.

   Выберите Сертификаты & секреты, добавьте описание в секрет и нажмите кнопку Добавить.

   Важно!

   После нажатия кнопки Добавить скопируйте созданное значение секрета. Вы не сможете получить после отъезда!

   

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

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

   

Готово! Вы успешно зарегистрировали приложение!

Шаг 2. Получение маркера с помощью приложения и использование этого маркера для доступа к API.

• Скопируйте следующий скрипт в среду интегрированной среды сценариев PowerShell или в текстовый редактор и сохраните его как Get-Token.ps1.

• При выполнении этого скрипта создается маркер и он сохраняется в рабочей папке под именем Latest-token.txt.

  # That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
  # Paste below your Tenant ID, App ID and App Secret (App key).
  
  $tenantId = '' ### Paste your tenant ID here
  $appId = '' ### Paste your Application ID here
  $appSecret = '' ### Paste your Application secret here
  
  $resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
  $oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
  $authBody = [Ordered] @{
       resource = "$resourceAppIdUri"
       client_id = "$appId"
       client_secret = "$appSecret"
       grant_type = 'client_credentials'
  }
  $authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
  $token = $authResponse.access_token
  Out-File -FilePath "./Latest-token.txt" -InputObject $token
  return $token
  

• Проверка работоспособности:

  • Запустите сценарий.
  • В браузере перейдите по адресу https://jwt.ms/.
  • Скопируйте маркер (содержимое файла Latest-token.txt).
  • Вставьте в верхнюю рамку.
  • Найдите раздел "роли". Найдите роль Alert.Read.All .

  

Давайте получим оповещения!

• Следующий скрипт использует Get-Token.ps1 для доступа к API и получает оповещения за последние 48 часов.

• Сохраните этот скрипт в той же папке, что и предыдущий скрипт Get-Token.ps1.

• Скрипт создает два файла (JSON и CSV) с данными в той же папке, что и скрипты.

  # Returns Alerts created in the past 48 hours.
  
  $token = ./Get-Token.ps1       #run the script Get-Token.ps1  - make sure you are running this script from the same folder of Get-Token.ps1
  
  # Get Alert from the last 48 hours. Make sure you have alerts in that time frame.
  $dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")
  
  # The URL contains the type of query and the time filter we create above
  # Read more about [other query options and filters](get-alerts.md).
  $url = "https://api.securitycenter.microsoft.com/api/alerts?`$filter=alertCreationTime ge $dateTime"
  
  # Set the WebRequest headers
  $headers = @{
      'Content-Type' = 'application/json'
      Accept = 'application/json'
      Authorization = "Bearer $token"
  }
  
  # Send the webrequest and get the results.
  $response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop
  
  # Extract the alerts from the results.
  $alerts =  ($response | ConvertFrom-Json).value | ConvertTo-Json
  
  # Get string with the execution time. We concatenate that string to the output file to avoid overwrite the file
  $dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}
  
  # Save the result as json and as csv
  $outputJsonPath = "./Latest Alerts $dateTimeForFileName.json"
  $outputCsvPath = "./Latest Alerts $dateTimeForFileName.csv"
  
  Out-File -FilePath $outputJsonPath -InputObject $alerts
  ($alerts | ConvertFrom-Json) | Export-CSV $outputCsvPath -NoTypeInformation
  

Все готово! Вы успешно выполнили следующие действия.

• Создано, зарегистрировано и приложение
• Предоставлено разрешение на чтение оповещений для этого приложения
• Подключен API
• Использование скрипта PowerShell для возврата оповещений, созданных за последние 48 часов

Статьи по теме

• API Microsoft Defender для конечной точки
• Доступ к Microsoft Defender для конечной точки с помощью контекста приложения
• Доступ к Microsoft Defender для конечной точки с помощью контекста пользователя