Microsoft Defender XDR REST API 的Hello World

  • 项目

适用于：

  • Microsoft Defender XDR

重要

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

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

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

在 Microsoft Entra ID 中注册应用

  1. 以具有 全局管理员 角色的用户身份登录到 Azure。

  2. 导航到Microsoft Entra ID>应用注册>“新建注册”。

    Microsoft Defender门户中的“新建注册”部分

  3. 在注册表单中，选择应用程序的名称，然后选择“ 注册”。 选择重定向 URI 是可选的。 完成此示例不需要一个。

  4. 在应用程序页上，选择“API 权限>”“添加我组织使用>的权限> API”，键入“Microsoft 威胁防护”，然后选择“Microsoft 威胁防护”。 你的应用现在可以访问Microsoft Defender XDR。

    提示

    Microsoft 威胁防护是Microsoft Defender XDR的前名称，不会显示在原始列表中。 你需要开始在文本框中写入其名称才能看到它出现。 Microsoft Defender门户中的 API 用法部分

    • 选择 “应用程序权限>Incident.Read.All ”，然后选择“ 添加权限”。

      Microsoft Defender门户中的应用程序权限窗格

  5. 选择“ 授予管理员同意”。 每次添加权限时，都必须选择“ 授予管理员同意 ”才能使其生效。

    Microsoft Defender门户中的“授予管理员同意”部分

  6. 将机密添加到应用程序。 选择“ 证书 & 机密”，向机密添加说明，然后选择“ 添加”。

    提示

    选择“ 添加”后，选择 “复制生成的机密值”。 离开后将无法检索机密值。

    Microsoft Defender门户中的“添加机密”部分

  7. 在安全的地方记录应用程序 ID 和租户 ID。 它们在应用程序页的 “概述 ”下列出。

    Microsoft Defender门户中的“概述”部分

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

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

重要

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

  1. 复制以下脚本，并将其粘贴到你喜欢的文本编辑器中。 另存为 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

验证令牌

  1. 将收到的令牌复制并粘贴到 JWT 中以对其进行解码。

  2. JWT 代表 JSON Web 令牌。 解码的令牌将包含许多 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 安全社区：Microsoft Defender XDR技术社区。