Feature: Add IP Geolocation Lookup to Get-HawkUserEntraIDSignInLog Function

[jonnybottles]

What problem would this feature solve?

Currently, Get-HawkUserEntraIDSignInLog retrieves sign-in logs from Microsoft Entra ID but does not provide IP geolocation information for the sign-in events. This makes it harder for security analysts to:

• Quickly identify suspicious login locations
• Detect potential geographic-based authentication anomalies
• Compare sign-in patterns across different geographical regions
• Group and analyze access patterns by country/region

The existing Get-HawkUserUALSignInLog function already provides this capability through IP geolocation lookups, but this functionality needs to be extended to the newer Entra ID sign-in log retrieval function to maintain feature parity and provide consistent analysis capabilities across both methods.

---

Proposed Solution

Enhance Get-HawkUserEntraIDSignInLog to:

1. Add a -ResolveIPLocations switch parameter to match Get-HawkUserUALSignInLog functionality.
2. Utilize the existing Get-IPGeolocation internal function to lookup location data for each unique IP address.
3. Add location data (country, region, city) to the output objects.
4. Mark Microsoft-owned IP addresses using the Test-MicrosoftIP function.
5. Export the enhanced data in both CSV and JSON formats with the additional geolocation fields.

The function should maintain the existing error handling and output formatting while adding the new geolocation capabilities.

---

Technical Requirements

1. Add ResolveIPLocations switch parameter

2. Reuse existing internal functions:

   • Get-IPGeolocation for location lookups.
   • Test-MicrosoftIP for Microsoft IP detection.
   • IPlocationCache global variable for caching.

3. Add new properties to output objects:

   • CountryName
   • RegionCode
   • RegionName
   • City
   • KnownMicrosoftIP

4. Handle null/invalid IP addresses gracefully.

5. Maintain existing performance optimization techniques like IP caching.

6. Ensure proper error handling for geolocation service failures.

---

Implementation Approach

1. Update function parameter block to include ResolveIPLocations switch. ```

2. Reuse existing caching mechanism to prevent duplicate lookups.

3. Add documentation for the new parameter and functionality.

4. Update output formatting to include new location fields.

---

Acceptance Criteria

1. Function accepts -ResolveIPLocations switch parameter.
2. IP addresses are correctly resolved to geographic locations.
3. Microsoft IPs are properly identified.
4. Location data is correctly added to output objects.
5. IP location caching works as expected.
6. Performance remains acceptable with geolocation enabled.
7. Output files contain all geolocation fields.
8. Error handling properly manages geolocation service failures.
9. Documentation is updated to reflect new functionality.
10. Unit tests cover new geolocation functionality.