From 84340bcfd6d9409e5b6658d9b0a1a02b695077f3 Mon Sep 17 00:00:00 2001 From: EmilienCourt Date: Wed, 30 Oct 2024 15:00:26 +0100 Subject: [PATCH] update documentation. Minor bugfixes on log file name. Added UnifiedAuditLogIngestionEnabled check. Bump version --- DFIR-O365RC/DFIR-O365RC.psd1 | 2 +- DFIR-O365RC/Get-O365.ps1 | 27 +++++++++++++-- README.md | 67 +++++++++--------------------------- 3 files changed, 41 insertions(+), 55 deletions(-) diff --git a/DFIR-O365RC/DFIR-O365RC.psd1 b/DFIR-O365RC/DFIR-O365RC.psd1 index 6d997c2..946c534 100755 --- a/DFIR-O365RC/DFIR-O365RC.psd1 +++ b/DFIR-O365RC/DFIR-O365RC.psd1 @@ -7,7 +7,7 @@ RootModule = '.\DFIR-O365RC.psm1' # Version number of this module. - ModuleVersion = '2.0.1' + ModuleVersion = '2.0.2' # Supported PSEditions CompatiblePSEditions = 'Core', 'Desktop' diff --git a/DFIR-O365RC/Get-O365.ps1 b/DFIR-O365RC/Get-O365.ps1 index 9036f16..b086dd4 100755 --- a/DFIR-O365RC/Get-O365.ps1 +++ b/DFIR-O365RC/Get-O365.ps1 @@ -104,7 +104,7 @@ "Lauching job with startDate {0:yyyy-MM-dd} and endDate {1:yyyy-MM-dd}" -f ($newStartDate, $newEndDate) | Write-Log -LogPath $logFile $dateToProcess = ($newStartDate.ToString("yyyy-MM-dd")) - $jobName = "UnifiedAuditLogPurview" + $dateToProcess + $jobName = "UnifiedAuditLogPurview_" + $dateToProcess Start-RSJob -Name $jobName -ScriptBlock $launchSearch -FunctionsToImport Get-UnifiedAuditLogPurview, Write-Log -ArgumentList $cert, $appId, $tenant, $newStartDate, $newEndDate, $requestType, $recordTypes, $operations, $freeTexts, $IPAddresses, $userIds, $currentPath @@ -213,7 +213,7 @@ function Get-O365 { $dateToProcess = ($newStartDate.ToString("yyyy-MM-dd")) $actualdate = $(get-date -f yyyy-MM-dd-hh-mm-ss) - $logFile = $currentPath + "\UnifiedAuditLog" + $dateToProcess + ".log" + $logFile = $currentPath + "\UnifiedAuditLog_" + $dateToProcess + ".log" $unifiedAuditFolder = $currentPath + "\O365_unified_audit_logs" if ((Test-Path $unifiedAuditFolder) -eq $false){ @@ -316,6 +316,27 @@ function Get-O365 { Get-RSJob | Remove-RSJob -Force + "Checking the status of Unified Audit Log"| Write-Log -LogPath $logFile + Connect-ExchangeOnlineApplication -logFile $logFile -certificate $cert -appId $appId -organization $tenant -commandNames "Get-AdminAuditLogConfig" + try { + $adminAuditLogConfig = Get-AdminAuditLogConfig + $isIngestionEnabled = $adminAuditLogConfig.UnifiedAuditLogIngestionEnabled + if (-not $isIngestionEnabled){ + Write-Error "Log ingestion is not enabled. This means that the unified audit log is disabled. This is not the default setting, please check https://learn.microsoft.com/en-us/purview/audit-log-enable-disable for more information. Exiting" + "Log ingestion is not enabled. This means that the unified audit log is disabled. This is not the default setting, please check https://learn.microsoft.com/en-us/purview/audit-log-enable-disable for more information. Exiting" | Write-Log -LogPath $logFile -LogLevel "Error" + $adminAuditLogConfig | Write-Log -LogPath $logFile -LogLevel "Error" + } + else { + $unifiedAuditLogFirstOptInDate = $adminAuditLogConfig.UnifiedAuditLogFirstOptInDate.ToString() + "Unified Audit Log First Opt In Date : $unifiedAuditLogFirstOptInDate" | Write-Log -LogPath $logFile -LogLevel "Info" + } + } + catch { + $errormessage = $_.Exception.Message + Write-Warning "Error while trying to execute Get-AdminAuditLogConfig : $errormessage. Continuing" + "Error while trying to execute Get-AdminAuditLogConfig : $errormessage. Continuing" | Write-Log -LogPath $logFile -LogLevel "Warning" + } + "Checking permissions for app $($appId)"| Write-Log -LogPath $logFile Connect-ExchangeOnlineApplication -logFile $logFile -certificate $cert -appId $appId -organization $tenant try { @@ -346,7 +367,7 @@ function Get-O365 { "Lauching job number $($d) with startDate {0:yyyy-MM-dd} {0:HH:mm:ss} and endDate {1:yyyy-MM-dd} {1:HH:mm:ss}" -f ($newStartDate, $newEndDate) | Write-Log -LogPath $logFile $dateToProcess = ($newStartDate.ToString("yyyy-MM-dd")) - $jobName = "UnifiedAuditLog" + $dateToProcess + $jobName = "UnifiedAuditLog_" + $dateToProcess Start-RSJob -Name $jobName -ScriptBlock $launchSearch -FunctionsToImport Connect-ExchangeOnlineApplication, Write-Log, Get-LargeUnifiedAuditLog, Get-MailboxAuditLog -ArgumentList $cert, $appId, $tenant, $newStartDate, $newEndDate, $requestType, $recordTypes, $operations, $freeTexts, $IPAddresses, $userIds, $currentPath diff --git a/README.md b/README.md index 6c2381c..304d999 100755 --- a/README.md +++ b/README.md @@ -66,16 +66,15 @@ If you are investigating other Azure resources, with DFIR-O365RC: ## Installation and prerequisites + ### Using Docker _This is the recommended way of using DFIR-O365RC_ -Clone the repository and use `docker compose` (or the legacy `docker-compose`) to build the image, run the container and mount a volume (in the `output/` folder): +Just type : ```bash -sudo docker compose run dfir-o365rc -# using legacy Compose V1 -sudo docker-compose run dfir-o365rc +sudo docker run --rm -v .:/mnt/host -it anssi/dfir-o365rc:latest ``` DFIR-O365RC is ready to use: @@ -87,60 +86,26 @@ https://github.com/ANSSI-FR/DFIR-O365RC PS /mnt/host/output> ``` -### Manual Installation - -Clone the DFIR-O365RC repository. The module works on *PowerShell Desktop* and *PowerShell Core*. - -Please note that the `Connect-ExchangeOnline` cmdlet [requires Microsoft .NET Framework 4.7.2 or later](https://learn.microsoft.com/en-us/powershell/exchange/exchange-online-powershell-v2?view=exchange-ps#windows). - -DFIR-O365RC uses Boe Prox's [PoshRSJob](https://github.com/proxb/PoshRSJob) module as well as a lot of Microsoft modules to interact with the required SDKs. - -Install them by running: - -```powershell -Install-Module Az.Accounts -RequiredVersion 3.0.2 -Install-Module Az.Monitor -RequiredVersion 5.2.1 -Install-Module Az.Resources -RequiredVersion 7.2.0 -Install-Module ExchangeOnlineManagement -RequiredVersion 3.5.1 -Install-Module Microsoft.Graph.Authentication -RequiredVersion 2.20.0 -Install-Module Microsoft.Graph.Applications -RequiredVersion 2.20.0 -Install-Module Microsoft.Graph.Beta.Reports -RequiredVersion 2.20.0 -Install-Module Microsoft.Graph.Beta.Security -RequiredVersion 2.20.0 -Install-Module Microsoft.Graph.Identity.DirectoryManagement -RequiredVersion 2.20.0 -Install-Module PoshRSJob -RequiredVersion 1.7.4.4 -``` - -Once the modules are installed, launch a PowerShell prompt and locate your Powershell modules path: +If you would like to build your Docker image manually, clone the repository and use `docker compose` (or the legacy `docker-compose`) to build the image, run the container and mount a volume (in the `output/` folder): -```powershell -PS> $env:PSModulePath +```bash +sudo docker compose run dfir-o365rc +# using legacy Compose V1 +sudo docker-compose run dfir-o365rc ``` -Copy the [DFIR-O365RC directory](DFIR-O365RC/) in one of your modules path, for example: - -- on Windows: - - - `%UserProfile%\Documents\WindowsPowerShell\Modules` - - - `%ProgramFiles%\WindowsPowerShell\Modules` +### Using PowerShell - - `%SystemRoot%\system32\WindowsPowerShell\v1.0\Modules` +You can install the module on *PowerShell Desktop* and *PowerShell Core*. -- on Linux: - - - `/home/%username%/.local/share/powershell/Modules` - - - `/usr/local/share/powershell/Modules` - - - `/opt/microsoft/powershell/7/Modules` - -Restart the PowerShell prompt and import the DFIR-O365RC module: +Please note that the `Connect-ExchangeOnline` cmdlet [requires Microsoft .NET Framework 4.7.2 or later](https://learn.microsoft.com/en-us/powershell/exchange/exchange-online-powershell-v2?view=exchange-ps#windows). +To install the module from the PowerShell Gallery : ```powershell -PS> Import-Module DFIR-O365RC +Install-Module -Name ``` - +You can also install the module manually by cloning the DFIR-O365RC repository, install the required dependencies (check [DFIR-O365RC.psd1](DFIR-O365RC/DFIR-O365RC.psd1)) and add the [DFIR-O365RC directory](DFIR-O365RC/) in one of your PowerShell's modules path. ## Managing the DFIR-O365RC application @@ -353,8 +318,8 @@ Get-O365Light -startDate $startDate -endDate $endDate -appId $appId -tenant $ten Retrieve Unified Audit log events considered of interest in a time window between -90 days and -30 days from now: ```powershell -$endDate = Get-Date.AddDays(-30) -$startDate = Get-Date.AddDays(-90) +$endDate = (Get-Date).AddDays(-30) +$startDate = (Get-Date).AddDays(-90) Get-O365Light -startDate $startDate -endDate $endDate -appId $appId -tenant $tenant -certificatePath $certificatePath ```