Usare uno script PowerShell per la ricerca nel log di audit

Articolo
02/13/2024

La sicurezza, la conformità e il controllo sono diventati una priorità assoluta per gli amministratori IT al giorno d’oggi. Microsoft 365 offre diverse funzionalità incorporate per aiutare le organizzazioni a gestire la sicurezza, la conformità e il controllo. In particolare, la registrazione di controllo unificata consente di esaminare gli incidenti di sicurezza e i problemi di conformità. È possibile recuperare i log di audit usando i metodi seguenti:

L’API Office 365 Management Activity
Strumento di ricerca del log di controllo nel portale di Microsoft Purview o nella Portale di conformità di Microsoft Purview.
Il cmdlet Search-UnifiedAuditLog in Exchange Online PowerShell

Se è necessario recuperare regolarmente i log di controllo, è consigliabile prendere in considerazione una soluzione che usa l'API attività di gestione Office 365 perché può offrire alle organizzazioni di grandi dimensioni scalabilità e prestazioni per recuperare milioni di record di controllo in modo continuativo. L'uso dello strumento di ricerca dei log di controllo nel portale di Microsoft Purview o nel portale di conformità è un buon modo per trovare rapidamente i record di controllo per operazioni specifiche che si verificano in un intervallo di tempo più breve. L'uso di intervalli di tempo più lunghi nello strumento di ricerca nel log di audit, in particolare per le organizzazioni di grandi dimensioni, potrebbe restituire una quantità di record troppo elevata per essere gestita o esportata facilmente.

In situazioni in cui è necessario recuperare manualmente i dati di controllo per un'indagine o un incidente specifico, in particolare per intervalli di date più lunghi nelle organizzazioni di grandi dimensioni, l'uso del cmdlet Search-UnifiedAuditLog può essere l'opzione migliore. Questo articolo include uno script PowerShell che usa il cmdlet per recuperare fino a 50.000 record di controllo (ogni volta che si esegue il cmdlet) e quindi esportarli in un file CSV che può essere formattato con Power Query in Excel per assistere nella revisione. L'uso dello script in questo articolo consente anche di ridurre al minimo la possibilità che le ricerche nel log di audit di grandi dimensioni raggiungano il timeout nel servizio.

Consiglio

Se non si è un cliente E5, usare la versione di valutazione delle soluzioni Microsoft Purview di 90 giorni per esplorare in che modo funzionalità aggiuntive di Purview possono aiutare l'organizzazione a gestire le esigenze di sicurezza e conformità dei dati. Iniziare ora dall'hub delle versioni di valutazione Portale di conformità di Microsoft Purview. Informazioni dettagliate sull'iscrizione e le condizioni di valutazione.

Prima di eseguire lo script

La registrazione di controllo deve essere abilitata per l'organizzazione per poter usare correttamente lo script per restituire record di controllo. La registrazione di controllo è attivata per impostazione predefinita per le organizzazioni di Microsoft 365 e Office 365 Enterprise. Per verificare che la ricerca nel registro di controllo sia attivata per l’organizzazione, è possibile eseguire il comando seguente in Exchange Online PowerShell:
```
Get-AdminAuditLogConfig | FL UnifiedAuditLogIngestionEnabled
```
Il valore True per la proprietà UnifiedAuditLogIngestionEnabled indica che la ricerca nel log di audit è attivata.
Per eseguire correttamente lo script, è necessario assegnare il ruolo Log di controllo di sola visualizzazione o Log di controllo in Exchange Online. Per impostazione predefinita, questi ruoli sono assegnati ai gruppi di ruoli Gestione conformità e Gestione organizzazione nella pagina Autorizzazioni nell'interfaccia di amministrazione di Exchange.
Il completamento dello script può richiedere molto tempo. Il tempo necessario per l'esecuzione dipende dall'intervallo di date e dalle dimensioni dell'intervallo per cui si configura lo script per il recupero dei record di controllo. Intervalli di date più grandi e intervalli più piccoli comportano un tempo di esecuzione lungo. Per altre informazioni sull'intervallo di date e sugli intervalli, vedere la tabella del passaggio 2.
Lo script di esempio fornito in questo articolo non è supportato da alcun programma o servizio standard di supporto Microsoft. Lo script di esempio è fornito così come è senza alcun tipo di garanzia. Microsoft esclude inoltre qualsiasi garanzia implicita, tra cui, senza limitazioni, tutte le garanzie implicite di commerciabilità o idoneità per uno scopo specifico. L'utente assume tutti i rischi associati all'uso o alle prestazioni dello script di esempio e della documentazione. In nessun caso Microsoft, i suoi autori o chiunque altro coinvolto nella creazione, produzione o consegna dello script è da ritenersi responsabile per qualsiasi danno eventuale (inclusi, senza limitazione alcuna, danni riguardanti profitti aziendali, interruzione di attività, perdita di informazioni aziendali o altra perdita pecuniaria) derivanti dall'utilizzo o dall'incapacità di utilizzo dello script di esempio e della documentazione, anche nel caso in cui Microsoft sia stata avvisata della possibilità di tali danni.

Passaggio 1: Connettersi a Exchange Online PowerShell

La prima operazione da eseguire consiste nel connettersi a Exchange Online PowerShell. È possibile connettersi usando l'autenticazione moderna o l'autenticazione a più fattori (MFA). Per istruzioni dettagliate, vedere Connettersi a Exchange Online PowerShell.

