Usar un script de PowerShell para buscar en el registro de auditoría

La seguridad, el cumplimiento y la auditoría son prioridades principales para los administradores de TI. Microsoft 365 cuenta con varias capacidades integradas para ayudar a las organizaciones a administrar la seguridad, el cumplimiento y la auditoría. En particular, un registro unificado de auditoría puede ayudarle a investigar incidentes de seguridad y problemas relacionados con el cumplimiento. Puede recuperar los registros de auditoría mediante los siguientes métodos:

• API de Actividad de administración de Office 365
• Herramienta de búsqueda de registros de auditoría en el portal de Microsoft Purview
• El cmdlet Search-UnifiedAuditLog en Exchange Online PowerShell

Si necesita recuperar periódicamente los registros de auditoría, considere la posibilidad de usar una solución que use la API de actividad de administración de Office 365. Proporciona a las organizaciones grandes la escalabilidad y el rendimiento para recuperar millones de registros de auditoría de forma continuada. El uso de la herramienta de búsqueda de registros de auditoría en el portal de Microsoft Purview es una buena manera de encontrar rápidamente registros de auditoría para operaciones específicas que se producen en un intervalo de tiempo más corto. Utilizar intervalos de tiempo mayores en la herramienta de búsqueda en el registro de auditoría, especialmente en el caso de grandes organizaciones, puede entregar un número de registros demasiado elevado como para poderlos administrar o exportar con facilidad.

Cuando necesite recuperar manualmente los datos de auditoría para una investigación o incidente específico, especialmente para intervalos de fechas más largos en organizaciones más grandes, el uso del cmdlet Search-UnifiedAuditLog podría ser la mejor opción. En este artículo se incluye un script de PowerShell que usa el cmdlet . El script puede recuperar 50 000 registros de auditoría cada vez que ejecute el cmdlet y luego exportarlos a un archivo CSV. Puede dar formato al archivo mediante Power Query en Excel para ayudarle con la revisión. El uso del script de este artículo también minimiza la posibilidad de que las búsquedas de registros de auditoría de gran tamaño agote el tiempo de espera en el servicio.

Antes de ejecutar el script:

• El registro de auditoría debe estar habilitado para que la organización use correctamente el script para devolver registros de auditoría. El registro de auditoría está activado de forma predeterminada para organizaciones de Microsoft 365 y Office 365 Enterprise. Para comprobar que la búsqueda de registros de auditoría está activada para su organización, ejecute el siguiente comando en Exchange Online PowerShell:

  Get-AdminAuditLogConfig | FL UnifiedAuditLogIngestionEnabled
  

  El valor de True para la propiedad UnifiedAuditLogIngestionEnabled indica que la búsqueda de registros de auditoría está activada.

• Debe tener asignado el rol Registros de auditoría de solo vista o Registros de auditoría en Exchange Online para ejecutar correctamente el script. De forma predeterminada, estos roles se asignan a los grupos de roles Administración de cumplimiento y Administración de la organización en la página Permisos del Centro de administración de Exchange.

• El script puede tardar mucho tiempo en completarse. El tiempo que tarde en ejecutarse dependerá del intervalo de fechas y el tamaño del intervalo que establezca en la configuración del script para recuperar registros de auditoría. Los intervalos de fechas más grandes y los intervalos más pequeños dan como resultado un tiempo de ejecución largo. Consulte la tabla en el Paso 2 para más información sobre los intervalos de fechas.

• El script de ejemplo que aparece en este artículo no es compatible con ningún programa o servicio de soporte técnico estándar de Microsoft. El script de ejemplo se proporciona tal cual sin garantía de ningún tipo. Además, Microsoft no se hace responsable de cualquier garantía implícita, incluyendo, de manera enunciativa pero no limitativa, cualquier garantía implícita de comercialización o de calidad para cualquier propósito. Cualquier riesgo resultante del uso o rendimiento del script y la documentación de ejemplo será únicamente responsabilidad suya. En ningún caso Microsoft, sus autores o cualquier persona involucrada en su creación, producción o entrega del script será responsable de cualquier daño (incluidos, de manera enunciativa pero no limitativa, daños por pérdidas de beneficios de una empresa, interrupción de la actividad de una empresa, pérdidas de información de una empresa, o cualquier otro daño pecuniario), incluso si Microsoft supiera de la posibilidad de tales daños.

Paso 1: Conectar con Exchange Online PowerShell

En primer lugar, conéctese a Exchange Online PowerShell. Puede conectarse mediante la autenticación moderna o la autenticación multifactor (MFA). Para obtener instrucciones, consulte Conexión a Exchange Online PowerShell.

Paso 2: modificar y ejecutar el script para recuperar registros de auditoría

Después de conectarse a Exchange Online PowerShell, cree, modifique y ejecute el script para recuperar los datos de auditoría. Las primeras siete líneas del script de búsqueda en el registro de auditoría contienen las siguientes variables que puede modificar para configurar la búsqueda. Consulte la tabla del paso 2 para obtener una descripción de dichas variables.

1. Guarde el siguiente texto en un script de Windows PowerShell mediante un sufijo de nombre de archivo de .ps1. Por ejemplo, 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
   

2. Modifique las variables que se enumeran en la siguiente tabla para configurar los criterios de búsqueda. El script incluye valores de ejemplo para estas variables, pero cámbielos (a menos que se indique lo contrario) para satisfacer sus requisitos específicos.

   
   

La mayoría de las variables enumeradas en la tabla anterior se corresponden con parámetros para el cmdlet Search-UnifiedAuditLog. Para obtener más información acerca de estos parámetros, consulte Search-UnifiedAuditLog.

1. En su equipo local, abra Windows PowerShell y vaya a la carpeta en la que guardó el script modificado.

2. Ejecute el script en Exchange Online PowerShell, por ejemplo:

   .\SearchAuditLog.ps1
   

El script muestra mensajes de progreso durante la ejecución. Una vez que el script termina de ejecutarse, crea el archivo de registro y el archivo de .csv que contiene los registros de auditoría y los guarda en las carpetas definidas por las $logFile variables y $outputFile .

Paso 3: Dar formato y visualizar los registros de auditoría

Después de ejecutar el script y exportar los registros de auditoría a un archivo .csv, es posible que desee dar formato a la .csv para facilitar la revisión y el análisis de los registros de auditoría. Una manera de hacerlo es usar la característica de transformación JSON Power Query en Excel para dividir cada propiedad del objeto JSON de la columna AuditData en su propia columna. Para obtener instrucciones paso a paso, consulte «Paso 2: Dar formato al registro de auditoría exportado mediante el Editor de Power Query» en Exportar, configurar y ver los archivos de registros de auditoría.