Merge pull request #262 from T0pCyber/feature/251-tr-1-implement-unit…

…-testing-convert-hawkdaystodatetestsps1

Feature/251 tr 1 implement unit testing convert hawkdaystodatetestsps1

Hawk/Hawk.psd1

@@ -53,10 +53,9 @@
 	FunctionsToExport  =
 	'Get-HawkTenantConfiguration',
 	'Get-HawkTenantEDiscoveryConfiguration',
-	'Get-HawkTenantInboxRule',
 	'Get-HawkTenantConsentGrant',
 	'Get-HawkTenantRBACChange',
-	'Get-HawkTenantAzureAppAuditLog',
+	'Get-HawkTenantEntraIDAppAuditLog',
 	'Get-HawkUserUALSignInLog',
 	'Get-HawkUserConfiguration',
 	'Get-HawkUserEmailForwarding',
@@ -73,7 +72,6 @@
 	'Start-HawkUserInvestigation',
 	'Update-HawkModule',
 	'Get-HawkUserAdminAudit',
-	'Get-HawkTenantAuthHistory',
 	'Get-HawkUserHiddenRule',
 	'Get-HawkMessageHeader',
 	'Get-HawkUserPWNCheck',
@@ -82,7 +80,6 @@
 	'Get-HawkUserMobileDevice',
 	'Get-HawkTenantEntraIDAdmin',
 	'Get-HawkTenantEXOAdmin',
-	'Get-HawkTenantMailItemsAccessed',
 	'Get-HawkUserMailItemsAccessed',
 	'Get-HawkUserExchangeSearchQuery',
 	'Get-HawkUserMailSendActivity',
@@ -96,7 +93,6 @@
 	'Get-HawkTenantRiskyUsers',
 	'Get-HawkTenantRiskDetections',
 	'Get-HawkTenantRiskyServicePrincipals'
-
 	# Cmdlets to export from this module
 	# CmdletsToExport = ''
 

Hawk/functions/Tenant/Get-HawkTenantAdminEmailForwardingChange.ps1

@@ -89,7 +89,7 @@ Search-UnifiedAuditLog -RecordType ExchangeAdmin -Operations @(
                     'ForwardingSMTPAddress',
                     'ExternalEmailAddress',
                     'PrimarySmtpAddress',
-                    'RedirectTo',             # Added from other LLM suggestion
+                    'RedirectTo',            
                     'DeliverToMailboxAndForward',  # Corrected parameter name
                     'DeliverToAndForward'     # Alternative parameter name
                 ) -or

Hawk/functions/Tenant/Get-HawkTenantConsentGrant.ps1

@@ -61,7 +61,7 @@
     }
 
     if($BroadGrantCount -gt 0) {
-        Out-LogFile "Found $BroadGrantCount Broad-Scope ('AllPrincipals' or '*.All') Grant(s)" -notice
+        Out-LogFile "Found $BroadGrantCount broad-scoped grants ('AllPrincipals' or '*.All')" -notice
         $flag = $true
     }
 

Hawk/functions/Tenant/Get-HawkTenantEXOAdmin.ps1

@@ -10,7 +10,7 @@
     PS C:\> Export-EXOAdmin -EngagementFolder foldername
     Exports Exchange Admins UserPrincipalName to .csv
 .OUTPUTS
