Usar um script Windows PowerShell para pesquisar o log de auditoria

A segurança, a conformidade e a auditoria são as principais prioridades para os administradores de TI. 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 registos de auditoria no portal do Microsoft Purview
• O cmdlet Search-UnifiedAuditLog no Exchange Online Windows PowerShell

Se precisar de obter regularmente registos de auditoria, considere uma solução que utilize a API de Atividade de Gestão de Office 365. Fornece às grandes organizações a escalabilidade e o desempenho para obter milhões de registos de auditoria de forma contínua. A utilização da ferramenta de pesquisa de registos de auditoria no portal do Microsoft Purview é uma boa forma de encontrar rapidamente registos de auditoria para operações específicas que ocorrem num intervalo de tempo mais curto. 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 precisar de obter manualmente dados de auditoria para uma investigação ou incidente específico, especialmente para intervalos de datas mais longos em organizações maiores, a utilização do cmdlet Search-UnifiedAuditLog poderá ser a melhor opção. Este artigo inclui um script do PowerShell que utiliza o cmdlet . O script pode obter 50 000 registos de auditoria sempre que executar o cmdlet e, em seguida, exportá-los para um ficheiro CSV. Pode formatar o ficheiro ao utilizar Power Query no Excel para ajudar na sua revisão. A utilização do script neste artigo também minimiza a probabilidade de pesquisas de registos de auditoria grandes exceder o tempo limite no serviço.

Antes de executar o script

• O registo de auditoria tem de estar ativado para que a sua organização utilize o script com êxito para devolver registos 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 registos de auditoria está ativada para a sua organização, execute o seguinte comando no Exchange Online PowerShell:

  Get-AdminAuditLogConfig | FL UnifiedAuditLogIngestionEnabled
  

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

• Tem de lhe ser atribuída a função Registos de Auditoria ou Registos de Auditoria Apenas de Visualização 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.

• Pode demorar muito tempo até que o script seja 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 num tempo de execução longo. 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 exemplo é fornecido tal como está sem qualquer tipo de garantia. 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

Primeiro, ligue-se ao Exchange Online PowerShell. Pode ligar através da autenticação moderna ou da 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 ligar ao Exchange Online PowerShell, crie, modifique e execute o script para obter 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 exemplo para estas variáveis, mas altere-os (salvo indicação em contrário) para cumprir os 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.

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

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

   .\SearchAuditLog.ps1
   

O script exibe mensagens de progresso durante a execução. Depois de o script terminar de ser executado, cria o ficheiro de registo e o ficheiro de .csv que contém os registos de auditoria e guarda-os nas pastas definidas pelas $logFile variáveis e $outputFile .

Etapa 3: formate e visualize os registros de auditoria

Depois de executar o script e exportar os registos de auditoria para um ficheiro de .csv, poderá querer formatar o .csv para facilitar a revisão e análise dos registos de auditoria. Uma forma de o fazer é utilizar a funcionalidade de transformação JSON Power Query no Excel para dividir cada propriedade no objeto JSON na coluna AuditData na 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.