DC-4: Collect Graph Activity Logs

[jonnybottles]

What problem would this feature solve?

In April 2024, Microsoft enabled Graph activity logs, providing investigators with deeper insight into Graph API usage within their tenant. These logs offer critical visibility into API operations that was previously unavailable, enhancing the ability to detect and investigate potential malicious activity.

Proposed Solution

First, implement the collection of critical key operation audit logs that were added following the 2023 Microsoft Entra ID signing key compromise. These security-critical logs include:

• Key rotation events
• Key creation events
• Key invalidation events

Additionally, enhance Graph activity log collection based on @T0pCyber's upcoming requirements for other investigative log types. These additional logs will focus on general Graph API activity to help identify suspicious behavior patterns but will be separate from the key operation logs outlined above.

---

⚙️ Developer Section (For Hawk Team Members Only)

Technical Requirements

Graph API Log Collection:

• Implement key operation log collection for:
  • Key rotation events
  • Key creation events
  • Key invalidation events
• Design an extensible framework to easily add other Graph activity logs.
• Handle the new Graph API authentication flow.
• Process nested operation details within the API responses.

Data Export Requirements:

• Export logs in both CSV and JSON formats.
• Include full operation details in the export, including:
  • Actor
  • Timestamp
  • Operation metadata
• Flag suspicious patterns and high-risk operations.
• Separate key operation logs from other activity logs in the export output.

Log Processing:

• Handle pagination for large result sets from the Graph API.
• Map API operations to human-readable descriptions.
• Extract relevant actors and targets from the log data.
• Identify and flag high-risk operation patterns.

---

Implementation Approach

1. Create New Function: Get-HawkGraphActivityLog

   • Implement core functionality for collecting Graph activity logs.
   • Process the API response data to extract relevant information.
   • Export the findings in both CSV and JSON formats.
   • Design the function for easy extensibility to support additional log types in the future.

2. Integration Points:

   • Add the new log collection to the existing tenant investigation workflow.
   • Integrate with Hawk’s existing logging framework.
   • Ensure proper error handling is in place to avoid disruptions.
   • Update the Hawk help documentation to include new capabilities.

3. Future Extensibility:

   • Structure the code to allow for the easy addition of new log types as needed.
   • Prepare the framework for the additional log type requirements from @T0pCyber.
   • Allow configuration of the collection scope (e.g., time ranges, specific operations).

---

Acceptance Criteria

• Successfully retrieves all key operation logs from the Microsoft Graph API.
• Export format matches existing Hawk standards for consistency.
• Suspicious operations and high-risk patterns are clearly flagged in the output.
• Documentation is updated to reflect the new log collection capabilities.
• The framework is ready to support additional log types without major refactoring.
• Proper error handling is implemented for scenarios such as missing permissions.
• There is a clear separation between key operation logs and other activity logs in the output.
• Help documentation provides clear instructions on using the new log collection feature.

---

Dependencies

• Microsoft Graph API permissions: Ensure proper permissions are granted to access key operation and activity logs.
• Graph API authentication implementation: Verify that Hawk’s existing authentication flow supports the new log collection.
• Requirements from @T0pCyber: Await additional log type requirements to finalize implementation.

---

Notes

• Awaiting additional Graph activity log requirements from @T0pCyber.
• Consider the performance impact of retrieving multiple log types in a single investigation run.
• May need to produce separate output files for different log categories to keep results organized.
• Add a detailed explanation of the different log types and their significance in the documentation.