Hawk - Tenant Investigation

Overview

Start-HawkTenantInvestigation is a comprehensive cmdlet that automates the collection and analysis of tenant-wide security data. It executes multiple specialized functions to gather information about tenant configuration, security settings, and potential security issues.

Note: A tenant investigation can take significant time to complete depending on the date range and amount of data. Consider running an initial investigation with a shorter timeframe to gauge execution time.

Interactive Mode

Running Start-HawkTenantInvestigation without parameters starts interactive mode:

Start-HawkTenantInvestigation

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-HawkTenantInvestigation with any of the following parameters:

Available Parameters

Parameter	Type	Required	Description	Example
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 from today, saving results to C:\HawkOutput while skipping the update check:

Start-HawkTenantInvestigation -DaysToLookBack 30 -FilePath 'C:\HawkOutput' -SkipUpdate

Date Range Investigation

Investigate a specific date range (January 2024) and output to a timestamped folder:

Start-HawkTenantInvestigation -StartDate '01/01/2024' -EndDate '01/31/2024' -FilePath 'C:\Investigations\Jan2024'

Tenant Investigation Functions

(Click to expand)

Note: Start-HawkTenantInvestigation executes the following functions in sequence. Each of these functions can also be run independently as a standalone command for targeted investigations.

Function Name	Description	Output Files
Get-HawkTenantConfiguration	Gathers basic tenant configuration including admin audit settings, organization config, remote domains, transport rules, and transport configuration.	AdminAuditLogConfig.txt OrgConfig.txt RemoteDomain.csv/.json TransportRules.csv/.json TransportConfig.csv/.json
Get-HawkTenantEDiscoveryConfiguration	Retrieves comprehensive eDiscovery permissions data from both built-in Exchange Online Role Groups and custom management role entries.	EDiscoveryRoles.csv/.json CustomEDiscoveryRoles.csv/.json
Get-HawkTenantEDiscoveryLog	Collects eDiscovery activity logs, tracking searches, exports, and case management activities.	Simple_eDiscoveryLogs.csv/.json eDiscoveryLogs.csv/.json
Get-HawkTenantAdminInboxRuleCreation	Searches the Unified Audit Log (UAL) for inbox rule creation events performed through administrative interfaces or PowerShell. Tracks when administrators or scripts create rules, and flags suspicious configurations like forwarding or deletion rules.	Simple_Admin_Inbox_Rules_Creation.csv/.json Admin_Inbox_Rules_Creation.csv/.json _Investigate_Admin_Inbox_Rules_Creation.csv/.json
Get-HawkTenantAdminInboxRuleModification	Searches the UAL for inbox rule modifications made through administrative interfaces or PowerShell. Focuses on rule changes made using administrative tools rather than user interfaces like Outlook. Flags suspicious modifications involving forwarding or deletion rules.	Simple_Admin_Inbox_Rules_Modification.csv/.json Admin_Inbox_Rules_Modification.csv/.json _Investigate_Admin_Inbox_Rules_Modification.csv/.json
Get-HawkTenantAdminInboxRuleRemoval	Searches the UAL for inbox rule removal events performed through administrative interfaces or PowerShell. Tracks when rules are deleted using administrative tools rather than user interfaces. Flags if removed rules had suspicious configurations.	Simple_Admin_Inbox_Rules_Removal.csv/.json Admin_Inbox_Rules_Removal.csv/.json _Investigate_Admin_Inbox_Rules_Removal.csv/.json
Get-HawkTenantAdminMailboxPermissionChange	Tracks administrative changes to mailbox permissions made through PowerShell or admin centers. Monitors when administrators grant or modify FullAccess, SendAs, or Send on Behalf permissions.	Simple_Mailbox_Permission_Change.csv/.json Mailbox_Permission_Change.csv/.json _Investigate_Mailbox_Permission_Change.csv/.json
Get-HawkTenantAdminEmailForwardingChange	Monitors administrative changes to email forwarding settings made through PowerShell or admin centers. Helps detect unauthorized forwarding configurations made using administrative tools rather than user interfaces.	Simple_Forwarding_Changes.csv/.json Forwarding_Changes.csv/.json Forwarding_Recipients.csv/.json
Get-HawkTenantDomainActivity	Monitors changes to domain configurations and federations in Microsoft 365.	Domain_Changes_Audit.csv/.json
Get-HawkTenantRBACChange	Collects Role-Based Access Control changes in the UAL, including role assignments and management scopes. Assists in tracking M365 administrative permissions changes across the the tenant	Simple_RBAC_Changes.csv/.json RBAC_Changes.csv/.json
Get-HawkTenantEntraIDAuditLog	Retrieves Microsoft Entra ID audit logs for comprehensive identity management tracking.	EntraIDAuditLogs.csv/.json
Get-HawkTenantEntraIDAppAuditLog	Searches the UAL for historical events related to application permissions and consent grants in Microsoft Entra ID. It focuses on tracking when and by whom application permissions were granted or modified.	Entra_ID_Application_Audit.csv/.json _Investigate_Consent_Grants.csv/.json
Get-HawkTenantEXOAdmin	Exports Exchange Online administrator roles and memberships.	ExchangeOnlineAdministrators.csv/.json
Get-HawkTenantConsentGrant	Reviews application and delegated permission grants. Flags for investigation if overly permissive or risky risky permissions are assigned.	Consent_Grants.csv/.json
Get-HawkTenantRiskyUsers	Collects Risky Users log from Microsoft Entra ID. Flags for investigation if Risky users are confirmed to be compromised, or if users are at a High, Medium, or Low risk level.	RiskyUsers.csv/.json _Investigate_Compromised_Users.csv/.json _Investigate_Risky_Users.csv/.json
Get-HawkTenantRiskDetections	Retrieves risk detection events from Microsoft Entra ID. Differs from Risky Users as this is an aggregated assessment of Risk Events as. Flags for investigation if Risky detections are confirm a user to be compromised, or if users are at a High, Medium, or Low risk level.	Risk_Detections.csv/.json _Investigate_Confirmed_Compromised_Risk_Detection.csv/.json _Investigate_Risk_Detection.csv/.json
Get-HawkTenantEntraIDAdmin	Exports Microsoft Entra ID administrator roles and assignments.	EntraIDAdministrators.csv/.json
Get-HawkTenantAppAndSPNCredentialDetail	Examines application and service principal credential configurations.	SPNCertsAndSecrets.csv/.json ApplicationCertsAndSecrets.csv/.json
Get-HawkTenantEntraIDUser	Exports Microsoft Entra ID user information with focus on security-relevant properties.	EntraIDUsers.csv/.json

