Usar um script Windows PowerShell para pesquisar o log de auditoria

Segurança, conformidade e auditoria se tornaram as principais prioridades dos administradores de TI no mundo de hoje. O Microsoft 365 tem vários recursos integrados para ajudar as organizações a gerenciar a segurança, conformidade e auditoria. Em particular, o registro de auditoria unificado pode ajudá-lo a investigar incidentes de segurança e problemas de conformidade. Você pode recuperar registros de auditoria usando os seguintes métodos:

• API da Atividade de Gestão do Office 365
• A ferramenta de pesquisa de log de auditoria no portal do Microsoft Purview ou no portal de conformidade do Microsoft Purview.
• O cmdlet Search-UnifiedAuditLog no Exchange Online Windows PowerShell

Se você precisar recuperar logs de auditoria regularmente, considere uma solução que usa a API de Atividade de Gerenciamento de Office 365 porque ela pode fornecer às grandes organizações a escalabilidade e o desempenho para recuperar milhões de registros de auditoria em uma base contínua. Usar a ferramenta de pesquisa de log de auditoria no portal do Microsoft Purview ou no portal de conformidade é uma boa maneira de localizar rapidamente registros de auditoria para operações específicas que ocorrem em um intervalo de tempo menor. O uso de intervalos de tempo mais longos na ferramenta de pesquisa de log de auditoria, especialmente para grandes organizações, pode retornar muitos registros para gerenciar ou exportar facilmente.

Quando há situações em que você precisa recuperar manualmente os dados de auditoria para uma investigação ou incidente específico, especialmente para intervalos de datas mais longos em organizações maiores, usar o cmdlet Search-UnifiedAuditLog pode ser a melhor opção. Este artigo inclui um script do PowerShell que usa o cmdlet que pode recuperar 50.000 registros de auditoria (cada vez que você executar o cmdlet) e, em seguida, exportá-los para um arquivo CSV que você pode formatar usando o Power Query no Excel para ajudar na sua revisão. O uso do script neste artigo também minimiza a chance de que grandes pesquisas de log de auditoria expirem no serviço.

Antes de executar o script

• O log de Auditoria deve ser habilitado para que sua organização use com sucesso o script para retornar os registros de auditoria. O log de Auditoria é ativado por padrão para organizações empresariais Microsoft 365 e Office 365. Para verificar se a pesquisa de log de auditoria está ativada para sua organização, você pode executar o seguinte comando no Exchange Online Windows PowerShell:

  Get-AdminAuditLogConfig | FL UnifiedAuditLogIngestionEnabled
  

  O valor de True para a propriedade UnifiedAuditLogIngestionEnabled indica que a pesquisa de registro de auditoria está ativada.

• Você deve receber a função Logs de Auditoria somente exibição ou Logs de Auditoria no Exchange Online para executar o script com êxito. Por padrão, essas funções são atribuídas aos grupos de função Gerenciamento de Conformidade e Gerenciamento da Organização na página Permissões do centro de administração do Exchange.

• O script pode demorar muito para ser concluído. Quanto tempo leva para ser executado depende do intervalo de datas e do tamanho do intervalo para o qual você configura o script para recuperar os registros de auditoria. Intervalos de datas maiores e intervalos menores resultam em um longo tempo de execução. Confira a tabela na Etapa 2 para obter mais informações sobre o intervalo de datas e intervalos.

• O script de exemplo fornecido neste artigo não é compatível com nenhum programa ou serviço de suporte padrão da Microsoft. O script de amostra é fornecido COMO ESTÁ, sem garantia de nenhum tipo. A Microsoft também se isenta de todas as garantias implícitas, incluindo, sem limitação, quaisquer garantias implícitas de comercialização ou adequação a uma finalidade específica. Todo o risco decorrente do uso ou desempenho do script de amostra e da documentação permanece com você. Em nenhuma hipótese a Microsoft, seus autores ou qualquer outra pessoa envolvida na criação, produção ou entrega do script será responsável por quaisquer danos (incluindo, sem limitação, danos por perda de lucros comerciais, interrupção de negócios, perda de informações comerciais, ou outra perda pecuniária) decorrente do uso ou da incapacidade de usar o script ou documentação de amostra, mesmo que a Microsoft tenha sido avisada da possibilidade de tais danos.

Etapa 1: Conecte-se ao Exchange Online Windows PowerShell

A primeira etapa é conectar-se ao Exchange Online Windows PowerShell. Você pode se conectar usando a autenticação moderna ou com a autenticação multifator (MFA). Para obter instruções passo a passo, confira Conectar-se ao Exchange Online Windows PowerShell.

Etapa 2: modificar e executar o script para recuperar os registros de auditoria

Depois de se conectar ao Exchange Online Windows PowerShell, a próxima etapa é criar, modificar e executar o script para recuperar os dados de auditoria. As primeiras sete linhas no script de pesquisa de log de auditoria contêm as seguintes variáveis ​​que você pode modificar para configurar sua pesquisa. Consulte a tabela na etapa 2 para obter uma descrição dessas variáveis.

1. Salve o texto a seguir em um script do Windows PowerShell usando um sufixo de nome de arquivo .ps1. Por exemplo, 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 as variáveis ​​listadas na tabela a seguir para configurar os critérios de pesquisa. O script inclui valores de amostra para essas variáveis, mas você deve alterá-los (a menos que indicado de outra forma) para atender aos seus requisitos específicos.

   
   

A maioria das variáveis ​​listadas na tabela anterior correspondem aos parâmetros do cmdlet Search-UnifiedAuditLog. Para obter mais informações sobre esses parâmetros, confiraSearch-UnifiedAuditLog.

3. No seu computador local, abra o Windows PowerShell e vá para a pasta onde você salvou o script modificado.

4. Execute o script no Exchange Online Windows PowerShell; por exemplo:

   .\SearchAuditLog.ps1
   

O script exibe mensagens de progresso durante a execução. Após a conclusão da execução do script, ele cria o arquivo de log e o arquivo CSV que contém os registros de auditoria e os salva nas pastas definidas pelas variáveis ​​$logFile e $outputFile.

Etapa 3: formate e visualize os registros de auditoria

Depois de executar o script e exportar os registros de auditoria para um arquivo CSV, você pode formatar o CSV para facilitar a revisão e análise dos registros de auditoria. Uma maneira de fazer isso é usar o recurso de transformação JSON do Power Query no Excel para dividir cada propriedade no objeto JSON na coluna AuditData em sua própria coluna. Para obter instruções passo a passo, consulte "Etapa 2: formatar o registro de auditoria exportado usando o Power Query Editor" em Exportar, configurar e visualizar registros de registro de auditoria.