DC-2: Expand M365 Log Collection

[jonnybottles]

What problem would this feature solve?

Currently, Hawk is not collecting several critical M365 log types that provide important investigative context. Adding the collection of these logs will enhance investigators' ability to understand user and system activity during incidents.

Proposed Solution

Implement the collection of the following additional log types using Search-UnifiedAuditLog:

• MailItemsAccessed: Track when mailbox items are accessed.
• SearchQueryInitiatedExchange: Track searches performed in Exchange.
• SearchQueryInitiatedSharePoint: Track searches performed in SharePoint.
• Send: Track message sending activity.

@T0pCyber input needed: Should these logs be collected for both Start-HawkTenantInvestigation and Start-HawkUserInvestigation, or just one of these commands?

---

⚙️ Developer Section (For Hawk Team Members Only)

Technical Requirements

Create Separate Functions for Each Log Type:

• Get-HawkMailItemsAccessed
• Get-HawkExchangeSearchQuery
• Get-HawkSharePointSearchQuery
• Get-HawkMailSendActivity

Each function should:

• Use Search-UnifiedAuditLog with the appropriate operation filters.
• Handle pagination for large result sets.
• Export results in a consistent format (both CSV and JSON).
• Flag suspicious patterns or high-risk activity.

---

Output Requirements:

• Separate CSV/JSON files for each log type.
• Standard Hawk output formatting.
• Clear and accurate activity timestamps.
• Include relevant actor information (e.g., user who performed the action).

---

Implementation Approach

1. Create Base Log Collection Framework:

   • Implement common pagination handling to efficiently process large datasets.
   • Use shared output formatting to maintain consistency across all log types.
   • Ensure consistent error handling to avoid process interruptions.
   • Implement reusable logic for detecting and flagging suspicious activity.

2. Implement Individual Collection Functions:

   • Each function will focus on a specific log type.
   • Include custom processing to handle type-specific data and metadata extraction.
   • Implement type-specific detection rules for identifying suspicious patterns.
   • Provide individual help documentation for each new function.

3. Integration:

   • Add the new log collection functions to the investigation workflow (pending input from @T0pCyber on scope).
   • Update the master documentation to include details on the new log types.
   • Include progress indicators during investigations to show log collection status.
   • Add the new functions to the Hawk help system for user reference.

---

Acceptance Criteria

• All four log types are successfully collected from Search-UnifiedAuditLog.
• Each log type has a dedicated function (Get-HawkMailItemsAccessed, Get-HawkExchangeSearchQuery, etc.).
• Output is consistently formatted across all log types in both CSV and JSON formats.
• Proper error handling is implemented for each function.
• Clear documentation is provided for each new log collection capability.
• Pagination handling is efficient and optimized for large datasets.
• Suspicious activity is correctly flagged in the output.
• Performance testing is completed to ensure scalability.
• The implementation scope is confirmed by @T0pCyber.

---

Dependencies

• Access to Search-UnifiedAuditLog: Ensure the necessary permissions are granted to retrieve M365 logs.
• Existing Hawk Output Framework: Maintain consistency with the current Hawk export formatting.
• @T0pCyber's Input: Confirm the implementation scope (whether the logs should be collected for both tenant and user investigations).

---

Notes

• Await @T0pCyber's decision on whether to implement log collection for both Start-HawkTenantInvestigation and Start-HawkUserInvestigation.
• Consider the performance impact of additional log collection on large tenants.
• Adjust the time window handling if necessary to optimize log retrieval.
• Consider adding severity ratings to flagged suspicious activities for better prioritization.