Compartilhar via

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 precisar de obter registos de auditoria regularmente, deve considerar uma solução que utilize a API de Atividade de Gestão de Office 365, uma vez que pode proporcionar às grandes organizações a escalabilidade e o desempenho para obter milhões de registos de auditoria de forma contínua. Utilizar a ferramenta de pesquisa de registos de auditoria no portal do Microsoft Purview ou no portal de conformidade é uma boa forma de localizar 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 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 é um cliente E5, use a avaliação das soluções do Microsoft Purview de 90 dias para explorar como os 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 do Microsoft Purview. Saiba mais detalhes 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.

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

  • 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 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 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 devolve registos 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 ultrapassar o limite de 5000 registos devolvidos, esta variável utiliza o intervalo de dados que especificou e segmenta-o em intervalos de tempo mais pequenos. 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 predefinido de 5000 registos 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.