Compartir a través de

Procedimientos recomendados mediante la herramienta de cmdlets Search-UnifiedAuditLog

  • Artículo

El registro de auditoría es una herramienta que registra eventos de un rango de cargas de trabajo. El cmdlet Search-UnifiedAuditLog se puede usar para buscar y recuperar datos del registro de auditoría. Es importante comprender cómo usar este cmdlet de forma eficaz, especialmente cuando se trata de interpretar la información de la propiedad AuditData, ya que diferentes cargas de trabajo insertan diferentes tipos de información en esta propiedad.

De forma predeterminada, el cmdlet Search-UnifiedAuditLog devuelve 100 registros de auditoría para cualquier solicitud de búsqueda, a menos que especifique un número diferente de registros que se recuperarán mediante el parámetro ResultSize (hasta un máximo de 5000 registros).

Una sola búsqueda puede procesar un máximo de 50 000 registros de auditoría mediante la recuperación de páginas. Dado que el registro de auditoría puede contener una gran cantidad de datos, es importante ser lo más específico posible al usar parámetros de búsqueda para evitar devolver demasiados registros.

Para usar el cmdlet Search-UnifiedAuditLog, la cuenta debe tener el rol Registros de auditoría o Registros de auditoría de Exchange View-Only. Estos roles forman parte de los grupos de roles Administración de cumplimiento y Administración de la organización, y se pueden asignar a otros grupos de roles según sea necesario.

RecordTypes

RecordType es la carga de trabajo que generó el registro. Entre los ejemplos de diferentes tipos de eventos que se encuentran mediante el cmdlet Search-UnifiedAuditLog se incluyen:

  1. Agregar un miembro a un grupo de Microsoft Entra ID (AzureActiveDIrectory)
  2. Actualizar las propiedades del buzón en Exchange (ExchangeAdmin)
  3. Eliminación de un archivo en SharePoint (SharePointFileOperation)
  4. Registro de un usuario en Microsoft Teams (MicrosoftTeams)
  5. Latido AIP (AipHeartbeat)

Estos eventos se pueden buscar y realizar un seguimiento mediante el cmdlet Search-UnifiedAuditLog, que permite filtrar y ver los detalles de los eventos que se registran en el registro de auditoría unificado.

Estructura de datos de auditoría

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

Los registros de auditoría constan de dos partes: propiedades generales AuditData (propiedad)

Propiedades generales

Propiedades generales rellenadas de la misma manera por todas las cargas de trabajo y la propiedad AuditData que contiene información específica de la carga de trabajo. Las propiedades generales incluyen el tipo de registro, la fecha de creación, la operación y el identificador de usuario.

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 (propiedad)

Busque la información más importante sobre un evento mediante la propiedad AuditData. Las cargas de trabajo usan esquemas para describir las propiedades que insertan en los registros de auditoría y estos esquemas se usan para ayudar a interpretar la carga en los eventos de auditoría. Es posible que sea necesario realizar alguna prueba y error para comprender completamente la información de un registro de auditoría. Una guía de las propiedades detalladas de los registros de auditoría puede ser útil en este proceso. Los detalles sobre la acción realizada por un usuario se almacenan en formato de notación de objetos JavaScript (JSON), por lo que es necesario un procesamiento adicional para dar formato a los datos para extraer la información.

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
}

En la tabla siguiente se enumeran los detalles de la propiedad AuditData.

