Hello World для MICROSOFT DEFENDER XDR REST API

  • Статья

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

  • Microsoft Defender XDR

Важно!

Некоторые сведения относятся к предварительным выпускам продуктов, которые могут быть существенно изменены до коммерческого выпуска. Корпорация Майкрософт не дает никаких гарантий, явных или подразумеваемых, относительно предоставленных здесь сведений.

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

Выполнение этого проекта займет от 5 до 10 минут. Эта оценка времени включает регистрацию приложения и применение кода из примера скрипта PowerShell.

Регистрация приложения в Microsoft Entra ID

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

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

    Раздел Новая регистрация на портале Microsoft Defender

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

  4. На странице приложения выберите Разрешения> APIДобавить разрешения>API, которые использует> моя организация, введите Microsoft Threat Protection и выберите Microsoft Threat Protection. Теперь приложение может получить доступ к Microsoft Defender XDR.

    Совет

    Microsoft Threat Protection — это прежнее имя Microsoft Defender XDR и не будет отображаться в исходном списке. Чтобы оно появилось, необходимо написать его имя в текстовом поле. Раздел об использовании API на портале Microsoft Defender

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

      Область разрешений приложения на портале Microsoft Defender

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

    Раздел Предоставление согласия администратора на портале Microsoft Defender

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

    Совет

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

    Раздел добавления секрета на портале Microsoft Defender

  7. Запишите идентификатор приложения и идентификатор клиента в безопасном месте. Они перечислены в разделе Обзор на странице приложения.

    Раздел Обзор на портале Microsoft Defender

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

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

Важно!

Хотя в примере в этом демонстрационном приложении рекомендуется вставить значение секрета для тестирования, никогда не следует жестко кодировать секреты в приложение, работающее в рабочей среде. Третья сторона может использовать ваш секрет для доступа к ресурсам. Вы можете защитить секреты приложения с помощью azure Key Vault. Практический пример защиты приложения см. в статье Управление секретами в серверных приложениях с помощью Azure Key Vault.

  1. Скопируйте приведенный ниже сценарий и вставьте его в избранный текстовый редактор. Сохраните как Get-Token.ps1. Вы также можете запустить код "как есть" в интегрированной среде сценариев PowerShell, но его следует сохранить, так как нам потребуется снова запустить его при использовании скрипта извлечения инцидента в следующем разделе.

    Этот скрипт создаст маркер и сохранит его в рабочей папке под именем Latest-token.txt.

    # This script gets the app context token and saves it to a file named "Latest-token.txt" under the current directory.
# Paste in your tenant ID, client ID and app secret (App key).

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"
$authBody = [Ordered] @{
  resource = $resourceAppIdUri
  client_id = $clientId
  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. Скопируйте и вставьте полученный маркер в JWT , чтобы декодировать его.

  2. JWT — это веб-токен JSON. Декодированный маркер будет содержать ряд элементов или утверждений в формате JSON. Убедитесь, что утверждение ролей в декодированном маркере содержит необходимые разрешения.

    На следующем рисунке показан декодированные маркеры, полученные из приложения с Incidents.Read.Allразрешениями , Incidents.ReadWrite.Allи AdvancedHunting.Read.All :

    Раздел Декодированные маркеры на портале Microsoft Defender

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

Приведенный ниже сценарий будет использовать Get-Token.ps1 для доступа к API. Затем он получает список инцидентов, которые были обновлены в последний раз в течение последних 48 часов, и сохраняет список в виде JSON-файла.

Важно!

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

# This script returns incidents last updated within the past 48 hours.

$token = ./Get-Token.ps1

# Get incidents from the past 48 hours.
# The script may appear to fail if you don't have any incidents in that time frame.
$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")

# This URL contains the type of query and the time filter we created above.
# Note that `$filter` does not refer to a local variable in our script --
# it's actually an OData operator and part of the API's syntax.
$url = "https://api.security.microsoft.com/api/incidents`?`$filter=lastUpdateTime+ge+$dateTime"

# Set the webrequest headers
$headers = @{
    'Content-Type' = 'application/json'
    'Accept' = 'application/json'
    'Authorization' = "Bearer $token"
}

# Send the request and get the results.
$response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop

# Extract the incidents from the results.
$incidents =  ($response | ConvertFrom-Json).value | ConvertTo-Json -Depth 99

# Get a string containing the execution time. We concatenate that string to the name 
# of the output file to avoid overwriting the file on consecutive runs of the script.
$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}

# Save the result as json
$outputJsonPath = "./Latest Incidents $dateTimeForFileName.json"

Out-File -FilePath $outputJsonPath -InputObject $incidents

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

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

Совет

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