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

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

  • Статья

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

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

Получение оповещений с помощью простого скрипта 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.

  • Скопируйте следующий скрипт в среду интегрированной среды сценариев 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 .

    Область декодированного маркера для jwt.ms

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

  • Следующий скрипт использует 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 часов

Совет

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