DC-1 Extend Log Retrieval Period

[jonnybottles]

What happened?

Microsoft 365 audit log retention periods have been extended, but they vary based on the organization's licensing:

• All licenses (E3 and E5) now support audit log retention up to 180 days.
• E5 licenses support audit log retention up to 365 days.

Currently, Hawk scripts only support parsing audit logs back to 90 days. This limitation prevents users from accessing audit logs older than 90 days using Hawk, even though the data is available in Microsoft 365. Hawk should be updated to support parsing audit logs up to 180 days for all users and up to 365 days for organizations with E5 licenses. The default should remain at 90 days, but users should have the option to specify longer date ranges based on their licensing.

Steps to Reproduce

1. Use Hawk scripts that query audit logs (e.g., Search-HawkTenantEXOAuditLog.ps1).
2. Set the StartDate parameter to a date older than 90 days ago (e.g., 150 days ago).
3. Run the script.
4. Observe that the script does not retrieve data beyond 90 days or returns errors due to the limitation.

Hawk Version

Version 3.1.0

---

🔧 Developer Section (For Hawk Team Members Only)

The following sections are for internal use by the Hawk development team. Users can ignore these fields.

Technical Analysis

Root cause analysis

• Hawk scripts are currently designed to support parsing audit logs up to 90 days.
• Microsoft 365 now retains audit logs up to 180 days for all licenses (E3 and E5) and up to 365 days for E5 licenses.
• Hawk does not take advantage of the extended retention periods and unnecessarily restricts users to 90 days.
• There is a need to allow users to specify longer date ranges based on their licensing without causing errors.
• Users cannot access audit logs older than 90 days through Hawk, despite the data being available.

Implementation Plan

1. Update Default Date Range:

   • Modify scripts to default to a StartDate of 90 days ago.
   • Allow users to specify a StartDate up to 180 days ago for all licenses.
   • For organizations with E5 licenses, allow StartDate up to 365 days ago.

2. Adjust Date Range Validation:

   • Implement logic to detect the organization's licensing level.
     • Use available APIs or cmdlets (e.g., Get-MsolAccountSku, Get-AzureADSubscribedSku) to determine the licenses assigned to the tenant.
   • Based on the detected licensing, set the maximum allowable StartDate:
     • E3 Licenses: Maximum of 180 days ago.
     • E5 Licenses: Maximum of 365 days ago.
   • Update validation to prevent users from specifying StartDate beyond their retention period.
   • Ensure scripts handle date ranges appropriately without errors when querying up to the maximum allowed days.

3. Provide Informative Messages:

   • If users attempt to set a StartDate older than their maximum retention period, display a clear warning or error message.
   • Inform users of the maximum available date range based on their licensing.
   • Example message: "Your organization's audit log retention period is 180 days based on your licensing. Please specify a StartDate within the last 180 days."

4. Allow Advanced Overrides:

   • Provide an option for advanced users to override the default settings if they have extended retention policies or special arrangements.
   • Implement a parameter (e.g., -OverrideRetention) that allows users to specify custom date ranges.
   • Include warnings when overrides are used to ensure users understand the implications and potential for incomplete data.

5. Handle Licensing Detection Gracefully:

   • If the script cannot determine the licensing level (e.g., due to permissions issues), default to the safest option (90 days) and inform the user.
   • Provide guidance on how users can check their licensing manually if automatic detection fails.

6. Update Documentation:

   • Revise script documentation to reflect the new retention periods and licensing considerations.
   • Provide guidance on setting the StartDate parameter based on licensing.
   • Include examples demonstrating how to query logs from different time periods.

7. Test Scripts:

   • Test the updated scripts in environments with different licensing levels (E3, E5).
   • Verify that scripts correctly detect licensing and enforce appropriate date ranges.
   • Ensure that scripts handle date ranges correctly and do not produce errors.

8. Optimize Performance:

   • Consider the impact of querying larger date ranges on performance.
   • Implement logic to handle larger datasets efficiently (e.g., batching, pagination).

9. Communicate Changes to Users:

   • Include information about the update in release notes.
   • Advise users to update their Hawk installation to access logs up to their maximum retention period.

Acceptance Criteria

• Hawk scripts support parsing audit logs up to 180 days for all users and up to 365 days for E5 licensed organizations.
• Scripts default to a StartDate of 90 days ago but allow users to specify longer date ranges based on their licensing.
• Scripts automatically detect the organization's licensing level and adjust the maximum allowable date range accordingly.
• Users receive clear notifications if their queries exceed their available data retention period.
• Advanced users can override default settings if they have extended retention policies.
• If a StartDate older than the maximum allowed is specified, the script provides a clear error message.
• Documentation is updated to guide users on the new capabilities and limitations.
• Scripts are tested and verified to function correctly with the extended date ranges.
• No errors occur due to the extended date range when running the scripts.

---

Additional Notes:

• Testing:

  • Test scripts in environments with both E3 and E5 licenses to validate behavior.
  • Simulate scenarios where licensing detection fails to ensure scripts handle it gracefully.

• Dependencies:

  • Ensure compatibility with the latest Microsoft 365 audit log APIs.
  • Verify that necessary permissions are available to detect licensing and access audit logs up to the allowed retention period.

[jonnybottles]

https://learn.microsoft.com/en-us/purview/audit-log-retention-policies?tabs=microsoft-purview-portal

[jonnybottles]

This ticket, ticket154 has dependencies on several other tickets because they all deal with audit log access and need to work together coherently. Here are the specific dependencies:
Direct Dependencies:

#147 (Update Search-HawkTenantEXOAuditLog.ps1)
#148 (Update Get-HawkUserAdminAudit.ps1)
#149 (Update Get-HawkUserMailboxAuditing.ps1)

Reasons for Dependencies:

The retention period changes in #154 need to be implemented after these scripts are updated to use Search-UnifiedAuditLog because:

All these scripts access audit logs and need consistent date handling
The licensing detection for retention periods needs to work with the new UnifiedAuditLog cmdlets
Error handling and date validation need to be coordinated across all audit log access

Not Direct Dependencies:

#146 (Update Get-HawkTenantRbacChanges.ps1)
#150 (Update Get-HawkTenantEDiscoveryConfiguration.ps1)
#152 (Update Get-SimpleAdminAuditLog parsing)

While these tickets are part of the broader audit log modernization effort, they don't directly impact the retention period functionality as they deal with different aspects of auditing or different data types.
The most efficient sequence would be:

Implement #147, #148, #149 to update the core audit log access
Then implement #154 to add the retention period handling on top of the modernized scripts
The remaining tickets can be implemented in parallel as they don't directly affect retention periods