实用图表：使用 Microsoft AuditLog 查询图表 API（预览版）

统一审核日志是一个极好的信息来源

自 2016 年推出以来，统一审核日志一直是 Microsoft 365 租户管理员的重要信息来源。根据租户中运行的工作负载，审核日志可以提取 1,600 多个不同的事件。拥有 Purview Audit（标准）许可证 (Office 365 E3) 的租户可以访问审核事件 180 天，而拥有 Purview Audit（高级）许可证的租户可以访问事件 365 天。尽管某些工作负载生成的某些审计事件中的信息格式有些奇怪，但毫无疑问，能够查询审计日志以发现租户内部发生的情况是有用的。

根据 Microsoft 365 路线图项目 117587，该 API 将于 2024 年 5 月全面可用。

AuditLog 查询图 API

到目前为止，查询审核日志的唯一编程方法是运行Search-UnifiedAuditLog cmdlet。即使 Microsoft 在 2023 年中期对 cmdlet 的工作方式进行了意外更改，此方法也很有效。到目前为止，似乎还没有公开的解释来证明这一变化的合理性。我想发现影响客户脚本的未宣布的更改是在云中工作的乐趣的一部分。

Microsoft 于 2022 年在 Purview Compliance 门户中引入了新的搜索功能。该门户不是执行交互式搜索，而是创建服务在后台处理的搜索查询。 AuditLog 查询图 API（又名 Microsoft Purview 审核搜索 API）是一项预览功能，用于以与 Purview 使用的方式类似的方式创建和运行搜索查询并检索搜索结果。执行搜索需要几个步骤：

• 通过设置搜索参数的值来创建搜索查询。
• 提交搜索查询（职位）。
• 搜索查询完成后，检索搜索结果（审核记录）。

这一切听起来非常简单，但它比使用 Search-UnifiedAuditLog cmdlet 运行审核搜索更复杂。让我们更详细地研究一下 AuditLog Query API。

创建审核搜索查询

我使用 Microsoft Graph PowerShell SDK 来测试 AuditLog 查询 API。首先要注意的是，我使用了AuditLogsQuery.Read.All 权限来访问审核日志。此权限允许访问所有审计数据。其他权限可用于授予对审核数据的有限访问权限，例如仅允许访问 Exchange Online 审核事件。您还需要使用管理员帐户登录才能使用委派权限。作为后台进程运行的作业（例如 Azure 自动化 Runbook）使用应用程序权限，不需要以管理员身份登录。

此代码片段展示了如何使用新搜索查询的参数创建哈希表，以及如何将查询发布到审核日志查询端点以创建新作业。

$Uri = "https://graph.microsoft.com/beta/security/auditLog/queries"
$SearchName = ("Audit Search {0}" -f (Get-Date -format 'dd-MMM-yyyy HH:mm'))

$SearchParameters = @{
    "displayName"           = $SearchName
    "filterStartDateTime"   = $StartDateSearch
    "filterEndDateTime"     = $EndDateSearch
    "operationFilters"      = $Operations
}

$SearchQuery = Invoke-MgGraphRequest -Method POST -Uri $Uri -Body $SearchParameters
$SearchId = $SearchQuery.Id

$Operations 变量包含要搜索的以逗号分隔的审核事件列表。搜索的开始和结束日期以带有 Z 后缀的可排序日期格式传递。下面是一个查询的哈希表的示例，该查询查找从 2024 年 2 月 29 日午夜到 2024 年 3 月 2 日午夜之间的两个 SharePoint Online 操作：

Name                           Value
----                           -----
filterEndDateTime              2024-03-02T00:00:00Z
displayname                    Audit Search 04-Mar-2024 05:29
filterStartarDateTime          2024-02-29T00:00:00Z
operationsFilters              {fileuploaded, filemodified}

有些人喜欢获取一段时间内的所有审计记录，因为他们希望将审计数据加载到 SIEM 中以实现长期保留和查询目的。使用Search-UnifiedAuditLog cmdlet，获取每个可用审核记录的方法是不指定任何操作。

要获取特定时间段内的每条审核记录，请勿在用于审核日志查询的参数中包含 operationsFilter。参数将只是显示名称、开始日期和时间以及结束日期和时间。或者，您可以包含一个recordTypeFilters过滤器来定义您感兴趣的审核记录类型集。

运行审核搜索查询

