Utiliser un script PowerShell pour effectuer une recherche dans le journal d’audit

  • Article

La sécurité, la conformité et l’audit sont désormais une priorité absolue pour les administrateurs informatiques du monde actuel. Microsoft 365 offre plusieurs fonctionnalités intégrées pour aider les organisations à gérer la sécurité, la conformité et l’audit. En particulier, la journalisation d’audit unifiée peut vous aider à examiner les incidents de sécurité et les problèmes de conformité. Vous pouvez récupérer les journaux d’audit à l’aide des méthodes suivantes :

Si vous avez besoin de récupérer régulièrement des journaux d’audit, vous devez envisager une solution qui utilise l’API d’activité de gestion Office 365, car elle peut fournir aux grandes organisations la scalabilité et les performances nécessaires pour récupérer des millions d’enregistrements d’audit en continu. L’utilisation de l’outil de recherche de journal d’audit dans le portail Microsoft Purview ou le portail de conformité est un bon moyen de trouver rapidement des enregistrements d’audit pour des opérations spécifiques qui se produisent dans un intervalle de temps plus court. L’utilisation de plages de temps plus longues dans l’outil de recherche dans le journal d’audit, en particulier pour les grandes organisations, peut renvoyer trop d’enregistrements pour être facilement gérables ou exportés.

