Verwenden eines PowerShell-Skripts zum Durchsuchen des Überwachungsprotokolls

  • Artikel

Sicherheit, Compliance und Überwachung haben heutzutage für IT-Administratoren oberste Priorität. Microsoft 365 umfasst mehrere integrierte Funktionen, die Organisationen in den Bereichen Sicherheit, Compliance und Überwachung unterstützen. Insbesondere die vereinheitlichte Überwachungsprotokollierung kann Ihnen dabei helfen, Sicherheitsvorfälle und Complianceprobleme zu untersuchen. Sie können Überwachungsprotokolle mithilfe der folgenden Methoden abrufen:

Wenn Sie Überwachungsprotokolle regelmäßig abrufen müssen, sollten Sie eine Lösung in Betracht ziehen, die die Office 365-Verwaltungsaktivitäts-API verwendet, da sie großen Organisationen die Skalierbarkeit und Leistung bieten kann, um Millionen von Überwachungsdatensätzen kontinuierlich abzurufen. Die Verwendung des Suchtools für Überwachungsprotokolle im Microsoft Purview-Portal oder im Complianceportal ist eine gute Möglichkeit, Überwachungsdatensätze für bestimmte Vorgänge, die in kürzerer Zeit auftreten, schnell zu finden. Bei Verwendung längerer Zeiträume im Überwachungsprotokoll-Suchtool werden insbesondere bei großen Organisationen u. U. zu viele Datensätze für eine einfache Verwaltung oder den Export zurückgegeben.

In Situationen, in denen Sie Überwachungsdaten für eine bestimmte Untersuchung oder einen Vorfall manuell abrufen müssen, insbesondere für längere Datumsbereiche in größeren Organisationen, ist die Verwendung des Cmdlets Search-UnifiedAuditLog möglicherweise die beste Option. Dieser Artikel umfasst ein PowerShell-Skript, welches das Cmdlet nutzt, das bis zu 50.000 Überwachungsdatensätze abrufen kann (jedesmal, wenn Sie das Cmdlet ausführen), und diese Datensätze dann in eine CSV-Datei CSV-Datei exportiert, welche Sie zur Vereinfachung Ihrer Überprüfung mit Power Query in Excel formatieren können. Durch die Verwendung des in diesem Artikel beschriebenen Skripts wird auch die Wahrscheinlichkeit minimiert, dass es bei umfangreichen Überwachungsprotokollsuchen zu einer Zeitüberschreitung im Dienst kommt.

Tipp

Wenn Sie kein E5-Kunde sind, verwenden Sie die 90-tägige Testversion von Microsoft Purview-Lösungen, um zu erfahren, wie zusätzliche Purview-Funktionen Ihre Organisation bei der Verwaltung von Datensicherheits- und Complianceanforderungen unterstützen können. Starten Sie jetzt im Testhub für Microsoft Purview-Complianceportal. Erfahren Sie mehr über Anmelde- und Testbedingungen.

Vor dem Ausführen des Skripts

  • Damit das Skript zum Zurückgeben von Überwachungsdatensätzen verwendet werden kann, muss die Überwachungsprotokollierung für Ihre Organisation aktiviert sein. Die Überwachungsprotokollierung ist für Microsoft 365- und Office 365 Enterprise-Organisationen standardmäßig aktiviert. Um zu überprüfen, ob die Überwachungsprotokollsuche für Ihre Organisation aktiviert ist, können Sie den folgenden Befehl in der Exchange Online-PowerShell ausführen:

    Get-AdminAuditLogConfig | FL UnifiedAuditLogIngestionEnabled

    Der Wert True für die Eigenschaft UnifiedAuditLogIngestionEnabled gibt an, dass die Überwachungsprotokollsuche aktiviert ist.

  • Ihnen muss die Rolle Nur anzeigende Überwachungsprotokolle oder Überwachungsprotokolle in Exchange Online zugewiesen sein, um das Skript erfolgreich ausführen zu können. Standardmäßig werden diese Rollen den Rollengruppen Complianceverwaltung und Organisationsverwaltung auf der Seite Berechtigungen im Exchange Admin Center zugewiesen.

  • Das Ausführen des Skripts kann länger dauern. Wie lange es dauert, hängt vom Datumsbereich und von der Größe des Intervalls ab, für die das Skript Überwachungsdatensätze abrufen soll. Größere Datumsbereiche und kleinere Intervalle führen zu einer langen Laufzeit. Weitere Informationen zum Datumsbereich und zu den Intervallen finden Sie in der Tabelle in Schritt 2.

  • Das in diesem Artikel bereitgestellte Beispielskript wird unter keinem standardmäßigen Supportprogramm oder Dienst von Microsoft unterstützt. Das Beispielskript wird wie besehen ohne jegliche Gewährleistung zur Verfügung gestellt. Microsoft schließt ferner alle konkludenten Gewährleistungen, einschließlich, aber nicht beschränkt auf konkludente Gewährleistungen der Marktgängigkeit oder Eignung für einen bestimmten Zweck aus. Das gesamte Risiko, das mit der Verwendung oder Leistung des Beispielskripts und der Dokumentation einhergeht, liegt bei Ihnen. In keinem Fall sind Microsoft, seine Autoren oder an der Erstellung, Produktion oder Übermittlung des Skripts beteiligte Personen für Schäden jeglicher Art (einschließlich und ohne Einschränkung Schäden durch Verlust entgangener Gewinne, Geschäftsunterbrechungen, Verlust von Geschäftsinformationen oder andere geldliche Verluste) haftbar, die aus der Nutzung bzw. Unfähigkeit zur Nutzung des Beispielskripts oder der Dokumentation entstehen, auch wenn Microsoft auf die Möglichkeit solcher Schäden hingewiesen wurde.

