Microsoft Defender for Endpoint API - Hello World
适用于:
希望体验 Microsoft Defender for Endpoint? 注册免费试用版。
注意
如果你是美国政府客户,请使用 适用于美国政府客户的 Microsoft Defender for Endpoint 中列出的 URI。
提示
为了提高性能,可以使用离地理位置更近的服务器:
- us.api.security.microsoft.com
- eu.api.security.microsoft.com
- uk.api.security.microsoft.com
- au.api.security.microsoft.com
- swa.api.security.microsoft.com
- ina.api.security.microsoft.com
使用简单的 PowerShell 脚本获取警报
完成此示例需要多长时间?
只需在两个步骤中完成 5 分钟:
- 应用程序注册
- 使用示例:只需复制/粘贴简短的 PowerShell 脚本
是否需要连接权限?
对于应用程序注册阶段,必须在 Microsoft Entra 租户中分配 全局管理员 角色。
步骤 1 - Microsoft Entra ID 中创建应用
登录 Azure 门户。
导航到 Microsoft Entra ID>应用注册>新注册。
在注册表单中,选择应用程序的名称,然后选择“ 注册”。
允许应用程序访问 Defender for Endpoint 并为其分配 “读取所有警报” 权限:
选择“ 授予同意”。
注意
每次添加权限时,都必须单击“ 授予同意 ”,新权限才能生效。
将机密添加到应用程序。
选择“ 证书 & 机密”,向机密添加说明,然后选择“ 添加”。
重要
单击“添加”后, 复制生成的机密值。 离开后将无法检索!
记下应用程序 ID 和租户 ID。
在应用程序页上,转到 “概述” 并复制以下内容:
完成! 已成功注册应用程序!
步骤 2 - 使用应用获取令牌,并使用此令牌访问 API。
将以下脚本复制到 PowerShell ISE 或文本编辑器,并将其另存为
Get-Token.ps1
。运行此脚本会生成一个令牌,并将其保存在名为
Latest-token.txt
下的工作文件夹中。# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory # Paste below your Tenant ID, App ID and App Secret (App key). $tenantId = '' ### Paste your tenant ID here $appId = '' ### Paste your Application ID here $appSecret = '' ### Paste your Application secret here $resourceAppIdUri = 'https://api.securitycenter.microsoft.com' $oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token" $authBody = [Ordered] @{ resource = "$resourceAppIdUri" client_id = "$appId" 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
健全性检查:
- 运行脚本。
- 在浏览器中,转到: https://jwt.ms/。
- 复制令牌 (Latest-token.txt 文件的内容) 。
- 粘贴到顶部框中。
- 查找“角色”部分。 找到 Alert.Read.All 角色。
获取警报!
以下脚本使用
Get-Token.ps1
访问 API 并获取过去 48 小时的警报。将此脚本保存在保存上一个脚本
Get-Token.ps1
的同一文件夹中。该脚本 (json 和 csv) 创建两个文件,其中数据与脚本位于同一文件夹中。
# Returns Alerts created in the past 48 hours. $token = ./Get-Token.ps1 #run the script Get-Token.ps1 - make sure you are running this script from the same folder of Get-Token.ps1 # Get Alert from the last 48 hours. Make sure you have alerts in that time frame. $dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o") # The URL contains the type of query and the time filter we create above # Read more about [other query options and filters](get-alerts.md). $url = "https://api.securitycenter.microsoft.com/api/alerts?`$filter=alertCreationTime ge $dateTime" # Set the WebRequest headers $headers = @{ 'Content-Type' = 'application/json' Accept = 'application/json' Authorization = "Bearer $token" } # Send the webrequest and get the results. $response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop # Extract the alerts from the results. $alerts = ($response | ConvertFrom-Json).value | ConvertTo-Json # Get string with the execution time. We concatenate that string to the output file to avoid overwrite the file $dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."} # Save the result as json and as csv $outputJsonPath = "./Latest Alerts $dateTimeForFileName.json" $outputCsvPath = "./Latest Alerts $dateTimeForFileName.csv" Out-File -FilePath $outputJsonPath -InputObject $alerts ($alerts | ConvertFrom-Json) | Export-CSV $outputCsvPath -NoTypeInformation
你都完成了! 你已成功:
- 创建并注册和应用程序
- 授予该应用程序读取警报的权限
- 连接 API
- 使用 PowerShell 脚本返回过去 48 小时内创建的警报
相关文章
- Microsoft Defender for Endpoint API
- 使用应用程序上下文访问 Microsoft Defender for Endpoint
- 使用用户上下文访问 Microsoft Defender for Endpoint
提示
想要了解更多信息? 在技术社区中与 Microsoft 安全社区互动: Microsoft Defender for Endpoint 技术社区。