Práticas recomendadas usando a ferramenta de cmdlet Search-UnifiedAuditLog

Artigo
04/04/2023

O log de auditoria é uma ferramenta que registra eventos de uma variedade de cargas de trabalho. O cmdlet Search-UnifiedAuditLog pode ser usado para pesquisar e recuperar dados do log de auditoria. É importante entender como usar esse cmdlet efetivamente, especialmente quando se trata de interpretar as informações na propriedade AuditData, pois cargas de trabalho diferentes inserem diferentes tipos de informações nessa propriedade.

Por padrão, o cmdlet Search-UnifiedAuditLog retorna 100 registros de auditoria para qualquer solicitação de pesquisa, a menos que você especifique um número diferente de registros para recuperar usando o parâmetro ResultSize (até um máximo de 5.000 registros).

Uma única pesquisa pode processar um máximo de 50.000 registros de auditoria usando a recuperação de página. Como o log de auditoria pode conter uma grande quantidade de dados, é importante ser o mais específico possível ao usar parâmetros de pesquisa para evitar o retorno de muitos registros.

Para usar o cmdlet Search-UnifiedAuditLog, sua conta deve ter a função Logs de Auditoria do Exchange View-Only ou Logs de Auditoria. Essas funções fazem parte dos grupos de funções gerenciamento de conformidade e gerenciamento de organizações e podem ser atribuídas a outros grupos de funções conforme necessário.

RecordTypes

Um RecordType é a carga de trabalho que gerou o registro. Exemplos de diferentes tipos de eventos encontrados usando o cmdlet Search-UnifiedAuditLog incluem:

Adicionar um membro a um grupo no Microsoft Entra ID (AzureActiveDIrectory)
Atualizar propriedades da caixa de correio no Exchange (ExchangeAdmin)
Excluir um arquivo no SharePoint (SharePointFileOperation)
Fazer logon de um usuário no Microsoft Teams (MicrosoftTeams)
Pulsação de AIP (AipHeartbeat)

Esses eventos podem ser pesquisados e rastreados usando o cmdlet Search-UnifiedAuditLog, o que permite filtrar e exibir os detalhes dos eventos registrados no log de auditoria unificado.

Estrutura auditar dados

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

Os registros de auditoria consistem em duas partes: propriedade AuditData de propriedades gerais

Propriedades gerais

Propriedades gerais que são preenchidas da mesma forma por todas as cargas de trabalho e pela propriedade AuditData que contém informações específicas da carga de trabalho. As propriedades gerais incluem o tipo de registro, a data de criação, a operação e o identificador de usuário.

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

Propriedade AuditData

Encontre as informações mais importantes sobre um evento usando a propriedade AuditData. As cargas de trabalho usam esquemas para descrever as propriedades que inserem em registros de auditoria e esses esquemas são usados para ajudar a interpretar a carga em eventos de auditoria. Pode exigir alguma avaliação e erro para entender completamente as informações em um registro de auditoria. Um guia para as propriedades detalhadas nos registros de log de auditoria pode ser útil nesse processo. Os detalhes sobre a ação tomada por um usuário são armazenados no formato JSON (Notação de Objeto JavaScript), portanto, o processamento adicional é necessário para formatar os dados para extrair as informações.

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
}

A tabela a seguir lista os detalhes da propriedade AuditData.

