User Guide:

User Investigation

Overview

Start-HawkUserInvestigation is a comprehensive cmdlet that performs a targeted investigation of individual user accounts. It executes multiple specialized functions to gather detailed information about user configuration, activities, and potential security issues.

Note: A user investigation involves detailed data collection and can take significant time to complete. Run one user at a time initially to gauge execution time and plan investigations accordingly.


Interactive Mode

Running Start-HawkUserInvestigation without parameters starts interactive mode:

Start-HawkUserInvestigation -UserPrincipalName user@contoso.com

The cmdlet will guide you through:

  • Selecting an output directory for investigation results
  • Choosing a date range (last X days or specific start/end dates)
  • Confirming settings before proceeding

Interactive mode is recommended for first-time users and ad-hoc investigations.


Non-Interactive Mode

For automated operations, run Start-HawkUserInvestigation with any of the following parameters:


Available Parameters

Parameter Type Required Description Example
UserPrincipalName String Yes UPN of user to investigate 'user@contoso.com'
StartDate DateTime No* Beginning of investigation period '01/01/2024'
EndDate DateTime No* End of investigation period '01/31/2024'
DaysToLookBack Integer No* Number of days to investigate (1-365) 30
FilePath String Yes Output directory for investigation results 'C:\HawkOutput'
SkipUpdate Switch No Bypass Hawk update check -SkipUpdate

* Either StartDate/EndDate pair OR DaysToLookBack must be specified


Examples:

Quick 30-Day Investigation

Look back 30 days for a single user, saving results to C:\HawkOutput:

Start-HawkUserInvestigation -UserPrincipalName user@contoso.com -DaysToLookBack 30 -FilePath 'C:\HawkOutput' -SkipUpdate

Date Range Investigation

Investigate a specific user for January 2024 and output to a timestamped folder:

Start-HawkUserInvestigation -UserPrincipalName user@contoso.com -StartDate '01/01/2024' -EndDate '01/31/2024' -FilePath 'C:\HawkOutput'

Multiple User Investigation

Investigate all users with CustomAttribute1="VIP" for January 2024:

$users = @('user1@contoso.com', 'user2@contoso.com')
Start-HawkUserInvestigation -UserPrincipalName $users -DaysToLookBack 30 -FilePath 'C:\Investigations'



Function Name Description Output Files
Get-HawkUserUALSignInLog Retrieves and analyzes historical authentication events from the Unified Audit Log (UAL), providing visibility into login patterns and sources. When enabled with -ResolveIPLocations, performs IP geolocation lookups to identify login origins and flags known Microsoft IP addresses.
  • Converted_Authentication_Logs_[user].csv/.json
  • Raw_Authentication_Logs_[user].csv/.json
Get-HawkUserConfiguration Gathers baseline information about the user including mailbox settings, statistics, folder statistics, and CAS mailbox info.
  • Mailbox_Info_[user].txt
  • Mailbox_Statistics_[user].txt
  • Mailbox_Folder_Statistics_[user].txt
  • CAS_Mailbox_Info_[user].txt
  • Mailbox_Archive_Statistics_[user].txt (if applicable)
Get-HawkUserInboxRule Retrieves current inbox rules directly from specified users' mailboxes using Get-InboxRule. Analyzes rules for suspicious configurations (like external forwarding, deletions, or redirects) and flags them for investigation. Also collects Sweep rules if present. Unlike UAL-based functions, this shows current rules rather than historical changes.
  • _Investigate_InboxRules_[user].csv/.json
  • InboxRules_[user].csv/.json
  • All_InboxRules_[user].csv/.json
  • SweepRules_[user].csv/.json (if present)
Get-HawkUserEmailForwarding Retrieves current email forwarding configurations for specified users by directly querying their mailbox settings. Reports all forwarding states and flags concerning configurations (like external forwarding) for investigation. Unlike the tenant-level function, this shows current forwarding status rather than historical changes.
  • _Investigate_Users_WithForwarding_[user].csv/.json
  • User_ForwardingReport_[user].csv/.json
  • ForwardingReport_[user].csv/.json
Get-HawkUserAutoReply Retrieves automatic reply (out-of-office) settings for specified users. Only exports configurations when AutoReplyState is enabled. Used to verify if auto-replies are active and review their content.
  • AutoReply_[user].txt
Get-HawkUserEntraIDSignInLog Retrieves Microsoft Entra ID sign-in logs for specified users from the most recent 14 days (due to Graph API limitations). Analyzes sign-in patterns and flags risky sign-ins for investigation, including both real-time risk assessments during sign-in and aggregated risk levels.
  • Entra_Sign_In_Log_[user].csv
  • _Investigate_Entra_Sign_In_Log_[user].csv