Parámetro Descripción
RecordType Tipo de carga de trabajo que generó el registro, como Microsoft Entra ID, Microsoft Teams, Exchange Administración o operación de archivo de SharePoint.
CreationTime Fecha y hora en formato UTC cuando se realizó la actividad.
Operación La operación registrada cuando alguien accede a un elemento, como FileViewed en el caso de SharePoint Online.
OrganizationId Identificador de inquilino único en forma de GUID.
UserKey La identidad que se usa para obtener acceso al elemento, normalmente lograda mediante la pertenencia a un grupo.
Carga de trabajo Nombre de la aplicación que registró el evento, como SharePoint Online, Exchange Online, OneDrive para la Empresa o Microsoft Entra ID.
ClientIP Dirección IP de la estación de trabajo cliente donde se originó la acción.
ObjectID Ruta de acceso completa al objeto al que se ha accedido.
UserID El Microsoft Entra identificador de cuenta de la cuenta que provocó la acción.
UserAgent El cliente usado para invocar la acción.
SourceFileName Nombre del archivo implicado en la acción.
UserType Tipo de usuario que realizó la acción, con valores de "0" (usuario normal), "1" (administrador) o "2" (administrador del centro de datos de Microsoft o cuenta del sistema).
EventSource Solo lo usa SharePoint Online, lo que indica si el origen era SharePoint o ObjectMode.
ResultIndex y ResultCount Las propiedades ResultIndex y ResultCount pueden ser útiles cuando se trabaja con grandes conjuntos de registros. ResultIndex indica el número de registro dentro del conjunto devuelto, mientras que ResultCount muestra el número total de registros devueltos. Por ejemplo, si ResultIndex es 1 y ResultCount es 125, significa que el registro mostrado es el primero de 125 devuelto en el conjunto.
Si la búsqueda encuentra un tiempo de espera interno, ResultIndex se establecerá en -1. A medida que los administradores obtengan experiencia con el registro de auditoría y los cmdlets de PowerShell, descubrirán que el registro de auditoría es una valiosa fuente de información para comprender quién interactuó con un documento o creó nuevos documentos durante un período de tiempo determinado. Es posible que se deba realizar alguna prueba y error para utilizar completamente la información proporcionada en los registros de auditoría.

Búsqueda de los eventos de conjunto correctos

Para encontrar los eventos adecuados al buscar en el registro de auditoría, es importante saber lo que está buscando y usar los filtros y parámetros adecuados. Esto puede ser complicado porque el registro de auditoría puede contener un gran número de eventos y buscar acciones específicas puede ser como buscar un objeto pequeño en una lista grande y desordenada de datos.

Una manera de abordar este problema es tomar medidas para generar un evento de auditoría para la acción que le interesa, esperar 60 minutos más o menos para permitir que el evento se ingiere en el registro de auditoría y, a continuación, buscar eventos dentro de ese período de tiempo.

Esto le proporcionará un conjunto más pequeño de eventos con los que trabajar, con el que puede analizar y usar para realizar búsquedas adicionales. También es una buena idea usar los valores de Operations / RecordTypes registrados para los eventos a fin de ayudarle a refinar las búsquedas y buscar los eventos específicos que está buscando.

A continuación se muestra un ejemplo de filtrado de datos mediante la búsqueda de operaciones muy específicas y en un intervalo de fechas determinado. Vea Tipos de registro para ver los tipos de registro que se pueden buscar.

El siguiente script busca una operación específica.

$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

El siguiente script busca un tipo de registro específico. En este ejemplo se usa para AipDiscover.

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

El script siguiente almacena el resultado en una matriz y busca un valor específico. En este ejemplo se usa 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"}

Administración de grandes cantidades de datos de auditoría

Si necesita recuperar un gran número de registros de auditoría de un inquilino grande o si necesita buscar varias operaciones durante un período prolongado, es probable que una sola búsqueda devuelva más de 5000 registros.

Para administrar grandes volúmenes de datos desde el cmdlet Search-UnifiedAuditLog, puede usar los parámetros ReturnLargeSet y ReturnNextPreviewPage. Estos parámetros permiten realizar búsquedas que devuelven grandes conjuntos de resultados y, a continuación, recuperar la siguiente página de resultados en búsquedas posteriores.

  1. Use el parámetro SessionId para identificar una sesión de búsqueda y especificar el número de páginas que desea recuperar. Esto permitirá al cmdlet capturar varias páginas de datos y devolverlas a usted.
  2. El parámetro SessionId también se usa cuando se desea buscar una gran cantidad de datos de auditoría mediante el cmdlet Search-UnifiedAuditLog. El cmdlet devolverá un máximo de 5000 registros por página, por lo que si desea buscar más, deberá usar el parámetro SessionId para identificar una sesión de búsqueda y especificar el número de páginas que desea recuperar. A continuación, el cmdlet usará el identificador de sesión para capturar las páginas de datos adicionales y devolverlas a usted.
  3. Si necesita buscar más de 50 000 registros, divida el trabajo entre varias búsquedas y use criterios diferentes para cada búsqueda.
  4. Almacene los resultados de las búsquedas en un repositorio externo, como Azure Log Analytics, Azure Data Explorer, para facilitar el acceso y el análisis.
  5. Revise y actualice periódicamente los criterios de búsqueda y audite los procesos de administración de datos para asegurarse de que captura los datos correctos y los administra de forma eficaz. Esto le ayudará a mantenerse al tanto de los posibles problemas de seguridad y mejorar la seguridad general de su organización.