Passaggio 2: Modificare ed eseguire lo script per recuperare i record di controllo

Dopo aver eseguito la connessione a Exchange Online PowerShell, il passaggio successivo consiste nel creare, modificare ed eseguire lo script per recuperare i dati di controllo. Le prime sette righe dello script di ricerca nel log di audit contengono le variabili seguenti che è possibile modificare per configurare la ricerca. Per la descrizione di queste variabili, vedere la tabella nel passaggio 2.

Salvare il testo seguente in uno script di Windows PowerShell con il suffisso del nome .ps1. Ad esempio: 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

Modificare le variabili elencate nella tabella seguente per configurare i criteri di ricerca. Lo script include valori di esempio per queste variabili, ma è consigliabile modificarli (se non diversamente specificato) in modo da soddisfare i requisiti specifici.

Variabile	Valore esemplificativo	Descrizione
`$logFile`	"d:\temp\AuditSearchLog.txt"	Specifica il nome e il percorso del file di log che contiene informazioni sullo stato della ricerca nel log di audit eseguita dallo script. Lo script scrive i timestamp UTC nel file di log.
`$outputFile`	"d:\temp\AuditRecords.csv"	Specifica il nome e il percorso del file CSV che contiene i record di controllo restituiti dallo script.
`[DateTime]$start` e `[DateTime]$end`	[DateTime]::UtcNow.AddDays(-1) [DateTime]::UtcNow	Specifica l'intervallo di date per la ricerca nel log di audit. Lo script restituisce i record per le attività di controllo che si sono verificate nell'intervallo di date specificato. Ad esempio, per restituire le attività eseguite nel mese di gennaio 2021, è possibile usare una data di inizio `"2021-01-01"` e una data di fine `"2021-01-31"` (racchiudere i valori tra virgolette doppie). Il valore di esempio nello script restituisce i record per le attività eseguite nelle 24 ore precedenti. Se non si include un timestamp nel valore, viene utilizzato il timestamp predefinito 00:00 (mezzanotte) nella data specificata.
`$record`	"AzureActiveDirectory"	Specifica il tipo di record delle attività di controllo (chiamate anche operazioni) da cercare. Questa proprietà indica il servizio o la caratteristica in cui è stata attivata un'attività. Per un elenco dei tipi di record che è possibile usare per questa variabile, vedere Tipo di record del log di audit. È possibile usare il nome del tipo di record o il valore di enumerazione. Suggerimento: per restituire i record di controllo per tutti i tipi di record, usare il valore `$null` (senza virgolette).
`$resultSize`	5000	Specifica il numero di risultati restituiti ogni volta che il cmdlet Search-UnifiedAuditLog viene chiamato dallo script (definito come set di risultati). 5000 è il valore massimo supportato dal cmdlet. Lasciare questo valore così come è.
`$intervalMinutes`	60	Per superare il limite di 5.000 record restituiti, questa variabile accetta l'intervallo di dati specificato e lo suddivide in intervalli di tempo più piccoli. Ora ogni intervallo, e non l'intervallo di date intero, è soggetto al limite di output di 5000 record del comando. Il valore predefinito di 5.000 record per intervallo di 60 minuti nell'intervallo di date deve essere sufficiente per la maggior parte delle organizzazioni. Tuttavia, se lo script restituisce un errore che indica `maximum results limitation reached`, ridurre l'intervallo di tempo, ad esempio a 30 o anche 15 minuti, ed eseguire di nuovo lo script.

La maggior parte delle variabili elencate nella tabella precedente corrispondono ai parametri per il cmdlet Search-UnifiedAuditLog. Per ulteriori informazioni su questi parametri, vedere Search-UnifiedAuditLog.

Aprire Windows PowerShell sul computer locale e passare alla cartella in cui è stato salvato lo script modificato.
Eseguire lo script in Exchange Online PowerShell, ad esempio:
```
.\SearchAuditLog.ps1
```

Lo script visualizza i messaggi di stato mentre è in esecuzione. Al termine dell'esecuzione, lo script crea il file di log e il file CSV che contiene i record di controllo e li salva nelle cartelle definite dalle variabili $logFile e $outputFile.

Importante

Esiste un limite di 50.000 per il numero massimo di record di controllo restituiti ogni volta che si esegue il cmdlet nello script. Se si esegue questo script e vengono restituiti 50.000 risultati, è probabile che i record di controllo per le attività che si sono verificate all’interno dell'intervallo di date non siano stati inclusi. In questo caso, è consigliabile dividere l'intervallo di date in durate più piccole e quindi eseguire di nuovo lo script per ogni intervallo di date. Ad esempio, se un intervallo di date di 90 giorni restituisce 50.000 risultati, è possibile eseguire di nuovo lo script in due volte, una per i primi 45 giorni nell'intervallo di date e la seconda per i 45 giorni seguenti.

Passaggio 3: Formattare e visualizzare i record di controllo

Dopo aver eseguito lo script ed esportato i record di controllo in un file CSV, è possibile formattare il file CSV per semplificare la revisione e l'analisi dei record di controllo. Un modo per farlo è la funzionalità di trasformazione JSON di Power Query in Excel per suddividere ogni proprietà della colonna AuditData nell'oggetto JSON in colonne specifiche. Per istruzioni dettagliate, vedere “Passaggio 2: Formattare il log di audit esportato usando l’editor di Power Query” in Esportare, configurare e visualizzare i record del log di audit.