Bonnes pratiques à l’aide de l’outil d’applet de commande Search-UnifiedAuditLog

  • Article

Le journal d’audit est un outil qui enregistre les événements d’une gamme de charges de travail. L’applet de commande Search-UnifiedAuditLog peut être utilisée pour rechercher et récupérer des données à partir du journal d’audit. Il est important de comprendre comment utiliser efficacement cette applet de commande, en particulier lorsqu’il s’agit d’interpréter les informations de la propriété AuditData, car différentes charges de travail insèrent différents types d’informations dans cette propriété.

Par défaut, l’applet de commande Search-UnifiedAuditLog renvoie 100 enregistrements d’audit pour toute demande de recherche, sauf si vous spécifiez un nombre différent d’enregistrements à récupérer à l’aide du paramètre ResultSize (jusqu’à un maximum de 5 000 enregistrements).

Une seule recherche peut traiter un maximum de 50 000 enregistrements d’audit à l’aide de la récupération de page. Étant donné que le journal d’audit peut contenir une grande quantité de données, il est important d’être aussi spécifique que possible lors de l’utilisation des paramètres de recherche pour éviter de retourner trop d’enregistrements.

Pour utiliser l’applet de commande Search-UnifiedAuditLog, votre compte doit avoir le rôle Journaux d’audit exchange View-Only ou Journaux d’audit. Ces rôles font partie des groupes de rôles Gestion de la conformité et Gestion de l’organisation, et peuvent être attribués à d’autres groupes de rôles en fonction des besoins.

RecordTypes

RecordType est la charge de travail qui a généré l’enregistrement. Voici quelques exemples de différents types d’événements trouvés à l’aide de l’applet de commande Search-UnifiedAuditLog :

  1. Ajouter un membre à un groupe dans Microsoft Entra ID (AzureActiveDIrectory)
  2. Mettre à jour les propriétés de boîte aux lettres dans Exchange (ExchangeAdmin)
  3. Supprimer un fichier dans SharePoint (SharePointFileOperation)
  4. Connecter un utilisateur à Microsoft Teams (MicrosoftTeams)
  5. Pulsation AIP (AipHeartbeat)

Ces événements peuvent être recherchés et suivis à l’aide de l’applet de commande Search-UnifiedAuditLog, ce qui vous permet de filtrer et d’afficher les détails des événements enregistrés dans le journal d’audit unifié.

Auditer la structure des données

Search-UnifiedAuditLog -RecordType AipDiscover -StartDate (Get-Date).AddDays(-100) -EndDate (Get-Date)

Les enregistrements d’audit se composent de deux parties : Propriétés générales Propriété AuditData

Propriétés générales

Propriétés générales qui sont remplies de la même façon par toutes les charges de travail, et la propriété AuditData qui contient des informations spécifiques à la charge de travail. Les propriétés générales incluent le type d’enregistrement, la date de création, l’opération et l’identificateur d’utilisateur.

RunspaceId   : 136b901e-a6bc-4f24-bb58-5c435090df91
RecordType   : AipDiscover
CreationDate : 2022-09-15 5:49:22 PM
UserIds      : AdeleV@M365x23987777.OnMicrosoft.com
Operations   : Access
ResultIndex  : 8
ResultCount  : 8
Identity     : 20728aaf-1964-1a4a-bd72-784fa3c12132
IsValid      : True
ObjectState  : Unchanged

Propriété AuditData

Recherchez les informations les plus importantes sur un événement à l’aide de la propriété AuditData. Les charges de travail utilisent des schémas pour décrire les propriétés qu’elles insèrent dans les enregistrements d’audit, et ces schémas sont utilisés pour aider à interpréter la charge utile dans les événements d’audit. Il peut être nécessaire d’effectuer des essais et des erreurs pour comprendre pleinement les informations contenues dans un enregistrement d’audit. Un guide des propriétés détaillées dans les enregistrements du journal d’audit peut être utile dans ce processus. Les détails de l’action effectuée par un utilisateur étant stockés au format JSON (JavaScript Object Notation), un traitement supplémentaire est nécessaire pour mettre en forme les données afin d’extraire les informations.