Get-HawkUserMailboxAuditing Retrieves mailbox audit logs from the UAL, focusing on two distinct types of activities: individual item operations (ExchangeItem) and aggregated access patterns (ExchangeItemGroup). Each type is processed separately, with both simplified and detailed output formats to support different analysis needs.
  • ExchangeItem_Simple_[user].csv/.json
  • ExchangeItem_Logs_[user].csv/.json
  • ExchangeItemGroup_Simple_[user].csv/.json
  • ExchangeItemGroup_Logs_[user].csv/.json
Get-HawkUserAdminAudit Scans the UAL for any administrative changes made to the user's account and permissions.
  • Simple_User_Changes_[user].csv/.json
  • User_Changes_[user].csv/.json
Get-HawkUserMessageTrace Retrieves the standard message tracking logs for sent messages. This function provides a snapshot of sender, recipient, and delivery status information for the last 7 days, limited to basic routing details.
  • Message_Trace_[user].csv/.json
Get-HawkUserMailItemsAccessed Collects mail access logs for user from the UAL. Useful for detecting unauthorized message access and retrieval.
  • MailItemsAccessed_[user].csv/.json
  • Simple_MailItemsAccessed_[user].csv/.json
Get-HawkUserExchangeSearchQuery Collects UAL SearchQueryInitiatedExchange logs for associated user. Useful for identifying potential reconnaissance activities in Exchange.
  • ExchangeSearches_[user].csv/.json
  • Simple_ExchangeSearches_[user].csv/.json
Get-HawkUserMailSendActivity Tracks mail sending activity by querying the UAL for "Send" operations. It retrieves detailed audit data—including contextual information on the sending events.
  • SendActivity_[user].csv/.json
  • Simple_SendActivity_[user].csv/.json
Get-HawkUserSharePointSearchQuery Collects UAL SearchQueryInitiatedSharePoint logs for associated user. Useful for identifying potential reconnaissance activities in SharePoint.
  • SharePointSearches_[user].csv/.json
  • Simple_SharePointSearches_[user].csv/.json
Get-HawkUserMobileDevice Retrieves all mobile devices connected to a mailbox and flags those that first synchronized during the investigation window for further review.
  • MobileDevices_[user].csv/.json
  • _Investigate_MobileDevice_[user].csv/.json


During User Investigations, Hawk automatically flags suspicious activities and configurations that warrant further review. These findings are stored in files prefixed with "_Investigate_" and represent detection logic built into specific functions:

Detection File What Triggers This Flag Why This Matters
_Investigate_Entra_Sign_In_Log_[user].csv/.json Entra ID sign-ins flagged for:
  • High/Medium/Low risk levels assigned by Entra ID to RiskLevelDuringSignIn property
  • High/Medium/Low risk levels assigned by Entra ID to RiskLevelAggregated property
 Microsoft Entra ID algorithms analyzes each sign-in for risk indicators. High, Medium, and Low risk ratings often indicate authentication patterns that deviate from the user's baseline behavior or are indicative of Risky activities. These automated detections can identify compromised accounts before manual analysis reveals the intrusion.
_Investigate_InboxRules_[user].csv/.json Rules that contain any of:
  • ForwardTo settings
  • ForwardAsAttachmentTo settings
  • RedirectTo settings
  • DeleteMessage set to true
  • Move to Deleted Items folder
 Attackers frequently create inbox rules to automatically exfiltrate data or hide their activities. The rules can silently forward emails to external addresses or delete potential evidence of compromise.
_Investigate_MobileDevice_[user].csv/.json Mobile devices that:
  • Had their first synchronization time (FirstSyncTime) after the investigation start date
 New mobile device connections during an incident timeline warrant investigation, as attackers may add their own devices to maintain persistent mailbox access. When investigating a potential compromise, any new device synchronizations within the investigation period should be validated as legitimate user activity.
_Investigate_Users_WithForwarding_[user].csv/.json Mailbox has any forwarding configured:
  • ForwardingAddress is set, OR
  • ForwardingSMTPAddress is set
 Email forwarding at the mailbox level is a common data exfiltration technique. Unlike inbox rules which forward individual messages, mailbox forwarding ensures a copy of every received email is sent to another address. This can indicate unauthorized configuration changes designed to silently copy mailbox contents to external destinations.


Spread Your Wings


Go Back

Review the previous section: Tenant Investigation.

Circle Back
Up Next

Smooth the flight path: Troubleshooting is next.

Fly Forward