Microsoft Defender XDR REST API 的Hello World

项目
04/26/2024

适用于：

Microsoft Defender XDR

重要

某些信息与预发布的产品有关，在商业发布之前可能有重大修改。 Microsoft 对此处所提供的信息不作任何明示或默示的保证。

使用简单的 PowerShell 脚本获取事件

完成此项目需要 5 到 10 分钟。此时间估计包括注册应用程序，以及应用 PowerShell 示例脚本中的代码。

在 Microsoft Entra ID 中注册应用

以具有 全局管理员 角色的用户身份登录到 Azure。
导航到Microsoft Entra ID>应用注册>“新建注册”。
在注册表单中，选择应用程序的名称，然后选择“ 注册”。选择重定向 URI 是可选的。完成此示例不需要一个。
在应用程序页上，选择“API 权限>”“添加我组织使用>的权限> API”，键入“Microsoft 威胁防护”，然后选择“Microsoft 威胁防护”。你的应用现在可以访问Microsoft Defender XDR。

提示

Microsoft 威胁防护是Microsoft Defender XDR的前名称，不会显示在原始列表中。你需要开始在文本框中写入其名称才能看到它出现。
- 选择 “应用程序权限>Incident.Read.All ”，然后选择“ 添加权限”。
选择“ 授予管理员同意”。每次添加权限时，都必须选择“ 授予管理员同意 ”才能使其生效。
将机密添加到应用程序。选择“ 证书 & 机密”，向机密添加说明，然后选择“ 添加”。

提示

选择“ 添加”后，选择 “复制生成的机密值”。离开后将无法检索机密值。
在安全的地方记录应用程序 ID 和租户 ID。它们在应用程序页的 “概述 ”下列出。

使用应用获取令牌，并使用令牌访问 API

有关Microsoft Entra令牌的详细信息，请参阅Microsoft Entra教程。

重要

尽管此演示应用中的示例鼓励你粘贴机密值以进行测试，但 绝不能将机密硬编码 到生产中运行的应用程序中。第三方可以使用你的机密来访问资源。可以使用 Azure 密钥保管库帮助保护应用的机密安全。有关如何保护应用的实用示例，请参阅使用 Azure 密钥保管库管理服务器应用中的机密。

复制以下脚本，并将其粘贴到你喜欢的文本编辑器中。另存为 Get-Token.ps1。还可以在 PowerShell ISE 中按原样运行代码，但应保存它，因为在下一部分中使用事件提取脚本时，我们需要再次运行它。

此脚本将生成一个令牌，并将其保存在名为 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 Web 令牌。解码的令牌将包含许多 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 小时内更新的事件。

提示

想要了解更多信息？ Engage技术社区中的 Microsoft 安全社区：Microsoft Defender XDR技术社区。

通过

Microsoft Defender XDR REST API 的Hello World

使用简单的 PowerShell 脚本获取事件

在 Microsoft Entra ID 中注册应用

使用应用获取令牌，并使用令牌访问 API

验证令牌

获取最近发生的事件列表

反馈

其他资源

通过

Microsoft Defender XDR REST API 的Hello World

使用简单的 PowerShell 脚本获取事件

在 Microsoft Entra ID 中注册应用

使用应用获取令牌，并使用令牌访问 API

验证令牌

获取最近发生的事件列表

相关文章

反馈

其他资源