-    EXOAdmins.csv
+    ExchangeOnlineAdministrators.csv/.json
 .NOTES
 #>
 BEGIN{

Hawk/functions/Tenant/Get-HawkTenantEntraIDAppAuditLog.ps1

@@ -0,0 +1,113 @@
+Function Get-HawkTenantEntraIDAppAuditLog{
+<#
+.SYNOPSIS
+    Retrieves audit logs for application permission and consent events in Microsoft Entra ID.
+
+.DESCRIPTION
+    This function searches the Microsoft 365 Unified Audit Log for historical events related to 
+    application permissions and consent grants in Microsoft Entra ID (formerly Azure AD). It focuses 
+    on tracking when and by whom application permissions were granted or modified.
+
+    Key events tracked:
+    - OAuth2 permission grant additions
+    - Application consent grants
+    - Changes to application permissions
+
+    The function provides historical context to complement Get-HawkTenantConsentGrant, which shows 
+    current permission states. While Get-HawkTenantConsentGrant shows what permissions exist now, 
+    this function helps you understand how and when those permissions were established.
+
+    The audit data includes:
+    - Timestamp of permission changes
+    - UserID/UPN of who made the changes
+    - Target application details
+    - Client IP address of where changes originated
+    - Operation details and result status
+
+.OUTPUTS
+    File: Entra_ID_Application_Audit.csv/.json
+    Path: \Tenant
+    Description: Contains all application permission and consent events found in the audit logs with fields for:
+    - Id: Unique identifier for the audit event
+    - Operation: Type of operation performed (e.g., Add OAuth2PermissionGrant)
+    - ResultStatus: Success/failure status of the operation
+    - Workload: The workload where the operation occurred
+    - ClientIP: IP address where the operation originated
+    - UserID: User who performed the operation
+    - ActorUPN: UserPrincipalName of the user who performed the action
+    - TargetName: Name of the application affected
+    - EnvTime: Timestamp of the event
+    - CorrelationId: Identifier to correlate related events
+
+.EXAMPLE
+    Get-HawkTenantEntraIDAppAuditLog
+
+    Searches the audit logs for all application permission and consent events within the configured 
+    time window. Results are exported to Entra_ID_Application_Audit.csv and .json files.
+
+.NOTES
+    Author: Jonathan Butler
+    Version: 4.0
+    
+
+.LINK
+    https://learn.microsoft.com/en-us/microsoft-365/security/office-365-security/detect-and-remediate-illicit-consent-grants
+
+.LINK
+    https://learn.microsoft.com/en-us/microsoft-365/compliance/audit-log-activities
+#>
+Begin {
+	#Initializing Hawk Object if not present
+    # Check if Hawk object exists and is fully initialized
+    # Check if Hawk object exists and is fully initialized
+    if (Test-HawkGlobalObject) {
+        Initialize-HawkGlobalObject
+    }
+
+
+	Out-LogFile "Gathering Tenant information" -Action
+	Test-EXOConnection
+}#End BEGIN
+
+PROCESS{
+# Make sure our variables are null
+$AzureApplicationActivityEvents = $null
+
+Out-LogFile "Searching UAL for Entra ID Application Activities" -Action
+
+# Search the unified audit log for events related to application activity
+# https://docs.microsoft.com/en-us/microsoft-365/security/office-365-security/detect-and-remediate-illicit-consent-grants
+$AzureApplicationActivityEvents = Get-AllUnifiedAuditLogEntry -UnifiedSearch ("Search-UnifiedAuditLog -RecordType 'AzureActiveDirectory' -Operations 'Add OAuth2PermissionGrant.','Consent to application.' ")
+
+# If null we found no changes to nothing to do here
+if ($null -eq $AzureApplicationActivityEvents){
+	Out-LogFile "Get-HawkTenantEntraIDAppAuditLog completed successfully" -Information
+	Out-LogFile "No Application related events found in the search time frame." -Action
+}
+
+# If not null then we must have found some events so flag them
+else {
+	Out-LogFile "Application Rights Activity found." -Notice
+	Out-LogFile "Please review these Entra_ID_Application_Audit.csv to ensure any changes are legitimate." -Notice
+
+	# Go thru each even and prepare it to output to CSV
+	Foreach ($event in $AzureApplicationActivityEvents){
+
+		$event.auditdata | ConvertFrom-Json | Select-Object -Property Id,
+			Operation,
+			ResultStatus,
+			Workload,
+			ClientIP,
+			UserID,
+			@{Name='ActorUPN';Expression={($_.ExtendedProperties | Where-Object {$_.Name -eq 'actorUPN'}).value}},
+			@{Name='targetName';Expression={($_.ExtendedProperties | Where-Object {$_.Name -eq 'targetName'}).value}},
+			@{Name='env_time';Expression={($_.ExtendedProperties | Where-Object {$_.Name -eq 'env_time'}).value}},
+			@{Name='correlationId';Expression={($_.ExtendedProperties | Where-Object {$_.Name -eq 'correlationId'}).value}}`
+			| Out-MultipleFileType -fileprefix "Entra_ID_Application_Audit" -csv -json -append
+	}
+}
+}#End PROCESS
+END{
+Out-LogFile "Completed gathering Tenant App Audit Logs" -Information
+}#End END
+}