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

  • Применяется к: Microsoft Defender for Endpoint Plan 1, Microsoft Defender for Endpoint Plan 2, Microsoft Defender for Business

Примечание.

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

Совет

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

  • 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
  • aea.api.security.microsoft.com

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

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

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

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

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

На этапе регистрации приложения в клиенте Microsoft Entra должна быть назначена соответствующая роль. Дополнительные сведения о ролях см. в разделе Параметры разрешений.

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

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

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

    Параметр Регистрация приложений в области Управление в Центр администрирования Microsoft Entra

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

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

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

      Примечание.

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

      Параметр

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

      Области

      Важно!

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

      Например, вы можете:

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

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

    Примечание.

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

    Параметр предоставления согласия на разрешение в Центр администрирования Microsoft Entra

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

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

    Важно!

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

    Пункт меню Сертификаты & секреты в области Управление в Центр администрирования Microsoft Entra

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

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

    Область сведений о приложении в меню Обзор в Центр администрирования Microsoft Entra

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

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

Совет

Для некоторых API Microsoft Defender для конечной точки по-прежнему требуются маркеры доступа, выданные для устаревшего ресурса https://api.securitycenter.microsoft.com. Если аудитория маркеров не соответствует ресурсу, ожидаемому API, запросы завершаются ошибкой с 403 Forbidden, даже если конечная точка API использует https://api.security.microsoft.com. Используйте https://api.securitycenter.microsoft.com в качестве ресурса или область при получении маркеров.

Скопируйте следующий скрипт в среду интегрированной среды сценариев PowerShell или в текстовый редактор и сохраните его как Get-Token.ps1. При выполнении этого скрипта создается маркер и он сохраняется в рабочей папке под именем Latest-token.txt.

# This code gets the application context token and saves it to a file named "Latest-token.txt" in the current directory.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application (client) ID here
$appSecret = '' ### Paste your Application secret (App key) here to test, and then store it in a safe place!

$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

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

  1. Запустите скрипт, чтобы создать Latest-token.txt файл.
  2. В веб-браузере откройте https://jwt.ms/и скопируйте маркер (содержимое Latest-token.txt) в поле Ввод маркера ниже .
  3. На вкладке Декодированные маркеры найдите раздел роли и убедитесь, что он содержит разрешения Alert.Read.All , как показано на следующем рисунке:

Снимок экрана: jwt.ms с скопированным маркером и декодируемым маркером с разделом Роли и выделенным разрешением 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 created previously.
# Learn more about other query options and filters: https://learn.microsoft.com/defender-endpoint/api/get-alerts.
$url = "https://api.security.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 web request 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 часов.

Совет

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

  • Last updated on