Поиск в журнале аудита с помощью сценария PowerShell

Статья
01/23/2024

Сегодня для ИТ-администраторов нет задачи важнее, чем обеспечить в работе безопасность, соответствие требованиям и готовность к аудиту. Microsoft 365 предлагает ряд встроенных возможностей, которые помогут предприятиям контролировать безопасность, соответствие требованиям и аудиты. В частности, чтобы справиться с несоответствиями и нарушениями безопасности, вам поможет единое ведение журналов аудита. Получить журналы аудита можно следующими способами:

API действий управления Office 365
Средство поиска по журналам аудита на портале Microsoft Purview или Портал соответствия требованиям Microsoft Purview.
Командлет Search-UnifiedAuditLog в Exchange Online PowerShell

Если вам нужно регулярно получать журналы аудита, следует рассмотреть решение, использующее API действий управления Office 365, так как оно может обеспечить крупным организациям масштабируемость и производительность для получения миллионов записей аудита на постоянной основе. С помощью средства поиска по журналам аудита на портале Microsoft Purview или на портале соответствия требованиям можно быстро найти записи аудита для конкретных операций, выполняемых в более коротком диапазоне времени. При поиске в более широких временных рамках, особенно когда дело касается крупных организаций, средство поиска в журналах аудита может вернуть слишком много записей, что приведет к трудностям в их обработке и экспорте.

Если для расследования конкретного случая или инцидента вам нужно вручную извлечь данные аудита, особенно в обширном временном диапазоне для крупного предприятия, лучшим выбором будет командлет Search-UnifiedAuditLog. В этой статье описан сценарий PowerShell, использующий командлет, который может извлекать до 50 000 записей аудита (при каждом запуске командлета) и экспортировать их в CSV-файл. Затем этот файл можно преобразовать в удобный формат с помощью Power Query в Excel. Сценарий, приведенный в статье, также сводит к минимуму вероятность того, что поисковый запрос большого объема записей аудита превысит время ожидания службы.

Совет

Если вы не являетесь клиентом E5, используйте 90-дневную пробную версию решений Microsoft Purview, чтобы узнать, как дополнительные возможности Purview могут помочь вашей организации управлять безопасностью данных и соответствием требованиям. Начните сейчас, перейдя в центр пробных версий на портале соответствия требованиям Microsoft Purview. Сведения о регистрации и условиях пробной версии.

Перед запуском сценария

Для того чтобы пользоваться сценарием и искать записи аудита, в вашей организации должно быть включено ведение журналов аудита. По умолчанию ведение журналов аудита включено для организаций, использующих Microsoft 365 и Office 365 корпоративный. Чтобы убедиться, что для вашей организации доступен поиск в журнале аудита, можно выполнить следующую команду в Exchange Online PowerShell:
```
Get-AdminAuditLogConfig | FL UnifiedAuditLogIngestionEnabled
```
Значение True для свойства UnifiedAuditLogIngestionEnabled указывает на то, что поиск в журнале аудита включен.
Для успешного запуска скрипта вам должна быть назначена роль Журналы аудита только для просмотра или Журналы аудита в Exchange Online. По умолчанию эти роли назначаются группам ролей Управление соответствием и Управление организацией на странице Разрешения в центре администрирования Exchange.
Выполнение сценария может занять много времени. Время выполнения зависит от диапазона дат и длины интервала, в котором сценарий ищет записи аудита. Большие диапазоны дат и меньшие интервалы приводят к длительному выполнению. Чтобы узнать больше о диапазонах дат и интервалах, см. таблицу на этапе 2.
Пример сценария, приведенный в данной статье, не поддерживается ни одной из стандартных программ и служб технической поддержки Microsoft. Пример сценария приводится в виде "как есть", без каких-либо гарантий. Кроме того, корпорация Microsoft отказывается от всех подразумеваемых гарантий, включая в том числе все подразумеваемые гарантии пригодности для продажи или определенной цели. Все риски, возникающие в результате использования примера сценария и документации, берет на себя пользователь. Корпорация Microsoft, ее штатные авторы и другие лица, принимающие участие в создании, подготовке и выпуске сценария, ни при каких обстоятельствах не несут ответственности за какой-либо ущерб (в том числе ущерб, вызванный потерей доходов предприятия, остановкой его работы, потерей бизнес-данных и другими материальными потерями), вызванный использованием или невозможностью использования примера сценария и документации, даже если корпорации Microsoft известно о возможности нанесения такого ущерба.

