Microsoft Defender for Endpoint API - Hello World

适用于：

• Microsoft Defender for Endpoint 计划 1
• Microsoft Defender for Endpoint 计划 2

希望体验 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

使用简单的 PowerShell 脚本获取警报

完成此示例需要多长时间？

只需在两个步骤中完成 5 分钟：

• 应用程序注册
• 使用示例：只需复制/粘贴简短的 PowerShell 脚本

是否需要连接权限？

对于应用程序注册阶段，必须在Microsoft Entra租户中具有全局管理员角色。

步骤 1 - 在 Microsoft Entra ID 中创建应用

1. 使用全局管理员用户登录到 Azure。

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

   

3. 在注册表单中，选择应用程序的名称，然后单击“ 注册”。

4. 允许应用程序访问 Defender for Endpoint 并为其分配 “读取所有警报” 权限：

   • 在应用程序页上，单击“ API 权限>添加权限>API 我的组织使用> 类型 WindowsDefenderATP ”，然后单击“ WindowsDefenderATP”。

     注意

     WindowsDefenderATP 不显示在原始列表中。 你需要开始在文本框中写入其名称才能看到它出现。

     

   • 选择 “应用程序权限>”“警报”。Read.All> 单击 “添加权限”。

     

     重要

     需要选择相关权限。 “读取所有警报”只是一个示例！

     例如：

     • 若要 运行高级查询，请选择“运行高级查询”权限。
     • 若要 隔离计算机，请选择“隔离计算机”权限。
     • 若要确定所需的权限，请查看要调用的 API 中的 “权限” 部分。

5. 单击“ 授予同意”。

   注意

   每次添加权限时，都必须单击“ 授予同意 ”，新权限才能生效。

   

6. 将机密添加到应用程序。

   单击“ 证书 & 机密”，向机密添加说明，然后单击“ 添加”。

   重要

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

   

7. 记下应用程序 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

提示

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