Feature: Update Get-HawkTenantMailItemsAccessed

[jonnybottles]

What Problem Would This Feature Solve?

The current implementation of Get-HawkTenantMailItemsAccessed is limited and unproven—it was not included in Hawk 4.0 because its functionality is uncertain. Specifically:

• It only supports filtering by Application ID, which limits its utility.
• Users have no built-in option to retrieve mailbox access events for the entire tenant.
• There is no option to filter results by a specific user (UPN).
• The function does not leverage Get-SimpleUnifiedAuditLog for processing Unified Audit Log (UAL) data, resulting in less optimized, unflattened output.
• Without a mechanism to limit the time range of the log pull, the function may attempt to retrieve an excessive amount of data, potentially causing crashes or failures when pulling the UAL.

Proposed Solution

1. Enhance Parameter Flexibility:

   • Update the function so that it can retrieve all mail items accessed for the entire tenant when no filtering parameter is provided.
   • Add an optional parameter to filter by a User Principal Name (UPN) for targeted investigations.
   • Retain the existing functionality to filter by Application ID for cases where that is preferred.

2. Implement Time Window Limitation:

   • Introduce an optional parameter to limit the log pull to a reasonable timeframe (for example, a default of 48 hours with the ability to extend up to 7 days) to avoid overloading the system or causing crashes.

3. Integrate Get-SimpleUnifiedAuditLog:

   • Modify the function to leverage Get-SimpleUnifiedAuditLog for processing UAL data. This will ensure that the output is flattened and more easily consumable by spreadsheet applications.

4. Function Validation and Testing:

   • Clearly document that the function’s current state is uncertain, which is why it was not included in Hawk 4.0.
   • Conduct comprehensive testing with the new parameters to validate that:
     • The function can retrieve data for the entire tenant.
     • The function correctly filters data when a UPN or Application ID is provided.
     • The log pull respects the specified time window to prevent performance issues.

⚙️ Developer Section (For Hawk Team Members Only)

Technical Requirements

• Parameter Enhancements:

  • Modify the parameter block to include:
    • An optional parameter for UPN filtering.
    • An optional parameter for specifying a time window (default 48 hours, maximum up to 7 days).
  • Maintain the current Application ID parameter for backward compatibility.

• Data Retrieval:

  • Update the function to leverage Get-SimpleUnifiedAuditLog for processing UAL data, ensuring that the output is flattened for easier analysis.
  • Ensure that the function can process and export mailbox access events from the Unified Audit Log for the entire tenant when no filter is specified.
  • Implement proper pagination and interval handling to support the extended log pull within the specified timeframe.

• Output:

  • Export the retrieved data in the standard Hawk formats (CSV and JSON) following Hawk naming conventions.

Implementation Approach

• Update the logic in Get-HawkTenantMailItemsAccessed to check for:
  • No filtering parameter (retrieve all mail items accessed for the tenant).
  • A UPN parameter (filter results by user).
  • An Application ID parameter (retain existing behavior).
• Integrate Get-SimpleUnifiedAuditLog into the data processing pipeline to flatten nested JSON data.
• Add functionality to limit the log pull to a user-specified or default time window to prevent overloading the system.
• Include error handling and progress updates similar to other Hawk tenant functions.

Acceptance Criteria

• The function can be executed with no filter to retrieve all mailbox access events for the tenant.
• The function can be executed with a UPN parameter to filter by a specific user.
• The function can still filter by Application ID as originally designed.
• The log pull is limited to a reasonable time window (default 48 hours, extendable to 7 days) to prevent performance issues.
• The function leverages Get-SimpleUnifiedAuditLog to produce flattened output.
• The function outputs both CSV and JSON files that follow Hawk naming conventions.
• Comprehensive documentation is updated to reflect the new parameters and functionality.
• Testing confirms that the enhanced function operates reliably without crashing, even with extended data pulls.

[jonnybottles]

This function has been moved into the Hawk-> Internal >WorkInProgress folder as it is not ready for release.