搜索查询最多可能需要十分钟才能完成。最终，搜索完成，您可以获取查询找到的任何审核记录。此代码片段展示了如何获取审核记录的第一页。

$Uri = ("https://graph.microsoft.com/beta/security/auditLog/queries/{0}/records" -f $SearchId)
[array]$SearchRecords = Invoke-MgGraphRequest -Uri $Uri -Method GET

该 API 在一个页面中返回 150 条记录。如果要获取的记录少于 150 条，您可以继续分析返回的记录。但是，如果有更多数据可用，则您的代码必须使用在有其他数据可用时返回的 nextlink URI 来获取下一页，直到没有更多数据可用为止。强制代码以有限块的形式获取数据是一种称为分页的常见过程，图形 API 使用该过程来限制一次检索的数据量。以下是用于分页并获取查询的可用审核记录的代码：

# Paginate to fetch all available audit records
$NextLink = $SearchRecords.'@Odata.NextLink'
While ($null -ne $NextLink) {
    $SearchRecords = $null
    [array]$SearchRecords = Invoke-MgGraphRequest -Uri $NextLink -Method GET 
    $AuditRecords += $SearchRecords.value
    Write-Host ("{0} audit records fetched so far..." -f $AuditRecords.count)
    $NextLink = $SearchRecords.'@odata.NextLink' 
}

分页与 Graph API 配合良好。 AuditLog 查询 API 的预览版本似乎相当微妙，我使用 nextlink 指针的一些尝试导致了“500 内部服务器错误”，这阻止了检索审核记录的尝试。

Microsoft Graph PowerShell SDK 通过为许多 cmdlet 包含一个 All 参数来获取所有可用数据，从而使开发人员更加轻松。 Microsoft Graph PowerShell SDK (V2.15) 中存在用于管理审核日志查询的 Cmdlet。例如，要检索查询找到的审核记录，您可以运行 Get-MgBetaSecurityAuditLogQueryRecord cmdlet 并指定 All 参数：

[array]$AuditRecords = Get-MgBetaSecurityAuditLogQueryRecord -AuditLogQueryId $SearchId -All

乍一看，cmdlet 似乎是获取审核日志搜索返回的所有审核记录的好方法。该 cmdlet 确实返回所有记录，但无论我做什么，AuditData 属性的内容始终是 Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphSecurityAuditData。 如果没有 AuditData 属性的内容进行分析，检索到的审计记录的价值就会大大降低。结果是我继续使用图形查询。随着 Microsoft 将该 API 全面推出，这个问题可能会得到解决。

分析审计数据

审计记录有两部分。第一个在所有工作负载中都是不变的，包含时间戳、操作名称以及负责操作的用户或系统帐户等信息。第二个存储在 AuditData 属性中，可以找到有关所发生事件的信息。每个工作负载都控制着存储在 AuditData 中的信息，并且工作负载之间存在相当大的差异。因此，解析审计记录的内容需要花费更多的精力和定制的编码。

好消息是 AuditLog 查询 API 以易于访问的哈希表形式返回 AuditData 属性。坏消息是，不同工作负载之间存在相同的内容差异（我没想到会有其他情况）。换句话说，对于每种审核事件，您必须以与 Search-UnifiedAuditLogAuditData 属性所包含的内容以及数据的含义。 cmdlet。

图 1 显示了从查询中获取的审计记录的一些信息。我不知道什么对象的标识符为eba15bfd-c28e-4433-a20e-0278888c5825。我找不到具有此值的用户帐户或服务主体。这是一个蒙福的奥秘。

您可以从 GitHub 下载我用于测试的脚本。

关注审计事件提取的简易性

记住软件何时处于预览阶段总是很重要的。该代码可供人们测试，并且在正式发布之前会进行改进。考虑到 Microsoft 365 操作生成的审核数据量，可以理解 Microsoft 希望从 Search-UnifiedAuditLog cmdlet 运行的同步交互式审核搜索操作类型转向更适合服务的操作可以在后台运行的操作。这就是 Purview 合规性门户现在的工作方式，而 AuditLog 查询 API 的存在是 Microsoft 希望管理员在此模式下询问审核事件的另一个迹象。

微软的问题是，与设置异步审核搜索在后台运行然后获取结果的复杂性相比，使用单个 PowerShell cmdlet 的便捷性使得管理员可能会避开 Graph API 方法。每个人都喜欢轻松的生活，Search-UnifiedAuditLog 仍然是从 Microsoft 365 审核日志中检索数据的最简单方法。