Hello World для MICROSOFT DEFENDER XDR REST API
Область применения:
- Microsoft Defender XDR
Важно!
Некоторые сведения относятся к предварительным выпускам продуктов, которые могут быть существенно изменены до коммерческого выпуска. Корпорация Майкрософт не дает никаких гарантий, явных или подразумеваемых, относительно предоставленных здесь сведений.
Выполнение этого проекта займет от 5 до 10 минут. Эта оценка времени включает регистрацию приложения и применение кода из примера скрипта PowerShell.
Войдите в Azure.
Перейдите в раздел Microsoft Entra ID>Регистрация приложений>Новая регистрация.
В форме регистрации выберите имя приложения, а затем нажмите кнопку Зарегистрировать. Выбор URI перенаправления необязателен. Для выполнения этого примера он не понадобится.
На странице приложения выберите Разрешения> APIДобавить разрешения>API, которые использует> моя организация, введите Microsoft Threat Protection и выберите Microsoft Threat Protection. Теперь приложение может получить доступ к Microsoft Defender XDR.
Выберите Предоставить согласие администратора. Каждый раз при добавлении разрешения необходимо выбрать Предоставить согласие администратора , чтобы оно войти в силу.
Добавьте секрет в приложение. Выберите Сертификаты & секреты, добавьте описание в секрет, а затем нажмите кнопку Добавить.
Совет
После нажатия кнопки Добавить выберите скопировать созданное значение секрета. Вы не сможете получить значение секрета после выхода.
Запишите идентификатор приложения и идентификатор клиента в безопасном месте. Они перечислены в разделе Обзор на странице приложения.
Дополнительные сведения о маркерах Microsoft Entra см. в руководстве по Microsoft Entra.
Важно!
Хотя в примере в этом демонстрационном приложении рекомендуется вставить значение секрета для тестирования, никогда не следует жестко кодировать секреты в приложение, работающее в рабочей среде. Третья сторона может использовать ваш секрет для доступа к ресурсам. Вы можете защитить секреты приложения с помощью azure Key Vault. Практический пример защиты приложения см. в статье Управление секретами в серверных приложениях с помощью Azure Key Vault.
Скопируйте приведенный ниже сценарий и вставьте его в избранный текстовый редактор. Сохраните как 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
Скопируйте и вставьте полученный маркер в JWT , чтобы декодировать его.
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
- Создание приложения для доступа к Microsoft Defender XDR без пользователя
- Создание приложения для доступа к MICROSOFT DEFENDER XDR API от имени пользователя
- Создание приложения с мультитенантным доступом партнеров к API Microsoft Defender XDR
- Управление секретами в серверных приложениях с помощью Azure Key Vault
- Авторизация OAuth 2.0 для входа пользователей и доступа к API
Совет
Хотите узнать больше? Общайтесь с членами сообщества Microsoft Security в нашем техническом сообществе: Microsoft Defender XDR Tech Community.