Microsoft Defender XDR REST API 的Hello World
适用于:
- Microsoft Defender XDR
重要
某些信息与预发布的产品有关,在商业发布之前可能有重大修改。 Microsoft 对此处所提供的信息不作任何明示或默示的保证。
使用简单的 PowerShell 脚本获取事件
完成此项目需要 5 到 10 分钟。 此时间估计包括注册应用程序,以及应用 PowerShell 示例脚本中的代码。
在 Microsoft Entra ID 中注册应用
登录到 Azure。
导航到Microsoft Entra ID>应用注册>“新建注册”。
在注册表单中,选择应用程序的名称,然后选择“ 注册”。 选择重定向 URI 是可选的。 完成此示例不需要一个。
在应用程序页上,选择“API 权限>”“添加组织使用>的权限> API”,键入“Microsoft威胁防护”,然后选择“Microsoft威胁防护”。 你的应用现在可以访问Microsoft Defender XDR。
选择“ 授予管理员同意”。 每次添加权限时,都必须选择“ 授予管理员同意 ”才能使其生效。
将机密添加到应用程序。 选择“ 证书 & 机密”,向机密添加说明,然后选择“ 添加”。
提示
选择“ 添加”后,选择 “复制生成的机密值”。 离开后将无法检索机密值。
在安全的地方记录应用程序 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 小时内更新的事件。
相关文章
- Microsoft Defender XDR API 概述
- 访问Microsoft Defender XDR API
- 创建应用以在没有用户的情况下访问Microsoft Defender XDR
- 创建代表用户访问Microsoft Defender XDR API 的应用
- 创建具有对 Microsoft Defender XDR API 的多租户合作伙伴访问权限的应用
- 使用 Azure 密钥保管库管理服务器应用中的机密
- 用于用户登录和 API 访问的 OAuth 2.0 授权
提示
想要了解更多信息? 请在我们的技术社区中与 Microsoft 安全社区互动:Microsoft Defender XDR 技术社区。