Merge pull request #244 from T0pCyber/feature/236-Expand-M365-Log-Col…

…lection

Feature/236 expand m365 log collection

Hawk/Hawk.psd1

@@ -85,6 +85,7 @@
 	'Get-HawkTenantMailItemsAccessed',
 	'Get-HawkUserMailItemsAccessed',
 	'Get-HawkUserExchangeSearchQuery',
+	'Get-HawkUserMailSendActivity',
 	'Get-HawkTenantAppAndSPNCredentialDetail',
 	'Get-HawkTenantEntraIDUser',
 	'Get-HawkTenantDomainActivity',

Hawk/changelog.md

@@ -99,3 +99,4 @@
 - Add ability to pass command line arguments to Start-HawkUserInvestigation and Start-HawkTenantInvestigation
 - Added search of Exchange Search Queries to the User Investigation (Get-HawkUserExchangeSearchQuery)
 - Implemented check to verify that an Exchange operation is enabled for auditing before attempting to pull logs
+- Added log pull of user Send activity to the User Investigation (Get-HawkUserMailSendActivity)

Hawk/functions/User/Get-HawkUserExchangeSearchQuery.ps1

@@ -52,7 +52,7 @@ Function Get-HawkUserExchangeSearchQuery {
                 if (Test-OperationEnabled -User $User -Operation 'SearchQueryInitiated') {
                     Out-LogFile "Operation 'SearchQueryInitiated' verified enabled for $User." -Information
                     try {
-                        #Retrieve all audit data for mailitems accessed 
+                        #Retrieve all audit data for Exchange search queries 
                         $SearchCommand = "Search-UnifiedAuditLog -Operations 'SearchQueryInitiatedExchange' -UserIds $User"
                         $ExchangeSearches = Get-AllUnifiedAuditLogEntry -UnifiedSearch $SearchCommand
 

Hawk/functions/User/Get-HawkUserMailSendActivity.ps1

@@ -0,0 +1,95 @@
+Function Get-HawkUserMailSendActivity {
+    <#
+    .SYNOPSIS
+        This will export Send operations from the Unified Audit Log (UAL). Must be connected to Exchange Online
+        using the Connect-EXO or Connect-ExchangeOnline module. M365 E5 or G5 license is required for this function to work.
+        This telemetry will ONLY be availabe if Advanced Auditing is enabled for the M365 user.
+    .DESCRIPTION
+        This function queries for message-sending activity within Exchange, providing visibility into outbound communications 
+        that could be relevant for identifying data exfiltration attempts, phishing campaigns, or other malicious activity.
+    .PARAMETER UserPrincipalName
+        Specific user(s) to be investigated
+    .EXAMPLE
+        Get-HawkUserMailSendActivity -UserPrincipalName [email protected]
+        Returns send activity queries from Unified Audit Log (UAL) that correspond to the UserPrincipalName that is provided
+    .OUTPUTS
+        [email protected] /json
+        [email protected]/json
+    
+    .LINK
+        https://www.microsoft.com/security/blog/2020/12/21/advice-for-incident-responders-on-recovery-from-systemic-identity-compromises/
+    
+    .NOTES
+        "Operation Properties" and "Folders" will return "System.Object" as they are nested JSON within the AuditData field.
+        You will need to conduct individual log pull and review via PowerShell or other SIEM to determine values
+        for those fields.
+    #>
+        [CmdletBinding()]
+        param(
+            [Parameter(Mandatory=$true)]
+            [array]$UserPrincipalName
+        )
+
+        BEGIN {
+            # Check if Hawk object exists and is fully initialized
+            if (Test-HawkGlobalObject) {
+                Initialize-HawkGlobalObject
+            }
+            Out-LogFile "Starting Unified Audit Log (UAL) search for mail'Send' logs" -Action
+            Out-LogFile "Please be patient, this can take a while..." -Information
+            Test-EXOConnection
+        }#End Begin
+
+        PROCESS {
+
+            #Verify UPN input
+            [array]$UserArray = Test-UserObject -ToTest $UserPrincipalName
+
+            foreach($UserObject in $UserArray) {
+                [string]$User = $UserObject.UserPrincipalName
+
+                # Verify that user has operation enabled for auditing. Otherwise, move onto next user.
+                if (Test-OperationEnabled -User $User -Operation 'Send') {
+                    Out-LogFile "Operation 'Send' verified enabled for $User." -Information
+                    try {
+                        #Retrieve all audit data for Exchange send activity
+                        $SearchCommand = "Search-UnifiedAuditLog -Operations 'Send' -UserIds $User"
+                        $ExchangeSends = Get-AllUnifiedAuditLogEntry -UnifiedSearch $SearchCommand
+
+                        if ($ExchangeSends.Count -gt 0){
+
+                            #Define output directory path for user
+                            $UserFolder = Join-Path -Path $Hawk.FilePath -ChildPath $User
+
+                            #Create user directory if it doesn't already exist
+                            if (-not (Test-Path -Path $UserFolder)) {
+                                New-Item -Path $UserFolder -ItemType Directory -Force | Out-Null
+                            }
+
+                            #Compress raw data into more simple view
+                            $ExchangeSendsSimple = $ExchangeSends | Get-SimpleUnifiedAuditLog
+
+                            #Export both raw and simplistic views to specified user's folder
+                            $ExchangeSends | Select-Object -ExpandProperty AuditData | Convertfrom-Json | Out-MultipleFileType -FilePrefix "SendActivity_$User" -User $User -csv -json
+                            $ExchangeSendsSimple | Out-MultipleFileType -FilePrefix "Simple_SendActivity_$User" -User $User -csv -json
+                        } else {
+                            Out-LogFile "Get-HawkUserMailSendActivity completed successfully" -Information
+                            Out-LogFile "No items found for $User." -Information
+                        }
+                    } catch {
+                        Out-LogFile "Error processing Send Activity for $User : $_" -isError
+                        Write-Error -ErrorRecord $_ -ErrorAction Continue
+                    }
+                } else {
+                    Out-LogFile "Operation 'Send' is not enabled for $User." -Information
+                    Out-LogFile "No data recorded for $User." -Information
+                }
+            }
+
+        }#End Process
+
+        END{
+            Out-Logfile "Completed exporting Send Activity logs" -Information
+        }#End End
+
+    }

Hawk/functions/User/Start-HawkUserInvestigation.ps1

@@ -200,6 +200,16 @@
 					Out-LogFile "Running Get-HawkUserMailItemsAccessed" -Action
 					Get-HawkUserMailItemsAccessed -UserPrincipalName $User
 				}
+
+				if ($PSCmdlet.ShouldProcess("Running Get-HawkUserExchangeSearchQuery for $User")) {
+					Out-LogFile "Running Get-HawkUserExchangeSearchQuery" -Action
+					Get-HawkUserExchangeSearchQuery -UserPrincipalName $User
+				}
+
+				if ($PSCmdlet.ShouldProcess("Running Get-HawkUserMailSendActivity for $User")) {
+					Out-LogFile "Running Get-HawkUserMailSendActivity" -Action
+					Get-HawkUserMailSendActivity -UserPrincipalName $User
+				}
 
 				if ($PSCmdlet.ShouldProcess("Running Get-HawkUserMobileDevice for $User")) {
 					Out-LogFile "Running Get-HawkUserMobileDevice" -Action