Parâmetro	Descrição
RecordType	O tipo de carga de trabalho que gerou o registro, como Microsoft Entra ID, Microsoft Teams, Exchange Administração ou Operação de Arquivo do SharePoint.
CreationTime	A data e a hora no formato UTC quando a atividade foi executada.
Operação	A operação foi registrada quando alguém acessa um item, como FileViewed no caso do SharePoint Online.
OrganizationId	O identificador de locatário exclusivo na forma de um GUID.
UserKey	A identidade usada para obter acesso ao item, normalmente obtida por meio da associação em um grupo.
Workload	O nome do aplicativo que registrou o evento, como SharePoint Online, Exchange Online, OneDrive for Business ou Microsoft Entra ID.
ClientIP	O endereço IP da estação de trabalho do cliente de onde a ação se originou.
ObjectID	O caminho completo para o objeto que foi acessado.
UserID	O identificador da conta Microsoft Entra para a conta que causou a ação.
UserAgent	O cliente usado para invocar a ação.
SourceFileName	O nome do arquivo envolvido na ação.
UserType	O tipo de usuário que realizou a ação, com valores de "0" (usuário regular), "1" (administrador) ou "2" (administrador de data center da Microsoft ou conta do sistema).
EventSource	Usado apenas pelo SharePoint Online, indicando se a origem era SharePoint ou ObjectMode.
ResultIndex e ResultCount	As propriedades ResultIndex e ResultCount podem ser úteis ao trabalhar com conjuntos de registros grandes. ResultIndex indica o número de registro dentro do conjunto retornado, enquanto ResultCount mostra o número total de registros retornados. Por exemplo, se ResultIndex for 1 e ResultCount for 125, isso significa que o registro mostrado é o primeiro de 125 retornados no conjunto. Se a pesquisa encontrar um tempo limite interno, ResultIndex será definido como -1. À medida que os administradores ganham experiência com o log de auditoria e os cmdlets do PowerShell, eles descobrirão que o log de auditoria é uma fonte valiosa de informações para entender quem interagiu com um documento ou criou novos documentos durante um determinado período de tempo. Pode ser necessário algum erro e avaliação para utilizar totalmente as informações fornecidas nos registros de auditoria.

Localizar os eventos de conjunto corretos

Para encontrar os eventos certos ao pesquisar o log de auditoria, é importante saber o que você está procurando e usar os filtros e parâmetros apropriados. Isso pode ser desafiador porque o log de auditoria pode conter um grande número de eventos e procurar ações específicas pode ser como procurar um objeto pequeno em uma lista de dados grande e desordenada.

Uma maneira de abordar esse problema é tomar medidas para gerar um evento de auditoria para a ação em que você está interessado, aguardar por 60 minutos ou mais para permitir que o evento seja ingerido no log de auditoria e, em seguida, pesquisar eventos nesse período.

Isso lhe dará um conjunto menor de eventos para trabalhar, com os quais você pode analisar e usar para executar novas pesquisas. Também é uma boa ideia usar os valores do Operations / RecordTypes registrados para os eventos para ajudá-lo a refinar suas pesquisas e encontrar os eventos específicos que você está procurando.

A seguir está um exemplo de filtragem de dados procurando operações muito específicas e em um determinado intervalo de datas. Exibir Tipos de Registro para ver os tipos de registro que podem ser procurados.

O script a seguir procura uma operação 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

O script a seguir pesquisa um tipo de registro específico. Este exemplo 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

O script a seguir armazena o resultado em uma matriz e pesquisa um valor específico. Esses exemplos usam 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"}

Gerenciar grandes quantidades de dados de auditoria

Se você precisar recuperar um grande número de registros de auditoria de um locatário grande ou se precisar pesquisar várias operações por um longo período, é provável que uma única pesquisa retorne mais de 5.000 registros.

Para gerenciar grandes volumes de dados do cmdlet Search-UnifiedAuditLog, você pode usar os parâmetros ReturnLargeSet e ReturnNextPreviewPage. Esses parâmetros permitem que você execute pesquisas que retornam grandes conjuntos de resultados e recupere a próxima página de resultados em pesquisas subsequentes.

Use o parâmetro SessionId para identificar uma sessão de pesquisa e especificar o número de páginas que você deseja recuperar. Isso permitirá que o cmdlet busque várias páginas de dados e os retorne para você.
O parâmetro SessionId também é usado quando você deseja pesquisar uma grande quantidade de dados de auditoria usando o cmdlet Search-UnifiedAuditLog. O cmdlet retornará um máximo de 5.000 registros por página, portanto, se você quiser pesquisar mais do que isso, precisará usar o parâmetro SessionId para identificar uma sessão de pesquisa e especificar o número de páginas que você deseja recuperar. Em seguida, o cmdlet usará o identificador de sessão para buscar as páginas adicionais dos dados e devolvê-los a você.
Se você precisar pesquisar mais de 50.000 registros, divida o trabalho em várias pesquisas e use critérios diferentes para cada pesquisa.
Armazene os resultados das pesquisas em um repositório externo, como análise de log do Azure, Data Explorer do Azure, para fácil acesso e análise.
Examine e atualize regularmente seus critérios de pesquisa e audite processos de gerenciamento de dados para garantir que você esteja capturando os dados certos e gerenciando-os com eficiência. Isso ajudará você a se manter em cima de possíveis problemas de segurança e melhorar a segurança geral da sua organização.

