What problem would this feature solve?

The existing Get-HawkUserHiddenRule function relies on the EWS Managed API 2.2, which is now deprecated and depends on a specific DLL (Microsoft.Exchange.WebServices.dll) that is no longer maintained. This introduces several issues:

• Outdated Technology: EWS is deprecated and scheduled for discontinuation for Exchange Online support after October 2026.
• Security Concerns: The current implementation uses basic authentication (which does not support MFA), whereas modern solutions require OAuth-based authentication.
• Maintenance and Compatibility: Relying on a specific, deprecated DLL poses a risk for future compatibility and maintenance burdens.
• Encouraging Modernization: Migrating to Microsoft Graph API/SDK aligns with Microsoft’s current direction and industry best practices.

By moving to Microsoft Graph, we ensure that the functionality remains supported, secure, and easier to maintain. The new implementation should use the Microsoft Graph PowerShell SDK (or direct API calls where necessary) to retrieve mailbox rules. Note that the current EWS-based implementation has been moved to the Internal->WorkInProgress folder for archival and reference purposes.

Proposed Solution

1. Migrate from EWS to Microsoft Graph:

   • Remove EWS Dependencies: Eliminate reliance on Microsoft.Exchange.WebServices.dll and the deprecated EWS Managed API.
   • Use Microsoft Graph PowerShell SDK: Utilize commands such as:

     Get-MgUserMailFolderMessageRule -UserId "[email protected]" -MailFolderId "Inbox"

     This retrieves the visible message rules for the specified user's Inbox.
   • Investigate Extended Properties: Determine if Microsoft Graph can be used to fetch extended properties or other indicators to detect “hidden” rules. If this is not fully supported, document the limitation and guide users toward manual investigation (e.g., using MFCMapi).

2. Implement Modern Authentication:

   • Transition from using Get-Credential and basic authentication to OAuth-based authentication through Microsoft Entra ID (formerly Azure AD).
   • Update authentication logic to use token-based authentication, as supported by the Graph SDK.

3. Code Base Cleanup and Legacy Preservation:

   • Archive Current Implementation: The existing EWS-based code for Get-HawkUserHiddenRule has been moved to the Internal->WorkInProgress folder. This allows us to maintain a reference to the legacy implementation without cluttering the main code base.
   • Remove Deprecated Code: Remove the EWS-specific code from the main branch to avoid future dependency issues and encourage use of the modern Graph-based solution.

⚙️ Developer Section (For Hawk Team Members Only)

Technical Requirements

• Microsoft Graph PowerShell SDK:

  • Install and update the SDK (Install-Module Microsoft.Graph).
  • Use Get-MgUserMailFolderMessageRule to retrieve inbox rules.

• OAuth Authentication:

  • Register an application in Microsoft Entra ID with necessary permissions (e.g., Mail.Read, Mail.ReadWrite).
  • Implement token retrieval and authentication within the script.

• Extended Properties Handling:

  • Evaluate if extended properties can be retrieved via Microsoft Graph to identify “hidden” inbox rules.
  • If not feasible, document this limitation and advise manual investigation as a fallback.

• Support for Single and Bulk User Processing:

  • Ensure that the new implementation supports both single-user queries and bulk processing scenarios.

Implementation Approach

1. Setup:

   • Register a new application in Microsoft Entra ID.
   • Configure required API permissions.
   • Update project documentation to reflect OAuth-based authentication procedures.

2. Replace EWS Logic:

   • Remove the dependency on Microsoft.Exchange.WebServices.dll and related EWS code.
   • Implement Graph API calls using the Microsoft Graph PowerShell SDK. For example:

     $messageRules = Get-MgUserMailFolderMessageRule -UserId $user -MailFolderId "Inbox"

   • Parse and process the returned message rules to identify potential hidden rules (or document the detection limitations).

3. Logging and Error Handling:

   • Maintain existing logging mechanisms (e.g., via Out-LogFile) for consistency.
   • Log any instances where the Graph API does not expose necessary extended properties, including guidance for manual review if needed.

4. Legacy Code Preservation:

   • Confirm that the current EWS-based implementation is safely archived in the Internal->WorkInProgress folder for reference and potential rollback.

Acceptance Criteria

• ✅ Graph API Integration: The updated Get-HawkUserHiddenRule function successfully retrieves inbox rules using the Microsoft Graph PowerShell SDK.
• ✅ Modern Authentication: OAuth-based authentication is implemented, eliminating the need for basic PSCredential prompts.
• ✅ Extended Properties & Hidden Rule Detection:
  • If Microsoft Graph provides access to extended properties, they are used to evaluate and flag potential hidden rules.
  • If not, the script logs this limitation and advises users to perform manual review (e.g., via MFCMapi).
• ✅ Bulk and Single User Support: The function operates correctly for both individual and multiple user queries.
• ✅ Legacy Code Archived: The old EWS-based code is confirmed to be available in the Internal->WorkInProgress folder.
• ✅ Consistent Logging and Output: The output (e.g., CSV files and investigation logs) remains consistent with previous implementations for ease of transition and further analysis.

This feature request aims to modernize the Get-HawkUserHiddenRule function by replacing deprecated EWS-based code with a Microsoft Graph API/SDK implementation while ensuring that the legacy code is preserved for reference. Please review and provide any additional requirements or concerns before proceeding.