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 小时内创建的警报