AuditData:
{
  "SensitivityLabelEventData":{
    "SensitivityLabelId":"8581574a-c314-42e3-bfdc-a63cf96ed86e"
  },
  "SensitiveInfoTypeData":[
    
  ],
  "ProtectionEventData":{
    "IsProtected":false
  },
  "Common":{
    "ApplicationId":"c00e9d32-3c8d-4a7d-832b-029040e7db99",
    "ApplicationName":"Microsoft Azure Information Protection Word Add-In",
    "ProcessName":"WINWORD",
    "Platform":1,
    "DeviceName":"AdeleVanceWindo",
    "Location":"On-premises file shares",
    "ProductVersion":"2.13.49.0"
  },
  "DataState":"Use",
  "ObjectId":"C:\\452Documentcreated.docx",
  "UserId":"AdeleV@M365x23987777.OnMicrosoft.com",
  "ClientIP":"20.237.230.167",
  "Id":"20728aaf-1964-1a4a-bd72-784fa3c12132",
  "RecordType":93,
  "CreationTime":"2022-09-15T17:49:22",
  "Operation":"Access",
  "OrganizationId":"4b080626-0acc-4940-8af8-bfc836ff1a59",
  "UserType":0,
  "UserKey":"AdeleV@M365x23987777.OnMicrosoft.com",
  "Workload":"Aip",
  "Version":1,
  "Scope":1
}

Le tableau suivant répertorie les détails de la propriété AuditData.

Paramètre Description
RecordType Type de charge de travail qui a généré l’enregistrement, par exemple Microsoft Entra ID, Microsoft Teams, Exchange Administration ou Opération de fichier SharePoint.
CreationTime Date et heure au format UTC auxquelles l’activité a été effectuée.
Opération Opération journalisée lorsqu’une personne accède à un élément, tel que FileViewed dans le cas de SharePoint Online.
OrganizationId Identificateur de locataire unique sous la forme d’un GUID.
UserKey Identité utilisée pour accéder à l’élément, généralement obtenue par le biais de l’appartenance à un groupe.
Charge de travail Nom de l’application qui a enregistré l’événement, par exemple SharePoint Online, Exchange Online, OneDrive Entreprise ou Microsoft Entra ID.
ClientIP Adresse IP de la station de travail cliente d’où provient l’action.
ObjectID Chemin d’accès complet à l’objet auquel a été accédé.
UserID Identificateur de compte Microsoft Entra pour le compte à l’origine de l’action.
UserAgent Client utilisé pour appeler l’action.
SourceFileName Nom du fichier impliqué dans l’action.
UserType Type d’utilisateur qui a effectué l’action, avec les valeurs « 0 » (utilisateur normal), « 1 » (administrateur) ou « 2 » (administrateur de centre de données Microsoft ou compte système).
EventSource Utilisé uniquement par SharePoint Online, indiquant si la source était SharePoint ou ObjectMode.
ResultIndex et ResultCount Les propriétés ResultIndex et ResultCount peuvent être utiles lors de l’utilisation de jeux d’enregistrements volumineux. ResultIndex indique le numéro d’enregistrement dans le jeu retourné, tandis que ResultCount affiche le nombre total d’enregistrements retournés. Par exemple, si ResultIndex est 1 et ResultCount est 125, cela signifie que l’enregistrement affiché est le premier des 125 retournés dans le jeu.
Si la recherche rencontre un délai d’expiration interne, ResultIndex est défini sur -1. À mesure que les administrateurs acquièrent de l’expérience avec le journal d’audit et les applets de commande PowerShell, ils découvrent que le journal d’audit est une source d’informations précieuse pour comprendre qui a interagi avec un document ou créé de nouveaux documents au cours d’une certaine période. Il peut s’avérer nécessaire d’effectuer des essais et des erreurs pour utiliser pleinement les informations fournies dans les enregistrements d’audit.

Rechercher les événements d’ensemble corrects

Pour trouver les événements appropriés lors de la recherche dans le journal d’audit, il est important de savoir ce que vous recherchez et d’utiliser les filtres et paramètres appropriés. Cela peut être difficile, car le journal d’audit peut contenir un grand nombre d’événements, et la recherche d’actions spécifiques peut être semblable à la recherche d’un petit objet dans une liste de données volumineuse et désordonnée.

Une façon d’aborder ce problème consiste à prendre des mesures pour générer un événement d’audit pour l’action qui vous intéresse, à attendre environ 60 minutes pour permettre l’ingestion de l’événement dans le journal d’audit, puis à rechercher des événements au cours de cette période.

Cela vous donnera un ensemble plus petit d’événements à utiliser, que vous pouvez ensuite analyser et utiliser pour effectuer d’autres recherches. Il est également judicieux d’utiliser les valeurs Operations / RecordTypes journalisées pour les événements afin de vous aider à affiner vos recherches et à trouver les événements spécifiques que vous recherchez.

Voici un exemple de filtrage de données en recherchant des opérations très spécifiques et dans une plage de dates donnée. Affichez les types d’enregistrements pour afficher les types d’enregistrements qui peuvent être recherchés.

Le script suivant recherche une opération spécifique.