Этап 1. Подключение к Exchange Online PowerShell

Первый шаг — подключение к Exchange Online PowerShell. Вы можете подключиться с помощью современной проверки подлинности или многофакторной проверки подлинности (MFA). Пошаговые инструкции см. в статье Подключение к Exchange Online с помощью удаленной оболочки PowerShell.

Этап 2. Изменение и запуск сценария для получения записей аудита

После подключения к Exchange Online PowerShell необходимо создать, изменить и запустить сценарий для получения данных аудита. Первые семь строк сценария поиска в журнале аудита содержат указанные ниже переменные, которые можно изменить для настройки поиска. Описание этих переменных см. в таблице на шаге 2.

Сохраните приведенный ниже текст в сценарии Windows PowerShell, используя суффикс .ps1 в имени файла. Например, SearchAuditLog.ps1.

#Modify the values for the following variables to configure the audit log search.
$logFile = "d:\AuditLogSearch\AuditLogSearchLog.txt"
$outputFile = "d:\AuditLogSearch\AuditLogRecords.csv"
[DateTime]$start = [DateTime]::UtcNow.AddDays(-1)
[DateTime]$end = [DateTime]::UtcNow
$record = "AzureActiveDirectory"
$resultSize = 5000
$intervalMinutes = 60

#Start script
[DateTime]$currentStart = $start
[DateTime]$currentEnd = $end

Function Write-LogFile ([String]$Message)
{
    $final = [DateTime]::Now.ToUniversalTime().ToString("s") + ":" + $Message
    $final | Out-File $logFile -Append
}

Write-LogFile "BEGIN: Retrieving audit records between $($start) and $($end), RecordType=$record, PageSize=$resultSize."
Write-Host "Retrieving audit records for the date range between $($start) and $($end), RecordType=$record, ResultsSize=$resultSize"

$totalCount = 0
while ($true)
{
    $currentEnd = $currentStart.AddMinutes($intervalMinutes)
    if ($currentEnd -gt $end)
    {
        $currentEnd = $end
    }

    if ($currentStart -eq $currentEnd)
    {
        break
    }

    $sessionID = [Guid]::NewGuid().ToString() + "_" +  "ExtractLogs" + (Get-Date).ToString("yyyyMMddHHmmssfff")
    Write-LogFile "INFO: Retrieving audit records for activities performed between $($currentStart) and $($currentEnd)"
    Write-Host "Retrieving audit records for activities performed between $($currentStart) and $($currentEnd)"
    $currentCount = 0

    $sw = [Diagnostics.StopWatch]::StartNew()
    do
    {
        $results = Search-UnifiedAuditLog -StartDate $currentStart -EndDate $currentEnd -RecordType $record -SessionId $sessionID -SessionCommand ReturnLargeSet -ResultSize $resultSize

        if (($results | Measure-Object).Count -ne 0)
        {
            $results | export-csv -Path $outputFile -Append -NoTypeInformation

            $currentTotal = $results[0].ResultCount
            $totalCount += $results.Count
            $currentCount += $results.Count
            Write-LogFile "INFO: Retrieved $($currentCount) audit records out of the total $($currentTotal)"

            if ($currentTotal -eq $results[$results.Count - 1].ResultIndex)
            {
                $message = "INFO: Successfully retrieved $($currentTotal) audit records for the current time range. Moving on!"
                Write-LogFile $message
                Write-Host "Successfully retrieved $($currentTotal) audit records for the current time range. Moving on to the next interval." -foregroundColor Yellow
                ""
                break
            }
        }
    }
    while (($results | Measure-Object).Count -ne 0)

    $currentStart = $currentEnd
}

Write-LogFile "END: Retrieving audit records between $($start) and $($end), RecordType=$record, PageSize=$resultSize, total count: $totalCount."
Write-Host "Script complete! Finished retrieving audit records for the date range between $($start) and $($end). Total count: $totalCount" -foregroundColor Green

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

