Usar um script Windows PowerShell para pesquisar o log de auditoria

  • Artigo

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:

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.

Dica

Se você não for um cliente E5, use a avaliação de soluções do Microsoft Purview de 90 dias para explorar como recursos adicionais do Purview podem ajudar sua organização a gerenciar as necessidades de segurança e conformidade de dados. Comece agora no hub de avaliações portal de conformidade do Microsoft Purview. Saiba mais sobre os termos de inscrição e avaliaçã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.


Variável Valor de amostra Descrição
$logFile "d:\temp\AuditSearchLog.txt" Especifica o nome e a localização do arquivo de log que contém informações sobre o andamento da pesquisa de log de auditoria executada pelo script. O script grava carimbos de data/hora UTC no arquivo de log.
$outputFile "d:\temp\AuditRecords.csv" Especifica o nome e a localização do arquivo CSV que contém os registros de auditoria retornados pelo script.
[DateTime]$start e [DateTime]$end [DateTime]::UtcNow.AddDays(-1)
[DateTime]::UtcNow		 Especifica o intervalo de datas para a pesquisa do log de auditoria. O script retorna registros para atividades de auditoria que ocorreram dentro do intervalo de datas especificado. Por exemplo, para retornar atividades realizadas em janeiro de 2021, você pode usar uma data de início de "2021-01-01"e uma data de término de"2021-01-31" (certifique-se de colocar os valores entre aspas duplas). O valor de amostra no script retorna registros para atividades realizadas nas 24 horas anteriores. Se você não incluir um carimbo de data/hora no valor, o carimbo de data/hora padrão será 0h (meia-noite) na data especificada.
$record AzureActiveDirectory Especifica o tipo de registro das atividades de auditoria (também chamadas de operações) a serem pesquisadas. Esta propriedade indica o serviço ou recurso em que uma atividade foi acionada. Para obter uma lista dos tipos de registro que você pode usar para esta variável, confira Tipo de registro do log de Auditoria. Você pode usar o nome do tipo de registro ou valor ENUM.

Dica: para retornar registros de auditoria para todos os tipos de registro, use o valor $null (sem aspas duplas).
$resultSize 5000 Especifica o número de resultados retornados sempre que o cmdlet Search-UnifiedAuditLog é chamado pelo script (chamado de conjunto de resultados). O valor de 5.000 é o valor máximo compatível com o cmdlet. Deixe este valor como está.
$intervalMinutes 60 Para ajudar a superar o limite de 5.000 registros retornados, essa variável usa o intervalo de dados especificado e o corta em intervalos de tempo menores. Agora, cada intervalo, não todo o intervalo de datas, está sujeito ao limite de saída de 5.000 registros do comando. O valor padrão de 5.000 registros por intervalo de 60 minutos dentro do intervalo de datas deve ser suficiente para a maioria das organizações. Mas, se o script retornar um erro que diz, maximum results limitation reached, diminua o intervalo de tempo (por exemplo, para 30 minutos ou mesmo 15 minutos) e execute o script novamente.

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. 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.

Importante

Há um limite de 50.000 para o número máximo de registros de auditoria devolvidos cada vez que você executa o cmdlet no script. Se você executar este script e ele retornar 50.000 resultados, é provável que os registros de auditoria para atividades que ocorreram dentro do intervalo de datas não foram incluídos. Se isso acontecer, recomendamos que você divida o período em durações menores e execute novamente o script para cada período. Por exemplo, se um intervalo de datas de 90 dias retornar 50.000 resultados, você poderá executar o script novamente duas vezes, uma nos primeiros 45 dias do intervalo e, em seguida, nos próximos 45 dias.

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.