Microsoft Defender for Endpoint API - Hello World

适用于:

希望体验 Microsoft Defender for Endpoint? 注册免费试用版

注意

如果你是美国政府客户,请为美国政府客户使用Microsoft Defender for Endpoint中列出的 URI。

提示

为了提高性能,可以使用离地理位置更近的服务器:

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com

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

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

只需用两个步骤完成 5 分钟:

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

是否需要连接权限?

对于应用程序注册阶段,必须在 Azure Active Directory (Azure AD ) 租户中具有全局管理员角色。

步骤 1 - 在 Azure Active Directory 中创建应用

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

  2. 导航到 Azure Active Directory>应用注册>New 注册

    Azure Active Directory 门户中“管理”窗格下的“应用注册”选项

  3. 在注册表单中,为应用程序选择一个名称,然后单击 “注册”。

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

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

      注意

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

      Azure Active Directory 门户中“管理”窗格下的“API 权限”选项

    • 选择 应用程序权限>Alert.Read.All> Click on Add permissions.

      “请求 API 权限”页中的权限类型和设置窗格

      重要

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

      例如:

      • 若要 运行高级查询,请选择“运行高级查询”权限。
      • 若要 隔离计算机,请选择“隔离计算机”权限。
      • 若要确定所需的权限,请查看你有兴趣调用的 API 中的“ 权限 ”部分。
  5. 单击 “授予许可”。

    注意

    每次添加权限时,都必须单击 “授予许可 ”以使新权限生效。

    Azure Active Directory 门户中的授予权限许可选项

  6. 向应用程序添加机密。

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

    重要

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

    Azure Active Directory 门户“管理”窗格中的“证书 & 机密”菜单项

  7. 记下应用程序 ID 和租户 ID。

    在应用程序页上,转到 “概述 ”并复制以下内容:

    Azure Active Directory 门户中“概述”菜单项下的应用程序详细信息窗格

完成! 你已成功注册应用程序!

步骤 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 角色。

    用于 jwt.ms 的解码令牌窗格

让我们获取警报!

  • 以下脚本将使用 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 小时内创建的警报