Investigative Signals

(Click to expand)

During Tenant 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_Admin_Inbox_Rules_Creation.csv/.json _Investigate_Admin_Inbox_Rules_Modification.csv/.json _Investigate_Admin_Inbox_Rules_Removal.csv/.json	Rules that contain any of: ForwardTo settings ForwardAsAttachmentTo settings RedirectTo settings DeleteMessage set to true Move to Deleted Items folder	Attackers commonly use inbox rules for persistent data exfiltration and to hide their activities. Forward/redirect rules can secretly send copies of emails to attacker-controlled addresses, while deletion rules can remove evidence of compromise or hide malicious communications from the user.
_Investigate_Confirmed_Compromised_Risk_Detection.csv/.json _Investigate_Risk_Detection.csv/.json	Users with RiskState = "confirmedCompromised" Risk detections at High/Medium/Low levels	These signals represent Microsoft's evaluation of user risk based on machine learning and threat intelligence. Confirmed compromised accounts indicate high-confidence detections of malicious activity, while risk levels indicate potential compromise based on suspicious patterns like impossible travel or unusual behavior.
_Investigate_Confirmed_Users.csv/.json _Investigate_Risky_Users.csv/.json	Users with RiskState = "confirmedCompromised" Users with High/Medium/Low risk levels	Similar to risk detections, these files track user accounts that have exhibited suspicious behavior or confirmed compromise. Review these in conjunction with risk detections to understand the full scope of potentially affected accounts and the timeline of suspicious activities.
_Investigate_Consent_Grants.csv/.json	Consent grants flagged for review based on specific risk criteria: Broad-Scope Grants: Grants where ConsentType includes 'AllPrincipals' or the permission contains the term 'all'. Extremely Dangerous Grants: Grants with permissions matching: AppRoleAssignment.ReadWrite.All RoleManagement.ReadWrite.Directory High Risk Grants: Grants with permissions matching patterns such as: BitlockerKey.Read.All Any permission starting with Chat. Directory.ReadWrite.All Any permission starting with eDiscovery. Any permission starting with Files. MailboxSettings.ReadWrite Mail.ReadWrite Mail.Send Any permission starting with Sites. Any permission starting with User.	These investigation files document consent grants that warrant further review. Overly permissive or risky grants, whether due to broad-scope access, extremely dangerous privileges, or high risk permission patterns, may signal over provisioning or potential compromise. Reviewing these files helps ensure that permission assignments adhere to security best practices.
_Investigate_Mailbox_Permission_Change.csv/.json	Grants of sensitive permissions: FullAccess rights SendAs rights Send on Behalf rights	Attackers often add mailbox permissions to maintain persistent access or to access additional mailboxes. FullAccess rights provide complete mailbox control, while SendAs/Send on Behalf rights can be used for social engineering or to send malicious emails that appear legitimate to recipients.

Spread Your Wings

Go Back

Review the previous section: Permissions Setup.

Circle Back

Up Next

Uncover the details: User Investigations are up next.

Fly Forward

User Guide:

Tenant Investigation