使用 Search-UnifiedAuditLog cmdlet 工具的最佳做法

项目
11/10/2023

审核日志是一种记录来自一系列工作负载的事件的工具。 Search-UnifiedAuditLog cmdlet 可用于搜索和检索审核日志中的数据。了解如何有效使用此 cmdlet 非常重要，尤其是在解释 AuditData 属性中的信息时，因为不同的工作负载将不同类型的信息插入此属性。

默认情况下，Search-UnifiedAuditLog cmdlet 为任何搜索请求返回 100 条审核记录，除非指定了使用 ResultSize 参数检索的不同记录数， (最多) 5,000 条记录 。

单个搜索最多可以使用页面检索处理 50,000 条审核记录 。由于审核日志可以包含大量数据，因此在使用搜索参数时，请务必尽可能具体，以避免返回过多记录。

若要使用 Search-UnifiedAuditLog cmdlet，帐户必须具有 Exchange View-Only 审核日志或审核日志角色。这些角色是 合规性管理和组织管理角色组的一部分，可以根据需要分配给其他角色组。

RecordTypes

RecordType 是生成记录的工作负荷。使用 Search-UnifiedAuditLog cmdlet 找到的不同类型的事件的示例包括：

将成员添加到 Microsoft Entra ID (AzureActiveDIrectory) 中的组
更新 Exchange (ExchangeAdmin) 中的邮箱属性
删除 SharePoint (SharePointFileOperation) 中的文件
将用户登录到 Microsoft Teams (MicrosoftTeams)
AIP 检测信号 (AipHeartbeat)

可以使用 Search-UnifiedAuditLog cmdlet 搜索和跟踪这些事件，以便筛选和查看统一审核日志中记录的事件的详细信息。

审核数据结构

Search-UnifiedAuditLog -RecordType AipDiscover -StartDate (Get-Date).AddDays(-100) -EndDate (Get-Date)

审核记录由两部分组成：常规属性 AuditData 属性

常规属性

所有工作负荷以相同方式填充的常规属性，以及包含特定于工作负荷的信息的 AuditData 属性。常规属性包括记录类型、创建日期、操作和用户标识符。

RunspaceId   : 136b901e-a6bc-4f24-bb58-5c435090df91
RecordType   : AipDiscover
CreationDate : 2022-09-15 5:49:22 PM
UserIds      : AdeleV@M365x23987777.OnMicrosoft.com
Operations   : Access
ResultIndex  : 8
ResultCount  : 8
Identity     : 20728aaf-1964-1a4a-bd72-784fa3c12132
IsValid      : True
ObjectState  : Unchanged

AuditData 属性

使用 AuditData 属性查找有关事件的最重要信息。工作负载使用架构来描述它们插入审核记录的属性，这些架构用于帮助解释审核事件中的有效负载。它可能需要一些试验和错误才能完全了解审核记录中的信息。审核日志记录中详细属性的指南可在此过程中有所帮助。有关用户执行的操作的详细信息存储在 JavaScript 对象表示法中， (JSON) 格式，因此需要进一步处理数据的格式以提取信息。

AuditData:
{
  "SensitivityLabelEventData":{
    "SensitivityLabelId":"8581574a-c314-42e3-bfdc-a63cf96ed86e"
  },
  "SensitiveInfoTypeData":[
    
  ],
  "ProtectionEventData":{
    "IsProtected":false
  },
  "Common":{
    "ApplicationId":"c00e9d32-3c8d-4a7d-832b-029040e7db99",
    "ApplicationName":"Microsoft Azure Information Protection Word Add-In",
    "ProcessName":"WINWORD",
    "Platform":1,
    "DeviceName":"AdeleVanceWindo",
    "Location":"On-premises file shares",
    "ProductVersion":"2.13.49.0"
  },
  "DataState":"Use",
  "ObjectId":"C:\\452Documentcreated.docx",
  "UserId":"AdeleV@M365x23987777.OnMicrosoft.com",
  "ClientIP":"20.237.230.167",
  "Id":"20728aaf-1964-1a4a-bd72-784fa3c12132",
  "RecordType":93,
  "CreationTime":"2022-09-15T17:49:22",
  "Operation":"Access",
  "OrganizationId":"4b080626-0acc-4940-8af8-bfc836ff1a59",
  "UserType":0,
  "UserKey":"AdeleV@M365x23987777.OnMicrosoft.com",
  "Workload":"Aip",
  "Version":1,
  "Scope":1
}

下表列出了 AuditData 属性详细信息。

