Hello World для MICROSOFT DEFENDER XDR REST API

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

• Microsoft Defender XDR

Важно!

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

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

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

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

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

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

   

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

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

   Совет

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

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

     

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

   

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

   Совет

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

   

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

   

Получение маркера с помощью приложения и использование маркера для доступа к 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 :

   

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

Приведенный ниже сценарий будет использовать 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 часов.

Связанные статьи

• Общие сведения об API Microsoft Defender XDR
• Доступ к API Microsoft Defender XDR
• Create приложение для доступа к Microsoft Defender XDR без пользователя
• Create приложение для доступа к MICROSOFT DEFENDER XDR API от имени пользователя
• Create приложение с доступом мультитенантного партнера к API Microsoft Defender XDR
• Управление секретами в серверных приложениях с помощью Azure Key Vault
• Авторизация OAuth 2.0 для входа пользователей и доступа к API

Совет

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