Pasos para recuperar grandes cantidades de datos

Para capturar una gran cantidad de datos de auditoría, siga estos pasos:

  1. Generar un identificador de sesión.
  2. Use un bucle para recuperar datos en varias páginas.
  3. Ejecute repetidamente el comando Search-UnifiedAuditLog para capturar todos los datos disponibles.
  4. Guarde los datos de cada ejecución de Search-UnifiedAuditLog.
  5. Una vez capturadas todas las páginas, ordene los datos por fecha y expórelos a un archivo CSV.

Ejemplos

Search-UnifiedAuditLog tiene dos parámetros para admitir la recuperación de grandes conjuntos de datos, SessionID y SessionCommand. SessionID y SessionCommand se pueden combinar para procesar conjuntos de datos grandes. El parámetro SessionId contiene un valor de cadena para identificar una sesión de búsqueda. Puede usar cualquier valor que desee de un número simple a un GUID generado con el cmdlet New-Guid. La presencia de un identificador de sesión indica a Search-UnifiedAuditLog que podría necesitar capturar varias páginas de datos.

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

SessionCommand indica a Search-UnifiedAuditLog cómo controlar grandes cantidades de datos de auditoría. Los datos devueltos pueden contener registros duplicados. Este parámetro se puede establecer en:

  • ReturnLargeSet: los registros de auditoría devueltos no están ordenados. Puede capturar hasta 50 000 registros de auditoría mediante este método, pero debe recordar ordenar los datos una vez capturados.
  • ReturnNextPreviewPage: Search-UnifiedAuditLog devuelve registros de auditoría ordenados por fecha. Sin embargo, solo puede capturar un máximo de 5000 registros mediante este método. El número máximo de registros devueltos a través del uso de la paginación o del parámetro ResultSize es de 5000.

Nota:

Use siempre el mismo valor de SessionCommand para un valor SessionId determinado. No cambiar entre ReturnLargeSet y ReturnNextPreviewPage para el mismo identificador de sesión. De lo contrario, la salida está limitada a 10 000 resultados.

Script de ejemplo SessionId

En el ejemplo siguiente, el script importa primero el módulo Exchange Online Management y crea una conexión remota a Exchange Online. A continuación, establece las fechas de inicio y finalización de la búsqueda y usa el cmdlet Search-UnifiedAuditLog para buscar entradas en el registro de auditoría unificado dentro del intervalo de fechas especificado.

A continuación, el script usa un bucle foreach para examinar la matriz de registros devueltos por el cmdlet y procesa cada registro según sea necesario. En este caso, imprime el nombre de la operación y la identidad de usuario de cada registro.

# 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)"
}

Script de ejemplo ReturnLargeSet

En el ejemplo siguiente, el cmdlet Search-UnifiedAuditLog se usa para buscar entradas entre las horas de inicio y finalización especificadas en el registro de auditoría. El parámetro ReturnLargeSet se establece especificando los parámetros SessionId y SessionCommand en el objeto $parameters. A continuación, se recorren en bucle los resultados de la búsqueda y cada entrada se envía a la consola.

ReturnLargeSet: devuelve datos no ordenados. Mediante el uso de la paginación, puede tener acceso a un máximo de 50 000 resultados. Este es el valor recomendado si no se requiere un resultado ordenado y se ha optimizado para la latencia de búsqueda.

# 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
}

Script de ejemplo ReturnNextPreviewPage

El siguiente script realiza una búsqueda mediante el cmdlet Search-UnifiedAuditLog y el parámetro ReturnNextPreviewPage. La búsqueda se realiza con las horas de inicio y finalización especificadas. A continuación, los resultados de la búsqueda se envían a la consola.

# 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