参数	说明
RecordType	生成记录的工作负荷类型，例如Microsoft Entra ID、Microsoft Teams、Exchange 管理员或 SharePoint 文件操作。
CreationTime	执行活动的 UTC 格式的日期和时间。
操作	有人访问项目时记录的操作，例如 SharePoint Online 中的 FileViewed。
OrganizationId	GUID 形式的唯一租户标识符。
UserKey	用于获取对项的访问权限的标识，通常通过组中的成员身份实现。
Workload	记录事件的应用程序的名称，例如 SharePoint Online、Exchange Online、OneDrive for Business或Microsoft Entra ID。
ClientIP	发起操作的客户端工作站的 IP 地址。
ObjectID	访问的对象的完整路径。
UserID	导致操作发生的帐户的Microsoft Entra帐户标识符。
UserAgent	用于调用操作的客户端。
SourceFileName	操作中涉及的文件的名称。
UserType	执行操作的用户类型，其值为“0” (常规用户) 、“1” (管理员) 或“2” (Microsoft 数据中心管理员或系统帐户) 。
EventSource	仅由 SharePoint Online 使用，指示源是 SharePoint 还是 ObjectMode。
ResultIndex 和 ResultCount	使用大型记录集时，ResultIndex 和 ResultCount 属性可能很有用。 ResultIndex 指示返回集中的记录编号，而 ResultCount 显示返回的记录总数。例如，如果 ResultIndex 为 1 且 ResultCount 为 125，则表示显示的记录是集中返回的 125 中的第一条。如果搜索遇到内部超时，ResultIndex 将设置为 -1。当管理员获得使用审核日志和 PowerShell cmdlet 的经验时，他们会发现审核日志是一个有价值的信息来源，用于了解谁在特定时间段内与文档交互或创建了新文档。若要充分利用审核记录中提供的信息，可能需要经过一些试验和错误。

查找正确的集事件

若要在搜索审核日志时找到正确的事件，请务必知道要查找的内容并使用适当的筛选器和参数。这可能是具有挑战性的，因为审核日志可以包含大量事件，搜索特定操作可能类似于在大型无序数据列表中搜索小型对象。

解决此问题的一种方法是采取措施为感兴趣的操作生成审核事件，等待 60 分钟左右以允许事件引入审核日志，然后在该时间段内搜索事件。

这将为你提供一组较小的事件，然后你可以分析和使用它们来执行进一步的搜索。最好使用为事件记录的 Operations / RecordTypes 值来帮助优化搜索并查找要查找的特定事件。

下面是通过查找非常具体的操作并在给定日期范围内筛选数据的示例。查看记录类型以查看可查找的记录类型。

以下脚本查找特定操作。

$Operations = ("SensitivityLabelUpdated", "SensitivityLabelApplied", "FileSensitivityLabelApplied")
$StartDate = (Get-Date).AddDays(-90)
$EndDate = (Get-Date).AddDays(1)
[Array]$Records = Search-UnifiedAuditLog -StartDate $StartDate -EndDate $EndDate -Formatted -ResultSize 5000 -Operations $Operations

以下脚本搜索特定的记录类型。此示例使用 AipDiscover。

Search-UnifiedAuditLog -StartDate (Get-Date).AddDays(-100) -EndDate (Get-Date) -RecordType AipDiscover -Operations Access -ResultSize 5 -Formatted | Format-Table UserIds, CreationDate, Operations

以下脚本将结果存储在数组中，并搜索特定值。此示例使用 CreationDate。

[array]$Records  = Search-UnifiedAuditLog -RecordType AipDiscover -StartDate (Get-Date).AddDays(-100) -EndDate (Get-Date)
$Records | Where-Object {$_.CreationDate -eq "2022-09-15 5:49:22 PM"}

管理大量审核数据

如果需要从大型租户检索大量审核记录，或者需要在较长时间内搜索多个操作，则单个搜索可能会返回超过 5,000 条记录。

若要从 Search-UnifiedAuditLog cmdlet 管理大量数据，可以使用 ReturnLargeSet 和 ReturnNextPreviewPage 参数。这些参数允许执行返回大量结果集的搜索，然后在后续搜索中检索下一页结果。

使用 SessionId 参数标识搜索会话并指定要检索的页数。这将允许 cmdlet 提取多页数据并将其返回给你。
如果要使用 Search-UnifiedAuditLog cmdlet 搜索大量审核数据，也使用 SessionId 参数。该 cmdlet 每页最多返回 5000 条记录，因此如果要搜索更多记录，则需要使用 SessionId 参数来标识搜索会话并指定要检索的页数。然后，cmdlet 将使用会话标识符提取其他数据页并将其返回给你。
如果需要搜索超过 50,000 条记录，请将工作拆分到多个搜索中，并为每个搜索使用不同的条件。
将搜索结果存储在外部存储库（例如 Azure log analytics、Azure 数据资源管理器）中，以便于访问和分析。
定期查看和更新搜索条件并审核数据管理过程，以确保捕获正确的数据并有效地管理数据。这将帮助你随时了解任何潜在的安全问题，并提高组织的整体安全性。

检索大量数据的步骤

若要提取大量审核数据，请执行以下步骤：