Lorsque vous devez récupérer manuellement des données d’audit pour une enquête ou un incident spécifique, en particulier pour les plages de dates plus longues dans les grandes organisations, il peut être préférable d’utiliser la commande cmdlet Search-UnifiedAuditLog. Cet article inclut un script PowerShell qui utilise l'applet de commande qui peut récupérer 50 000 enregistrements d'audit (à chaque fois que vous exécutez l'applet de commande), puis les exporter vers un fichier CSV que vous pouvez formater à l'aide de Power Query dans Excel pour vous aider dans votre révision. L’utilisation du script décrit dans cet article réduit également le risque de délai d’utilisation des recherches importantes dans le journal d’audit dans le service.

Conseil

Si vous n’êtes pas un client E5, utilisez la version d’évaluation de 90 jours des solutions Microsoft Purview pour découvrir comment des fonctionnalités Supplémentaires purview peuvent aider vos organization à gérer les besoins en matière de sécurité et de conformité des données. Commencez dès maintenant au hub d’essais portail de conformité Microsoft Purview. En savoir plus sur les conditions d’inscription et d’essai.

Avant d’exécuter l’exemple de code :

  • La journalisation d’audit doit être activée pour que votre organisation utilise le script pour renvoyer des enregistrements d’audit. Nous activons par défaut la journalisation d’audit pour les organisations d’entreprise Microsoft 365 et Office 365. Pour vérifier que vous avez activé la recherche dans le journal d’audit pour votre organisation, vous pouvez exécuter la commande suivante dans Exchange Online PowerShell :

    Get-AdminAuditLogConfig | FL UnifiedAuditLogIngestionEnabled

    La valeur True de la propriété UnifiedAuditLogIn élémentsenabled indique que vous avez activé la recherche dans le journal d’audit.

  • Le rôle Afficher uniquement journaux d’audit ou Journaux d’audit doit vous être attribué dans Exchange Online pour exécuter correctement le script. Par défaut, ces rôles sont attribués aux groupes de rôles Gestion de la conformité et Gestion de l’organisation sur la page Autorisations dans le Centre d’administration Exchange.

  • La fin du script peut prendre un certain temps. Le temps d’exécuter dépend de la plage de dates et de la taille de l’intervalle pour laquelle vous configurez le script afin de récupérer les enregistrements d’audit. Des plages de dates plus grandes et des intervalles plus petits entraînent une durée d’exécution longue. Pour plus d’informations sur la plage de dates et les intervalles, consultez le tableau de l’étape 2.

  • L’exemple de script fourni dans cet article n’est pas pris en charge par les services ou programmes d’assistance standard de Microsoft. L’exemple de script est fourni tel quel, sans garantie d’aucune sorte. Microsoft Corporation décline aussi toute garantie implicite, y compris et sans limitation, les garanties implicites de qualité marchande ou d’adéquation à un usage particulier. La totalité des risques découlant de l’utilisation ou de la performance de l’exemple de script et de la documentation repose sur vous. En aucun cas Microsoft, ses auteurs ou quiconque impliqué dans la création, la production ou la livraison de script ne sera responsable de tous dommages quels qu’ils soient (y compris, sans limitation, les dommages pour perte de profits, interruption d’activité, perte d’informations commerciales ou toute autre perte pécuniaire) découlant de l’utilisation ou de l’impossibilité d’utiliser l’exemple de script ou la documentation, même si Microsoft a été informé de la possibilité de tels dommages.

Étape 1 : Connexion à Exchange Online PowerShell

La première étape consiste à se connecter à Exchange Online PowerShell. Vous pouvez vous connecter à l'aide de l'authentification moderne ou de l'authentification multifacteur (MFA). Pour obtenir des instructions, consultez Connexion à Exchange Online PowerShell.

Étape 2 : modifier et exécuter le script pour récupérer les enregistrements d’audit

Une fois que vous êtes connecté à Exchange Online PowerShell, l’étape suivante consiste à créer, modifier et exécuter le script afin de récupérer les données d’audit. Les sept premières lignes du script de recherche dans le journal d’audit contiennent les variables suivantes que vous pouvez modifier pour configurer votre recherche. Consultez le tableau à l’étape 2 pour obtenir une description de ces variables.

  1. Enregistrez le texte suivant dans un fichier de script Windows PowerShell à l'aide du suffixe de nom de fichier .ps1. Par exemple, 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. Modifiez les variables répertoriées dans le tableau suivant pour configurer les critères de recherche. Le script inclut des exemples de valeurs pour ces variables, mais vous devez les modifier (sauf indication contraire) pour répondre à vos exigences spécifiques.


Variable Exemple de valeur Description
$logFile "d:\temp\AuditSearchLog.txt" Indique le nom et l’emplacement du fichier journal qui contient des informations sur la progression de la recherche dans le journal d’audit effectuée par le script. Le script écrit les horodatages UTC sur le fichier d’audit.
$outputFile "d:\temp\AuditRecords.csv" Indique le nom et l’emplacement du fichier CSV contenant les enregistrements d’audit renvoyés par le script.
[DateTime]$start et [DateTime]$end [DateTime]::UtcNow.AddDays(-1)
[DateTime]::UtcNow		 Spécifie la plage de dates pour la recherche dans le journal d’audit. Le script retourne des enregistrements pour les activités d’audit qui se sont produites dans la plage de dates spécifiée. Par exemple, pour renvoyer les activités effectuées en janvier 2021, vous pouvez utiliser une date de début de "2021-01-01" et une date de fin de "2021-01-31" (n’oubliez pas d’entourer les valeurs de guillemets doubles) La valeur d’exemple dans le script renvoie les enregistrements des activités effectuées au cours des 24 heures précédentes. si vous n’incluez pas d’horodatage dans la valeur, l’horodatage par défaut est 00:00 (minuit) pour la date spécifiée.
$record « AzureActiveDirectory » Spécifie le type d’enregistrement des activités d’audit (également opérations) à rechercher. Cette propriété indique le service ou la fonctionnalité dans qui une activité a été déclenchée. Pour obtenir la liste des types d’enregistrement que vous pouvez utiliser pour cette variable, consultez Type d’enregistrement journal d’audit. Vous pouvez utiliser le nom du type d’enregistrement ou la valeur ENUM.

Conseil : pour renvoyer les enregistrements d'audit pour tous les types d'enregistrements, utilisez la valeur $null (sans guillemets doubles).
$resultSize 5000 Spécifie le nombre de résultats renvoyés chaque fois que la commande cmdlet Search-UnifiedAuditLog est appelée par le script (appelé jeu de résultats). La valeur de 5 000 est la valeur maximale prise en charge par la commande cmdlet. Laissez cette valeur telle qu’elle est.
$intervalMinutes 60 Pour vous aider à dépasser la limite de 5 000 enregistrements retournés, cette variable prend la plage de données que vous avez spécifiée et la découpe en intervalles de temps plus petits. Chaque intervalle, et non la plage de dates entière, est soumis à la limite de sortie de l’enregistrement de 5 000 de la commande. La valeur par défaut de 5 000 enregistrements par intervalle de 60 minutes dans la plage de dates doit être suffisante pour la plupart des organisations. Toutefois, si le script renvoie une erreur qui indique maximum results limitation reached, diminuez l’intervalle de temps (par exemple, à 30 minutes, voire 15 minutes) et réexécutez le script.

La plupart des variables répertoriées dans le tableau précédent correspondent aux paramètres de la commande cmdlet Search-UnifiedAuditLog. Pour plus d'informations sur ces paramètres, voir Search-UnifiedAuditLog.

  1. Sur votre ordinateur local, ouvrez Windows PowerShell et allez dans le dossier dans lequel vous avez enregistré le script modifié.

  2. Dans Exchange Online PowerShell, exécutez le script suivant par exemple :

    .\SearchAuditLog.ps1

Le script affiche les messages de progression pendant son exécution. Une fois l’exécution du script terminée, il crée le fichier journal et le fichier CSV qui contient les enregistrements d’audit et les enregistre dans les dossiers définis par les variables $logFile et $outputFile.

Importante

Il existe une limite de 50 000 pour le nombre maximal d'enregistrements d'audit renvoyés chaque fois que vous exécutez l'applet de commande dans le script. Si vous exécutez ce script et qu’il renvoie 50 000 résultats, il est probable que les enregistrements d’audit pour les activités qui se sont produites dans la plage de dates n’ont pas été inclus. Dans ce cas, nous vous recommandons de diviser la plage de dates en plus petites durées, puis de réexécuter le script pour chaque plage de dates. Par exemple, si une plage de dates de 90 jours renvoie 50 000 résultats, vous pouvez réexécuter le script deux fois, une fois pour les 45 premiers jours de la plage de dates, puis de nouveau pour les 45 prochains jours.

Étape 3 : formater et afficher les enregistrements d’audit

Après avoir exécuté le script et exporté les enregistrements d’audit dans un fichier CSV, vous souhaitez peut-être mettre en forme le fichier CSV afin de faciliter l’examen et l’analyse des enregistrements d’audit. Une des façons de cela consiste à transformer JavaScript Object Notation Power Query dans Excel pour fractionner chaque propriété de l’objet JSON dans la colonne AuditData dans sa propre colonne. Pour obtenir des instructions détaillées, consultez « Étape 2 : mise en forme du journal d’audit exporté à l’aide de l’Éditeur Power Query » dans Exporter, configurer et afficher des enregistrements du journal d’audit.