$Operations = ("SensitivityLabelUpdated", "SensitivityLabelApplied", "FileSensitivityLabelApplied")
$StartDate = (Get-Date).AddDays(-90)
$EndDate = (Get-Date).AddDays(1)
[Array]$Records = Search-UnifiedAuditLog -StartDate $StartDate -EndDate $EndDate -Formatted -ResultSize 5000 -Operations $Operations

Le script suivant recherche un type d’enregistrement spécifique. Cet exemple utilise pour AipDiscover.

Search-UnifiedAuditLog -StartDate (Get-Date).AddDays(-100) -EndDate (Get-Date) -RecordType AipDiscover -Operations Access -ResultSize 5 -Formatted | Format-Table UserIds, CreationDate, Operations

Le script suivant stocke le résultat dans un tableau et recherche une valeur spécifique. Cet exemple utilise CreationDate.

[array]$Records  = Search-UnifiedAuditLog -RecordType AipDiscover -StartDate (Get-Date).AddDays(-100) -EndDate (Get-Date)
$Records | Where-Object {$_.CreationDate -eq "2022-09-15 5:49:22 PM"}

Gérer de grandes quantités de données d’audit

Si vous avez besoin de récupérer un grand nombre d’enregistrements d’audit à partir d’un grand locataire, ou si vous devez rechercher plusieurs opérations sur une période prolongée, il est probable qu’une seule recherche retourne plus de 5 000 enregistrements.

Pour gérer de grands volumes de données à partir de l’applet de commande Search-UnifiedAuditLog, vous pouvez utiliser les paramètres ReturnLargeSet et ReturnNextPreviewPage. Ces paramètres vous permettent d’effectuer des recherches qui retournent de grands ensembles de résultats, puis de récupérer la page de résultats suivante dans les recherches suivantes.

  1. Utilisez le paramètre SessionId pour identifier une session de recherche et spécifier le nombre de pages que vous souhaitez récupérer. Cela permet à l’applet de commande d’extraire plusieurs pages de données et de vous les retourner.
  2. Le paramètre SessionId est également utilisé lorsque vous souhaitez rechercher une grande quantité de données d’audit à l’aide de l’applet de commande Search-UnifiedAuditLog. L’applet de commande retourne un maximum de 5 000 enregistrements par page. Par conséquent, si vous souhaitez en rechercher plus, vous devez utiliser le paramètre SessionId pour identifier une session de recherche et spécifier le nombre de pages que vous souhaitez récupérer. L’applet de commande utilise ensuite l’identificateur de session pour extraire les pages de données supplémentaires et vous les renvoyer.
  3. Si vous avez besoin de rechercher plus de 50 000 enregistrements, répartissez le travail entre plusieurs recherches et utilisez des critères différents pour chaque recherche.
  4. Stockez les résultats des recherches dans un référentiel externe, tel qu’Azure Log Analytics, Azure Data Explorer, pour faciliter l’accès et l’analyse.
  5. Examinez et mettez à jour régulièrement vos critères de recherche et auditez les processus de gestion des données pour vous assurer que vous capturez les données appropriées et que vous les gérez efficacement. Cela vous aidera à rester informé des éventuels problèmes de sécurité et à améliorer la sécurité globale de votre organization.

Étapes pour récupérer de grandes quantités de données

Pour extraire une grande quantité de données d’audit, procédez comme suit :

  1. Générez un identificateur de session.
  2. Utilisez une boucle pour récupérer des données dans plusieurs pages.
  3. Exécutez à plusieurs reprises la commande Search-UnifiedAuditLog pour extraire toutes les données disponibles.
  4. Enregistrez les données de chaque exécution de Search-UnifiedAuditLog.
  5. Une fois que toutes les pages ont été extraites, triez les données par date et exportez-les dans un fichier CSV.

Exemples

Search-UnifiedAuditLog a deux paramètres pour prendre en charge la récupération de jeux de données volumineux : SessionID et SessionCommand. SessionID et SessionCommand peuvent être combinés pour traiter des jeux de données volumineux. Le paramètre SessionId contient une valeur de chaîne pour identifier une session de recherche. Vous pouvez utiliser n’importe quelle valeur de votre choix, d’un nombre simple à un GUID généré avec l’applet de commande New-Guid. La présence d’un identificateur de session indique Search-UnifiedAuditLog qu’il peut être nécessaire d’extraire plusieurs pages de données.

eg.
$SessionId = "5b5a5a5a-5b5b-5c5c-5d5d-5e5e5e5e5e5e"
$SessionId = "UnifiedAuditLogSearch 01/02/17"

