Рекомендации по использованию средства командлета Search-UnifiedAuditLog

Статья
04/04/2023

Журнал аудита — это средство, записывающее события из диапазона рабочих нагрузок. Командлет Search-UnifiedAuditLog можно использовать для поиска и извлечения данных из журнала аудита. Важно понимать, как эффективно использовать этот командлет, особенно когда речь идет о интерпретации информации в свойстве AuditData, так как различные рабочие нагрузки вставляют различные типы информации в это свойство.

По умолчанию командлет Search-UnifiedAuditLog возвращает 100 записей аудита для любого поискового запроса, если не указано другое количество записей для получения с помощью параметра ResultSize (не более 5000 записей).

Один поиск может обработать не более 50 000 записей аудита с помощью извлечения страницы. Так как журнал аудита может содержать большой объем данных, важно быть максимально конкретным при использовании параметров поиска, чтобы избежать возврата слишком большого количества записей.

Чтобы использовать командлет Search-UnifiedAuditLog, ваша учетная запись должна иметь роль "Журналы аудита View-Only Exchange" или "Журналы аудита". Эти роли входят в группы ролей "Управление соответствием требованиям" и "Управление организацией" и могут быть назначены другим группам ролей при необходимости.

RecordTypes

RecordType — это рабочая нагрузка, создающая запись. Примеры различных типов событий, обнаруженных с помощью командлета Search-UnifiedAuditLog:

Добавление участника в группу в Microsoft Entra ID (AzureActiveDIrectory)
Обновление свойств почтового ящика в Exchange (ExchangeAdmin)
Удаление файла в SharePoint (SharePointFileOperation)
Вход пользователя в Microsoft Teams (MicrosoftTeams)
AIP Heartbeat (AipHeartbeat)

Эти события можно искать и отслеживать с помощью командлета Search-UnifiedAuditLog, который позволяет фильтровать и просматривать сведения о событиях, записанных в едином журнале аудита.

Структура данных аудита

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

Записи аудита состоят из двух частей: общие свойства AuditData property

Общие свойства

Общие свойства, которые заполняются одинаково всеми рабочими нагрузками, и свойство 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, когда было выполнено действие.
Operation	Операция регистрируется, когда кто-то обращается к элементу, например FileViewed в случае SharePoint Online.
OrganizationId	Уникальный идентификатор клиента в виде GUID.
UserKey	Удостоверение, используемое для получения доступа к элементу, как правило, достигается путем членства в группе.
Workload	Имя приложения, которое зарегистрировал событие, например SharePoint Online, Exchange Online, OneDrive для бизнеса или Microsoft Entra ID.
ClientIP	IP-адрес клиентской рабочей станции, на которой возникло действие.
ObjectID	Полный путь к объекту, к которому был выполнен доступ.
UserID	Идентификатор Microsoft Entra учетной записи, вызвавшей действие.
UserAgent	Клиент, используемый для вызова действия.
SourceFileName	Имя файла, участвующего в действии.
UserType	Тип пользователя, выполняющего действие, со значениями "0" (обычный пользователь), "1" (администратор) или "2" (администратор центра обработки данных Майкрософт или системная учетная запись).
EventSource	Используется только SharePoint Online, указывая, является ли источником SharePoint или ObjectMode.
ResultIndex и ResultCount	Свойства ResultIndex и ResultCount могут быть полезны при работе с большими наборами записей. ResultIndex указывает номер записи в возвращаемом наборе, а ResultCount — общее количество возвращенных записей. Например, если ResultIndex имеет значение 1, а ResultCount — 125, это означает, что показанная запись является первой из 125, возвращенных в наборе. Если поиск обнаруживает внутреннее время ожидания, ResultIndex будет иметь значение -1. По мере того как администраторы получают опыт работы с журналом аудита и командлетами PowerShell, они обнаружат, что журнал аудита является ценным источником информации для понимания того, кто взаимодействовал с документом или создавал новые документы в течение определенного периода времени. Для полного использования информации, предоставленной в записях аудита, может потребоваться несколько проб и ошибок.

Поиск правильных событий набора

Чтобы найти нужные события при поиске в журнале аудита, важно знать, что вы ищете, и использовать соответствующие фильтры и параметры. Это может быть сложной задачей, так как журнал аудита может содержать большое количество событий, а поиск определенных действий может быть похож на поиск небольшого объекта в большом и неупорядоченном списке данных.

Один из способов решения этой проблемы — принять меры по созданию события аудита для интересующего вас действия, подождите около 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"}