Переменная	Пример значения	Описание
`$logFile`	"d:\temp\AuditSearchLog.txt"	Определяет имя и расположение файла журнала с информацией о ходе поиска в журнале аудита, выполняемого сценарием. Сценарий записывает метки времени UTC в файл журнала.
`$outputFile`	"d:\temp\AuditRecords.csv"	Определяет имя и расположение CSV-файла, содержащего записи аудита, возвращаемые сценарием.
`[DateTime]$start` и `[DateTime]$end`	[DateTime]::UtcNow.AddDays(-1) [DateTime]::UtcNow	Определяет диапазон дат для поиска в журнале аудита. Скрипт возвращает записи о действиях аудита, произошедших в указанном диапазоне дат. Например, чтобы вернуть действия, выполненные в январе 2021 г., можно указать дату начала `"2021-01-01"` и дату окончания `"2021-01-31"` (обязательно заключите значения в кавычки). Пример значения в сценарии возвращает записи действий, совершенных за последние 24 часа. Если в значении не указана метка времени, по умолчанию к выбранной дате применяется метка времени 24:00 (полночь).
`$record`	"AzureActiveDirectory"	Определяет тип записи действий аудита (также называемых операциями) для поиска. Это свойство означает службу или функцию, в которой было инициировано действие. Чтобы просмотреть список типов записей, которые можно использовать для этой переменной, см. Тип записи журнала аудита. Можно использовать имя типа записи или значение перечисления. Совет. Для возврата записей аудита всех типов используйте значение `$null` (без кавычек).
`$resultSize`	5000	Определяет число результатов, возвращаемых каждый раз, когда сценарий вызывает командлет Search-UnifiedAuditLog (также называется результирующим набором). Максимальное значение, поддерживаемое командлетом, — 5000. Оставьте это значение без изменений.
`$intervalMinutes`	60	Чтобы помочь преодолеть ограничение в 5000 возвращаемых записей, эта переменная принимает указанный диапазон данных и разбивает его на меньшие интервалы времени. После этого ограничение в 5000 записей применяется не ко всему диапазону, а к каждому из меньших интервалов. Значение по умолчанию, равное 5000 записей на 60-минутный интервал в диапазоне дат, должно быть достаточно для большинства организаций. Но если сценарий вернул ошибку `maximum results limitation reached`, то уменьшите интервал времени (например, до 30 или даже до 15 минут) и повторно запустите сценарий.

Большинство переменных, перечисленных в предыдущей таблице, соответствует параметрам командлета Search-UnifiedAuditLog. Дополнительные сведения об этих параметрах см. в разделе Search-UnifiedAuditLog.

На локальном компьютере откройте Windows PowerShell и перейдите в папку, где сохранен измененный сценарий.
Запустите сценарий в Exchange Online PowerShell. Например:
```
.\SearchAuditLog.ps1
```

После запуска сценарий отображает сообщения о ходе выполнения. После завершения сценарий создает файл журнала и CSV-файл, содержащий записи аудита, и сохраняет их в папках, определяемых переменными $logFile и $outputFile.

Важно!

При каждом запуске командлета в сценарии предусмотрено максимальное ограничение в 50 000 записей аудита. Если сценарий вернул 50 000 результатов, вероятно, что в них не включены все записи аудита для действий, входящих в этот диапазон дат. В этом случае рекомендуется разбить диапазон на дат на меньшие интервалы и повторно запустить сценарий для каждого из таких интервалов. Например, если диапазон дат длительностью 90 дней содержит 50 000 результатов, то можно повторно запустить сценарий сначала для первых 45 дней, затем для последующих 45 дней.

Этап 3. Форматирование и просмотр записей аудита

После окончания работы сценария и экспорта записей аудита в CSV-файл этот файл можно форматировать, чтобы облегчить просмотр и анализ данных аудита. Один из способов сделать это — воспользоваться функцией преобразования Power Query JSON в Excel и разнести каждое свойство объекта JSON в столбце AuditData по отдельным столбцам. Пошаговые инструкции см. в пункте "Этап 2. Форматирование экспортированного журнала аудита с помощью редактора Power Query" в разделе Экспорт, настройка и просмотр записей журнала аудита.