生成会话标识符。
使用循环检索多个页面中的数据。
重复运行 Search-UnifiedAuditLog 命令以提取所有可用数据。
保存每次运行 Search-UnifiedAuditLog 中的数据。
提取所有页面后，按日期对数据进行排序，并将其导出到 CSV 文件。

示例

Search-UnifiedAuditLog 有两个参数支持检索大型数据集：SessionID 和 SessionCommand。 SessionID 和 SessionCommand 可以组合在一起来处理大型数据集。 SessionId 参数包含用于标识搜索会话的字符串值。可以使用任何喜欢的值，从简单数字到使用 New-Guid cmdlet 生成的 GUID。会话标识符的存在会告知 Search-UnifiedAuditLog 它可能需要提取多页数据。

eg.
$SessionId = "5b5a5a5a-5b5b-5c5c-5d5d-5e5e5e5e5e5e"
$SessionId = "UnifiedAuditLogSearch 01/02/17"

SessionCommand 告知 Search-UnifiedAuditLog 如何处理大量审核数据。返回的数据可能包含重复记录。此参数可设置为：

ReturnLargeSet：返回的审核记录未排序。使用此方法最多可以提取 50,000 条审核记录，但必须记住在提取全部数据后对数据进行排序。
ReturnNextPreviewPage：Search-UnifiedAuditLog 返回按日期排序的审核记录。但是，使用此方法最多只能提取 5,000 条记录。通过使用分页或 ResultSize 参数返回的最大记录数为 5,000 条记录。

注意

始终对给定 SessionId 值使用相同的 SessionCommand 值。对于同一会话 ID，请勿切换 ReturnLargeSet 和 ReturnNextPreviewPage。否则，输出限制为 10,000 个结果。

SessionId 示例脚本

在以下示例中，脚本首先导入Exchange Online管理模块，并创建与Exchange Online的远程连接。然后，它设置搜索的开始和结束日期，并使用 Search-UnifiedAuditLog cmdlet 在统一审核日志中搜索指定日期范围内的条目。

然后，该脚本使用 foreach 循环扫描 cmdlet 返回的记录数组，并根据需要处理每个记录。在本例中，它将打印每个记录的操作名称和用户标识。

# Import the Exchange Online Management module
Import-Module ExchangeOnlineManagement
# Create a remote connection to Exchange Online
$UserCredential = Get-Credential
Connect-IPPSSession
# Search the Unified Audit Log for entries with the specified SessionID
$SessionId = "5b5a5a5a-5b5b-5c5c-5d5d-5e5e5e5e5e5e"
$StartDate = (Get-Date).AddDays(-90)
$EndDate = (Get-Date).AddDays(1)
[Array]$Records = Search-UnifiedAuditLog -StartDate $StartDate -EndDate $EndDate -SessionId $SessionId

# Scan through the array of records
foreach ($Record in $Records)
{
    # Process each record as needed
    # For example, you could print the operation name and user identity
    Write-Host "Operation: $($Record.RecordType)"
    Write-Host "User Identity: $($Record.Operations)"
    Write-Host "User Identity: $($Record.AuditData)"
}

ReturnLargeSet 示例脚本

在以下示例中，Search-UnifiedAuditLog cmdlet 用于在审核日志中搜索指定开始和结束时间之间的条目。 ReturnLargeSet 参数是通过在 $parameters 对象中指定 SessionId 和 SessionCommand 参数来设置的。然后，将遍历搜索结果，并将每个条目输出到控制台。

ReturnLargeSet：返回未排序的数据。通过使用分页，最多可以访问 50,000 个结果。如果不需要有序结果并且已针对搜索延迟进行了优化，则这是建议的值。

# Set the start and end time for the audit log search
$startTime = "01/01/2022 00:00:00"
$endTime = "12/31/2022 23:59:59"

# Set the parameters for the search
$parameters = @{
    StartDate = $startTime
    EndDate = $endTime
    SessionId = "UnifiedAuditLogSearch 01/02/17"
    SessionCommand = "ReturnLargeSet"
}

# Perform the search and store the results in a variable
$results = Search-UnifiedAuditLog @parameters

# Loop through the results and output each entry
for ($i = 0; $i -lt $results.Count; $i++) {
    $entry = $results[$i]
    Write-Output $entry
}

ReturnNextPreviewPage 示例脚本

以下脚本使用 Search-UnifiedAuditLog cmdlet 和 ReturnNextPreviewPage 参数执行搜索。使用指定的开始和结束时间执行搜索。然后，搜索结果将输出到控制台。

# Set the start and end time for the audit log search
$startTime = "01/01/2022 00:00:00"
$endTime = "12/31/2022 23:59:59"

 
# Set the parameters for search
$parameters = @{
    SessionId = "UnifiedAuditLogSearch 01/02/17"
    SessionCommand = "ReturnNextPreviewPage"
    StartDate = $startTime
    EndDate = $endTime
}

# Retrieve results
$resultpage = Search-UnifiedAuditLog @parameters

通过