Управление большими объемами данных аудита

Если необходимо получить большое количество записей аудита из большого клиента или выполнить поиск нескольких операций в течение длительного периода времени, вполне вероятно, что один поиск вернет более 5000 записей.

Для управления большими объемами данных из командлета Search-UnifiedAuditLog можно использовать параметры ReturnLargeSet и ReturnNextPreviewPage. Эти параметры позволяют выполнять поиск, возвращающий большие наборы результатов, а затем извлекать следующую страницу результатов в последующих поисках.

Используйте параметр SessionId, чтобы определить сеанс поиска и указать количество страниц, которые требуется извлечь. Это позволит командлету получить несколько страниц данных и вернуть их вам.
Параметр SessionId также используется при поиске большого объема данных аудита с помощью командлета Search-UnifiedAuditLog. Командлет вернет не более 5000 записей на страницу, поэтому, если вы хотите найти большее количество, необходимо использовать параметр SessionId, чтобы определить сеанс поиска и указать количество страниц, которые требуется извлечь. Затем командлет будет использовать идентификатор сеанса, чтобы получить дополнительные страницы данных и вернуть их вам.
Если вам нужно найти более 50 000 записей, разделите работу между несколькими поисками и используйте разные критерии для каждого поиска.
Храните результаты поиска во внешнем репозитории, например Azure Log Analytics, Azure Data Explorer, для удобства доступа и анализа.
Регулярно проверяйте и обновляйте критерии поиска и процессы управления данными аудита, чтобы гарантировать, что вы собираете нужные данные и эффективно управляете ими. Это поможет вам оставаться в курсе любых потенциальных проблем безопасности и повысить общую безопасность вашей организации.

Действия по извлечению больших объемов данных

Чтобы получить большой объем данных аудита, выполните следующие действия.

Создайте идентификатор сеанса.
Используйте цикл для получения данных на нескольких страницах.
Повторно выполните команду Search-UnifiedAuditLog, чтобы получить все доступные данные.
Сохраните данные из каждого запуска Search-UnifiedAuditLog.
После получения всех страниц отсортируйте данные по дате и экспортируйте их в CSV-файл.

Примеры

Search-UnifiedAuditLog имеет два параметра для поддержки получения больших наборов данных: SessionID и SessionCommand. SessionID и SessionCommand можно объединить для обработки больших наборов данных. Параметр SessionId содержит строковое значение для идентификации сеанса поиска. Вы можете использовать любое значение, от простого числа до GUID, созданного с помощью командлета New-Guid. Наличие идентификатора сеанса сообщает Search-UnifiedAuditLog, что может потребоваться получить несколько страниц данных.

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

SessionCommand сообщает Search-UnifiedAuditLog, как обрабатывать большие объемы данных аудита. Возвращаемые данные могут содержать повторяющиеся записи. Для этого параметра можно задать следующее:

ReturnLargeSet: возвращенные записи аудита не отсортированы. С помощью этого метода можно получить до 50 000 записей аудита, но не забудьте отсортировать данные после их получения.
ReturnNextPreviewPage: Search-UnifiedAuditLog возвращает записи аудита, отсортированные по дате. Однако с помощью этого метода можно получить не более 5000 записей. Максимальное число записей, возвращаемых при использовании разбиения на разбиение по страницам или параметрОм ResultSize, составляет 5000 записей.

Примечание.

Всегда используйте одно и то же значение SessionCommand для заданного значения SessionId. Не переключайтесь между ReturnLargeSet и ReturnNextPreviewPage для одного и того же идентификатора сеанса. В противном случае выходные данные ограничены 10 000 результатами.

Пример скрипта SessionId

В следующем примере скрипт сначала импортирует модуль управления Exchange Online и создает удаленное подключение к Exchange Online. Затем он задает даты начала и окончания поиска и использует командлет Search-UnifiedAuditLog для поиска в едином журнале аудита записей в указанном диапазоне дат.

Затем скрипт использует цикл foreach для сканирования массива записей, возвращаемых командлетом, и обрабатывает каждую запись по мере необходимости. В этом случае выводится имя операции и удостоверение пользователя для каждой записи.

# 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 используется для поиска в журнале аудита записей между указанным временем начала и окончания. Параметр ReturnLargeSet задается путем указания параметров SessionId и SessionCommand в объекте $parameters. Затем результаты поиска циклически просматриваются, и каждая запись выводится в консоль.

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 и параметра 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

Поделиться через