SessionCommand indique Search-UnifiedAuditLog comment gérer de grandes quantités de données d’audit. Les données retournées peuvent contenir des enregistrements en double. Ce paramètre peut être défini sur :

  • ReturnLargeSet : les enregistrements d’audit retournés ne sont pas triés. Vous pouvez extraire jusqu’à 50 000 enregistrements d’audit à l’aide de cette méthode, mais n’oubliez pas de trier les données une fois qu’elles sont toutes extraites.
  • ReturnNextPreviewPage : Search-UnifiedAuditLog retourne les enregistrements d’audit triés par date. Toutefois, vous ne pouvez extraire que 5 000 enregistrements au maximum à l’aide de cette méthode. Le nombre maximal d’enregistrements renvoyés par le biais de la pagination ou du paramètre ResultSize est de 5 000.

Remarque

Utilisez toujours la même valeur SessionCommand pour une valeur SessionId donnée. Ne basculez pas entre ReturnLargeSet et ReturnNextPreviewPage pour le même ID de session. Sinon, la sortie est limitée à 10 000 résultats.

Exemple de script SessionId

Dans l’exemple suivant, le script importe d’abord le module Exchange Online Management et crée une connexion à distance à Exchange Online. Il définit ensuite les dates de début et de fin de la recherche et utilise l’applet de commande Search-UnifiedAuditLog pour rechercher dans le journal d’audit unifié des entrées dans la plage de dates spécifiée.

Le script utilise ensuite une boucle foreach pour analyser le tableau d’enregistrements retourné par l’applet de commande et traite chaque enregistrement en fonction des besoins. Dans ce cas, il imprime le nom de l’opération et l’identité de l’utilisateur pour chaque enregistrement.

# Import the Exchange Online Management module
Import-Module ExchangeOnlineManagement
# Create a remote connection to Exchange Online
$UserCredential = Get-Credential
Connect-IPPSSession
# Search the Unified Audit Log for entries with the specified SessionID
$SessionId = "5b5a5a5a-5b5b-5c5c-5d5d-5e5e5e5e5e5e"
$StartDate = (Get-Date).AddDays(-90)
$EndDate = (Get-Date).AddDays(1)
[Array]$Records = Search-UnifiedAuditLog -StartDate $StartDate -EndDate $EndDate -SessionId $SessionId

# Scan through the array of records
foreach ($Record in $Records)
{
    # Process each record as needed
    # For example, you could print the operation name and user identity
    Write-Host "Operation: $($Record.RecordType)"
    Write-Host "User Identity: $($Record.Operations)"
    Write-Host "User Identity: $($Record.AuditData)"
}

Exemple de script ReturnLargeSet

Dans l’exemple suivant, l’applet de commande Search-UnifiedAuditLog est utilisée pour rechercher dans le journal d’audit des entrées entre les heures de début et de fin spécifiées. Le paramètre ReturnLargeSet est défini en spécifiant les paramètres SessionId et SessionCommand dans l’objet $parameters. Les résultats de la recherche sont ensuite bouclé et chaque entrée est sortie dans la console.

ReturnLargeSet : renvoie des données non triées. En utilisant la pagination, vous pouvez accéder à un maximum de 50 000 résultats. Il s’agit de la valeur recommandée si un résultat ordonné n’est pas requis et a été optimisé pour la latence de recherche.

# Set the start and end time for the audit log search
$startTime = "01/01/2022 00:00:00"
$endTime = "12/31/2022 23:59:59"

# Set the parameters for the search
$parameters = @{
    StartDate = $startTime
    EndDate = $endTime
    SessionId = "UnifiedAuditLogSearch 01/02/17"
    SessionCommand = "ReturnLargeSet"
}

# Perform the search and store the results in a variable
$results = Search-UnifiedAuditLog @parameters

# Loop through the results and output each entry
for ($i = 0; $i -lt $results.Count; $i++) {
    $entry = $results[$i]
    Write-Output $entry
}

Exemple de script ReturnNextPreviewPage

Le script suivant effectue une recherche à l’aide de l’applet de commande Search-UnifiedAuditLog et du paramètre ReturnNextPreviewPage. La recherche est effectuée à l’aide des heures de début et de fin spécifiées. Les résultats de la recherche sont ensuite générés dans la console.

# Set the start and end time for the audit log search
$startTime = "01/01/2022 00:00:00"
$endTime = "12/31/2022 23:59:59"

 
# Set the parameters for search
$parameters = @{
    SessionId = "UnifiedAuditLogSearch 01/02/17"
    SessionCommand = "ReturnNextPreviewPage"
    StartDate = $startTime
    EndDate = $endTime
}

# Retrieve results
$resultpage = Search-UnifiedAuditLog @parameters