Schritt 1: Herstellen einer Verbindung mit Exchange Online PowerShell

Im ersten Schritt muss eine Verbindung mit Exchange Online PowerShell hergestellt werden. Sie können die Verbindung mithilfe der modernen Authentifizierung oder mittels mehrstufiger Authentifizierung herstellen. Schrittweise Anleitungen finden Sie unter Herstellen einer Verbindung mit Exchange Online PowerShell.

Schritt 2: Anpassen und Ausführen des Skripts zum Abrufen von Überwachungsdatensätzen

Nachdem eine Verbindung mit Exchange Online PowerShell hergestellt wurde, besteht der nächste Schritt im Erstellen, Anpassen und Ausführen des Skripts, um die Überwachungsdaten abzurufen. Die ersten sieben Zeilen im Skript für die Überwachungsprotokollsuche enthalten die folgenden Variablen, die Sie zum Konfigurieren der Suche ändern können. Eine Beschreibung dieser Variablen finden Sie in der Tabelle in Schritt 2.

  1. Speichern Sie den nachstehenden Text in einer Windows PowerShell-Skriptdatei mit dem Dateinamensuffix ".ps1". Beispiel: 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. Ändern Sie die in der folgenden Tabelle aufgeführten Variablen, um die Suchkriterien zu konfigurieren. Das Skript enthält Beispielwerte für diese Variablen, die Sie aber (sofern nicht anders angegeben) Ihren Anforderungen entsprechend anpassen sollten.


Variable Beispielwert Beschreibung
$logFile "d:\temp\AuditSearchLog.txt" Gibt den Namen und Speicherort für die Protokolldatei an, die Informationen über den Fortschritt der vom Skript ausgeführten Überwachungsprotokollsuche enthält. Das Skript schreibt UTC-Zeitstempel in die Protokolldatei.
$outputFile "d:\temp\AuditRecords.csv" Gibt den Namen und Speicherort der CSV-Datei an, die die vom Skript zurückgegebenen Überwachungsdatensätze enthält.
[DateTime]$start und [DateTime]$end [DateTime]::UtcNow.AddDays(-1)
[DateTime]::UtcNow		 Gibt den Datumsbereich für die Überwachungsprotokollsuche an. Das Skript gibt Datensätze für Überwachungsaktivitäten zurück, die innerhalb des angegebenen Datumsbereichs aufgetreten sind. Wenn beispielsweise Aktivitäten zurückgeben werden sollen, die im Januar 2021 ausgeführt wurden, können Sie als Startdatum "2021-01-01" und als Enddatum "2021-01-31" angeben (achten Sie darauf, die Werte in doppelte Anführungszeichen zu setzen). Der Beispielwert im Skript gibt Datensätze für Aktivitäten zurück, die innerhalb der letzten 24 Stunden ausgeführt wurden. Wenn der Wert keinen Zeitstempel enthält, wird der standardmäßige Zeitstempel "00:00 Uhr" (Mitternacht) für das angegebene Datum verwendet.
$record "AzureActiveDirectory" Gibt den Datensatztyp der Überwachungsaktivitäten (auch als Überwachungsvorgänge bezeichnet) an, nach dem gesucht werden soll. Diese Eigenschaft gibt den Dienst oder das Feature an, in dem eine Aktivität ausgelöst wurde. Eine Liste der Datensatztypen, die Sie für diese Variable verwenden können, finden Sie unter Überwachungsprotokolle: Datensatztypen. Sie können den Datensatztypnamen oder den ENUM-Wert verwenden.