Etapas para recuperar grandes quantidades de dados

Para buscar uma grande quantidade de dados de auditoria, siga estas etapas:

Gerar um identificador de sessão.
Use um loop para recuperar dados em várias páginas.
Execute repetidamente o comando Search-UnifiedAuditLog para buscar todos os dados disponíveis.
Salve os dados de cada execução do Search-UnifiedAuditLog.
Depois que todas as páginas forem buscadas, classifique os dados por data e exporte-os para um arquivo CSV.

Exemplos

Search-UnifiedAuditLog tem dois parâmetros para dar suporte à recuperação de grandes conjuntos de dados, SessionID e SessionCommand. SessionID e SessionCommand podem ser combinados para processar conjuntos de dados grandes. O parâmetro SessionId contém um valor de cadeia de caracteres para identificar uma sessão de pesquisa. Você pode usar qualquer valor que quiser de um número simples para um GUID gerado com o cmdlet New-Guid. A presença de um identificador de sessão informa Search-UnifiedAuditLog que talvez seja necessário buscar várias páginas de dados.

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

O SessionCommand informa Search-UnifiedAuditLog como lidar com grandes quantidades de dados de auditoria. Os dados retornados podem conter registros duplicados. Esse parâmetro pode ser definido como:

ReturnLargeSet: os registros de auditoria retornados não são variados. Você pode buscar até 50.000 registros de auditoria usando esse método, mas deve se lembrar de classificar os dados depois que todos eles forem buscados.
ReturnNextPreviewPage: Search-UnifiedAuditLog retorna registros de auditoria classificados por data. No entanto, você pode buscar apenas um máximo de 5.000 registros usando esse método. O número máximo de registros retornados por meio do uso da paginação ou do parâmetro ResultSize é de 5.000.

Observação

Sempre use o mesmo valor SessionCommand para um determinado valor SessionId. Não alterne entre ReturnLargeSet e ReturnNextPreviewPage para a mesma ID de sessão. Caso contrário, a saída será limitada a 10.000 resultados.

Script de exemplo SessionId

No exemplo a seguir, o script primeiro importa o módulo gerenciamento de Exchange Online e cria uma conexão remota com Exchange Online. Em seguida, ele define as datas de início e término da pesquisa e usa o cmdlet Search-UnifiedAuditLog para pesquisar o Log de Auditoria Unificada para obter entradas dentro do intervalo de datas especificado.

Em seguida, o script usa um loop foreach para examinar a matriz de registros retornados pelo cmdlet e processa cada registro conforme necessário. Nesse caso, ele imprime o nome da operação e a identidade do usuário para 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 exemplo ReturnLargeSet

No exemplo a seguir, o cmdlet Search-UnifiedAuditLog é usado para pesquisar o log de auditoria em busca de entradas entre os horários de início e término especificados. O parâmetro ReturnLargeSet é definido especificando os parâmetros SessionId e SessionCommand no objeto $parameters. Os resultados da pesquisa são então passados em loop e cada entrada é saída para o console.

ReturnLargeSet: retorna dados não variados. Você pode ter acesso a no máximo 50.000 resultados usando a paginação. Esse é o valor recomendado se um resultado ordenado não for necessário e tiver sido otimizado para latência de pesquisa.

# 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 exemplo ReturnNextPreviewPage

O script a seguir executa uma pesquisa usando o cmdlet Search-UnifiedAuditLog e o parâmetro ReturnNextPreviewPage. A pesquisa é realizada usando os horários de início e término especificados. Os resultados da pesquisa são então gerados para o console.

# 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

Partilhar via