Tipp: Verwenden Sie den Wert $null (ohne doppelte Anführungszeichen), wenn Überwachungsdatensätze für alle Datensatztypen zurückgegeben werden sollen.
$resultSize 5000 Gibt die Anzahl von Ergebnissen an, die jedes Mal zurückgegeben werden, wenn das Cmdlet Search-UnifiedAuditLog durch das Skript aufgerufen wird (auch als Resultset bezeichnet). Der Wert 5.000 ist die vom Cmdlet unterstützte Höchstanzahl. Lassen Sie diesen Wert unverändert.
$intervalMinutes 60 Um das Limit von 5.000 zurückgegebenen Datensätzen zu überwinden, nimmt diese Variable den von Ihnen angegebenen Datenbereich in kleinere Zeitintervalle auf. Das Ausgabelimit des Befehls von 5 000 Datensätzen gilt dann für jedes Intervall, nicht für den gesamten Datumsbereich. Der Standardwert von 5.000 Datensätzen pro 60-Minuten-Intervall innerhalb des Datumsbereichs sollte für die meisten Organisationen ausreichen. Sollte das Skript aber eine Fehlermeldung zurückgeben, die besagt „maximum results limitation reached“, verringern Sie das Zeitintervall (z. B.auf 30 Minuten oder sogar 15 Minuten), und führen Sie das Skript erneut aus.

Die meisten der in der vorherigen Tabelle aufgeführten Variablen entsprechen Parametern für das Cmdlet Search-UnifiedAuditLog. Weitere Informationen zu diesen Parametern finden Sie unter Search-UnifiedAuditLog.

  1. Öffnen Sie auf dem lokalen Computer Windows PowerShell, und wechseln Sie zu dem Ordner, in dem Sie das geänderte Skript gespeichert haben.

  2. Führen Sie das Skript in Exchange Online PowerShell aus. Zum Beispiel:

    .\SearchAuditLog.ps1

Während der Ausführung des Skripts werden Statusmeldungen angezeigt. Nach der Ausführung des Skripts werden die Protokolldatei und die CSV-Datei erstellt, die die Überwachungsdatensätze enthält, und diese in den Ordnern gespeichert, die durch die Variablen $logFile und $outputFile definiert sind.

Wichtig

Bei jeder Ausführung des Cmdlets gilt ein Limit von maximal 50.000 zurückgegebenen Überwachungsdatensätzen. Wenn Sie dieses Skript ausführen und 50.000 Ergebnisse zurückgegeben werden, wurden wahrscheinlich keine Überwachungsdatensätze für Aktivitäten einbezogen, die innerhalb dieses Datumsbereichs erfolgt sind. In diesem Fall empfehlen wir, den Datumsbereich in kleinere Abschnitte zu unterteilen und dann das Skript für jeden Datumsbereich erneut auszuführen. Wenn beispielsweise bei einem Datumsbereich von 90 Tagen 50.000 Ergebnisse zurückgegeben werden, können Sie das Skript zweimal ausführen, einmal für die ersten 45 Tage und dann erneut für die anderen 45 Tage des Datumsbereichs.

Schritt 3: Formatieren und Anzeigen der Überwachungsdatensätze

Nachdem Sie das Skript ausgeführt und die Überwachungsdatensätze in eine CSV-Datei exportiert haben, können Sie die CSV-Datei formatieren, um die Überprüfung und Analyse der Überwachungsdatensätze zu vereinfachen. Eine Methode hierfür besteht darin, mithilfe des Power Query-Features zum Transformieren in Excel jede Eigenschaft im JSON-Objekt in der Spalte AuditData in eine eigene Spalte aufzuteilen. Schrittweise Anleitungen finden Sie unter "Schritt 2: Formatieren von exportierten Überwachungsprotokollen mithilfe des Power Query-Editors" in Exportieren, Konfigurieren und Anzeigen von Überwachungsprotokoll-Datensätzen.