T0pCyber · dcodev1702 · Jan 18, 2025 · Jan 18, 2025 · Jan 19, 2025 · Jan 19, 2025
diff --git a/Hawk/Hawk.psd1 b/Hawk/Hawk.psd1
@@ -3,7 +3,7 @@
 	RootModule         = 'Hawk.psm1'
 
 	# Version number of this module.
-	ModuleVersion      = '4.0'
+	ModuleVersion      = '4.0.1'
 
 	# ID used to uniquely identify this module
 	GUID               = '1f6b6b91-79c4-4edf-83a1-66d2dc8c3d85'

diff --git a/Hawk/changelog.md b/Hawk/changelog.md
@@ -89,7 +89,7 @@
 - Updated Change Log URI.
 - Removed improperly formatted JSON from Get-HawkTenantAdminInboxRuleHistory, Get-HawkTenantAdminInboxRuleRemoval, Get-HawkTenantRBACChange, Get-HawkUserAdminAudit, Search-HawkTenantEXOAuditLog
 
-## 4.0 (2025-2-XX)
+## 4.0 (2025-2-23)
 
 - Implemented UTC timestamps to avoid using local timestamps
 - Implemented PROMPT tag to display to screen when prompting user
@@ -106,3 +106,8 @@
 - Implemented check to verify that an Exchange operation is enabled for auditing before attempting to pull logs
 - Added log pull of user Send activity to the User Investigation (Get-HawkUserMailSendActivity)
 - Added log pull of user SharePoint Search activity to the User Investigation (Get-HawkUserSharePointSearchQuery)
+
+## 4.0.1 (2025-3-0X)
+- Fixed bug in Get-IPGeolocation where API Keys from ipstack.com were not validated
+- Fixed bug in Get-IPGeolocation where API Keys were not validated to meet basic sanity checks/requirements
+- Added commandline agrument '-EnableGeoIPLocation' to Start-HawkUserInvestigation providing the ability to skip interactive prompts when conducting investigations.
diff --git a/Hawk/debug.ps1 b/Hawk/debug.ps1
@@ -0,0 +1,2 @@
+Import-Module "C:\Users\Lorenzo\hawk\Hawk\Hawk.psd1"
+Start-HawkUserInvestigation -UserPrincipalName irelandl@semperhunt.onmicrosoft.com -DaysToLookBack 60 -FilePath C:\Temp
diff --git a/Hawk/functions/Tenant/Get-HawkTenantRiskyServicePrincipals.ps1 b/Hawk/functions/Tenant/Get-HawkTenantRiskyServicePrincipals.ps1
@@ -65,14 +65,14 @@ Function Get-HawkTenantRiskyServicePrincipals {
         Send-AIEvent -Event "CmdRun"
 
         # Check for required license
-        $licenseCheck = Test-EntraWorkloadIDPremium
-        if (-not $licenseCheck.HasLicense) {
-            Out-LogFile "Entra Workload ID Premium license not found" -isWarning
-            Out-LogFile "No Entra Workload ID Premium capable licenses found." -Information
-            Out-LogFile "Required licenses: AAD_PREMIUM_P2, ENTERPRISEPREMIUM, SPE_E5, IDENTITY_THREAT_PROTECTION" -Information
-            Out-LogFile "The service principal risk detection requires one of these licenses to function" -Information
-            return
-        }
+        # $licenseCheck = Test-EntraWorkloadIDPremium
+        # if (-not $licenseCheck.HasLicense) {
+        #     Out-LogFile "Entra Workload ID Premium license not found" -isWarning
+        #     Out-LogFile "No Entra Workload ID Premium capable licenses found." -Information
+        #     Out-LogFile "Required licenses: AAD_PREMIUM_P2, ENTERPRISEPREMIUM, SPE_E5, IDENTITY_THREAT_PROTECTION" -Information
+        #     Out-LogFile "The service principal risk detection requires one of these licenses to function" -Information
+        #     return
+            # }
 
         Out-LogFile "Retrieving risky service principals from Microsoft Entra ID" -Action
 

diff --git a/Hawk/functions/Tenant/Start-HawkTenantInvestigation.ps1 b/Hawk/functions/Tenant/Start-HawkTenantInvestigation.ps1
@@ -195,7 +195,7 @@
         	Out-LogFile "Running Get-HawkTenantRBACChange" -action
         	Get-HawkTenantRBACChange
         }
-
+    
         if ($PSCmdlet.ShouldProcess("Entra ID Audit Log", "Get Entra ID audit logs")) {
         	Out-LogFile "Running Get-HawkTenantEntraIDAuditLog" -action
         	Get-HawkTenantEntraIDAuditLog
@@ -247,6 +247,4 @@
         $investigationEndTime = Get-Date
         Write-HawkInvestigationSummary -StartTime $investigationStartTime -EndTime $investigationEndTime -InvestigationType 'Tenant'
     }
-
-
 }
diff --git a/Hawk/functions/User/Get-HawkUserUALSignInLog.ps1 b/Hawk/functions/User/Get-HawkUserUALSignInLog.ps1
@@ -13,6 +13,8 @@
     Single UPN of a user, comma seperated list of UPNs, or array of objects that contain UPNs.
 .PARAMETER ResolveIPLocations
     Resolved IP Locations
+
+    If this option is specified, it will attempt to resolve IP locations (GeoIP) using ipstack.com API (API Key Required)
 .OUTPUTS
 
     File: Converted_Authentication_Logs.csv
@@ -100,26 +102,31 @@
             }
 
 
-            # Add IP Geo Location information to the data
-            if ($ResolveIPLocations) {
-                Out-File "Resolving IP Locations"
+            # Add Geo IP location information to the data
+            if ($PSBoundParameters.ContainsKey('ResolveIPLocations')) {
+                Out-LogFile "Attemping to resolve IP Locations" -Information
                 # Setup our counter
                 $i = 0
 
-                # Loop thru each connection and get the location
+                # Conduct IPStack API Key validation (once) so the API Key can be passed to Get-IPGeolocation
+                # Get-IPStackAPIKey either returns a valid API key or null
+                $AccessKey = Get-IPStackAPIKey
+
+                # Loop thru each connection and get the Geo IP location
                 while ($i -lt $ExpandedUserLogonLogs.Count) {
 
                     if ([bool]($i % 25)) { }
-                    Else {
-                        Write-Progress -Activity "Looking Up Ip Address Locations" -CurrentOperation $i -PercentComplete (($i / $ExpandedUserLogonLogs.count) * 100)
+                    else {
+                        Write-Progress -Activity "Looking Up IP Address Locations" -CurrentOperation $i -PercentComplete (($i / $ExpandedUserLogonLogs.count) * 100)
                     }
 
                     # Get the location information for this IP address
-                    if($ExpandedUserLogonLogs.item($i).clientip){
-                    $Location = Get-IPGeolocation -ipaddress $ExpandedUserLogonLogs.item($i).clientip
+                    # Need to perform access key value only once instead of for each IP address
+                    if($ExpandedUserLogonLogs.item($i).clientip -and ([string]::IsNullOrEmpty($AccessKey) -eq $false)) {
+                        $Location = Get-IPGeoLocation -IPAddress $ExpandedUserLogonLogs.item($i).clientip -AccessKey $AccessKey
                     }
                     else {
-                        $Location = "IP Address Null"
+                        $Location = "Lack valid REST API key or IP address was not found"
                     }
 
                     # Combine the connection object and the location object so that we have a single output ready
@@ -129,7 +136,7 @@
                     $i++
                 }
 
-                Write-Progress -Completed -Activity "Looking Up Ip Address Locations" -Status " "
+                Write-Progress -Completed -Activity "Looking Up IP Address Locations" -Status " "
             }
             else {
                 Out-LogFile "ResolveIPLocations not specified" -Information
@@ -144,6 +151,4 @@
 
         }
     }
-
-
 }
diff --git a/Hawk/functions/User/Start-HawkUserInvestigation.ps1 b/Hawk/functions/User/Start-HawkUserInvestigation.ps1
@@ -61,6 +61,13 @@
     .PARAMETER WhatIf
         Shows what would happen if the command runs. The command is not executed.
         Use this parameter to understand which investigation steps would be performed without actually collecting data.
+
+	.PARAMETER EnableGeoIPLocation
+		Switch to enable resolving IP addresses to geographic locations in the investigation.
+		This option requires an active internet connection and may increase the time needed to complete the investigation.
+		Providing this parameter automatically enables non-interactive mode.
+
+		REQUIRED: An API key from ipstack.com is required to use this feature.
 
     .OUTPUTS
         Creates multiple CSV and JSON files containing investigation results.
@@ -97,12 +104,12 @@
 	param (
 		[Parameter(Mandatory = $true)]
 		[array]$UserPrincipalName,
-
 		[DateTime]$StartDate,
 		[DateTime]$EndDate,
 		[int]$DaysToLookBack,
 		[string]$FilePath,
-		[switch]$SkipUpdate
+		[switch]$SkipUpdate,
+		[switch]$EnableGeoIPLocation
 	)
 
 	begin {
@@ -125,9 +132,17 @@
 			}
 
 			try {
-				Initialize-HawkGlobalObject -StartDate $StartDate -EndDate $EndDate `
-					-DaysToLookBack $DaysToLookBack -FilePath $FilePath `
-					-SkipUpdate:$SkipUpdate -NonInteractive:$NonInteractive
+				# Call Initialize-HawkGlobalObject in case of non-interactive mode
+				if ($PSBoundParameters.ContainsKey('EnableGeoIPLocation')) {
+					Initialize-HawkGlobalObject -StartDate $StartDate -EndDate $EndDate `
+						-DaysToLookBack $DaysToLookBack -FilePath $FilePath `
+						-SkipUpdate:$SkipUpdate -NonInteractive:$NonInteractive -EnableGeoIPLocation:$EnableGeoIPLocation
+				} else {
+					# Call Initialize-HawkGlobalObject in case of interactive mode for EnableGeoIPLocation	
+					Initialize-HawkGlobalObject -StartDate $StartDate -EndDate $EndDate `
+						-DaysToLookBack $DaysToLookBack -FilePath $FilePath `
+						-SkipUpdate:$SkipUpdate -NonInteractive:$NonInteractive
+				}
 			}
 			catch {
 				Stop-PSFFunction -Message "Failed to initialize Hawk: $_" -EnableException $true
@@ -138,8 +153,18 @@
 	process {
 		if (Test-PSFFunctionInterrupt) { return }
 
+		# Be sure to remove comments after testing!
+		#if ($PSBoundParameters.ContainsKey('EnableGeoIPLocation')) {
+		#	Initialize-HawkGlobalObject -EnableGeoIPLocation
+		#	Out-LogFile "START-HAWKUSERINVESTIGATION -> Calling Initialize-HawkGlobalObject with EnableGeoIPLocation" -Information
+		#} else {
+		#	Initialize-HawkGlobalObject
+		#	Out-LogFile "START-HAWKUSERINVESTIGATION -> Calling Initialize-HawkGlobalObject without EnableGeoIPLocation" -Information
+		#}
+
 		# Check if Hawk object exists and is fully initialized
 		if (Test-HawkGlobalObject) {
+			#Out-LogFile "START-USERINVESTIGATION::Test-HawkGlobalOjbect evaluated to TRUE!" -Information
 			Initialize-HawkGlobalObject
 		}
 		$investigationStartTime = Get-Date
@@ -156,6 +181,7 @@
 			foreach ($Object in $UserArray) {
 				[string]$User = $Object.UserPrincipalName
 
+				<#
 				if ($PSCmdlet.ShouldProcess("Running Get-HawkUserConfiguration for $User")) {
 					Out-LogFile "Running Get-HawkUserConfiguration" -Action
 					Get-HawkUserConfiguration -User $User
@@ -180,12 +206,21 @@
 					Out-LogFile "Running Get-HawkUserEntraIDSignInLog" -Action
 					Get-HawkUserEntraIDSignInLog -UserPrincipalName $User
 				}
-
+				#>
 				if ($PSCmdlet.ShouldProcess("Running Get-HawkUserUALSignInLog for $User")) {
-					Out-LogFile "Running Get-HawkUserUALSignInLog" -Action
-					Get-HawkUserUALSignInLog -User $User -ResolveIPLocations
+					# Two different use cases (interactive and non-interactive) have to be considered here
+					# $Hawk.EnableGeoIPLocation is to account for interactive mode
+					# $PSBoundParameters.ContainsKey('EnableGeoIPLocation') is to account for non-interactive mode
+					if ($Hawk.EnableGeoIPLocation -or $PSBoundParameters.ContainsKey('EnableGeoIPLocation')) {
+						Out-LogFile "Running Get-HawkUserUALSignInLog and resolving IP locations" -Action
+						Get-HawkUserUALSignInLog -User $User -ResolveIPLocations
+					} else {
+						Out-LogFile "Running Get-HawkUserUALSignInLog without resolving IP locations" -Action
+						Get-HawkUserUALSignInLog -User $User
+					}
 				}
 
+				<#
 				if ($PSCmdlet.ShouldProcess("Running Get-HawkUserMailboxAuditing for $User")) {
 					Out-LogFile "Running Get-HawkUserMailboxAuditing" -Action
 					Get-HawkUserMailboxAuditing -User $User
@@ -224,6 +259,7 @@
 					Out-LogFile "Running Get-HawkUserMobileDevice" -Action
 					Get-HawkUserMobileDevice -User $User
 				}
+				#>
 
 			}
 		}

diff --git a/Hawk/internal/functions/Add-HawkAppData.ps1 b/Hawk/internal/functions/Add-HawkAppData.ps1
@@ -24,11 +24,11 @@ Function Add-HawkAppData {
         [string]$Value
     )
 
-    Out-LogFile ("Adding " + $value + " to " + $Name + " in HawkAppData") -Action
+    Out-LogFile ("Adding `"$Value`"  to `"$Name`" in HawkAppData") -Action
 
     # Test if our HawkAppData variable exists
     if ([bool](get-variable HawkAppData -ErrorAction SilentlyContinue)) {
-        $global:HawkAppData | Add-Member -MemberType NoteProperty -Name $Name -Value $Value
+        $global:HawkAppData | Add-Member -MemberType NoteProperty -Name $Name -Value $Value -Force
     }
     else {
         $global:HawkAppData = New-Object -TypeName PSObject

diff --git a/Hawk/internal/functions/Get-IPGeoLocation.ps1 b/Hawk/internal/functions/Get-IPGeoLocation.ps1
@@ -0,0 +1,88 @@
+<#
+.SYNOPSIS
+    Get-IPGeoLocation is called by Get-HawkUserUALSignInLog to resolve IP addresses to geolocation data.
+    An IP address and IP Stack API Key is passed to the function, as it returns a PSCustomObject with the geolocation data.
+
+.DESCRIPTION
+    Get the Geographic Location of an IP address using the ipstack.com REST API
+.PARAMETER IPAddress
+    IP address to look up for its geographic location
+.PARAMETER AccessKey
+    Access key for ipstack.com's REST API
+.EXAMPLE
+    Get-IPGeoLocation -IPAddress 8.8.8.8 -AccessKey e904134b5cbb91f752a79f3ba9cbe59a
+    Gets all IP GeoLocation data of IPs that recieved
+.NOTES
+    General notes
+#>
+function Get-IPGeoLocation {
+    [CmdletBinding()]
+    param (
+        [Parameter(Mandatory = $true)]
+        [string]$IPAddress,
+
+        [Parameter(Mandatory = $true)]
+        [string]$AccessKey
+    )
+
+    begin {}
+
+    process {
+        try {
+
+            if ($IPAddress -eq "<null>") {
+                Write-Verbose "Null IP Provided: $IPAddress"
+                return [PSCustomObject]@{
+                    IP               = $IPAddress
+                    CountryName      = "NULL IP"
+                    RegionName       = "Unknown"
+                    RegionCode       = "Unknown"
+                    ContinentName    = "Unknown"
+                    City             = "Unknown"
+                    KnownMicrosoftIP = "Unknown"
+                }
+            }
+
+            # Check cache
+            if ($Global:IPLocationCache.ip -contains $IPAddress) {
+                Write-Verbose "IP Cache Hit: $IPAddress"
+                return ($Global:IPLocationCache | Where-Object { $_.ip -eq $IPAddress })
+            }
+
+            # Make API calls to IP Stack to look up IP addresses
+            $resource = "http://api.ipstack.com/$($IPAddress)?access_key=$AccessKey"
+            $geoip = Invoke-RestMethod -Method Get -URI $resource -ErrorAction Stop
+            $geoip | ConvertTo-Json -Depth 10
+
+            # Create result object
+            Write-Output "`n"
+            $isMSFTIP = Test-MicrosoftIP -IPToTest $geoip.ip -Type $geoip.type
+            $result = [PSCustomObject]@{
+                IP               = $geoip.ip
+                CountryName      = $geoip.country_name
+                ContinentName    = $geoip.continent_name
+                RegionName       = $geoip.region_name
+                RegionCode       = $geoip.region_code
+                City             = $geoip.city
+                KnownMicrosoftIP = $isMSFTIP
+            }
+
+            # Update cache
+            [array]$Global:IPLocationCache += $result
+
+            return $result
+        }
+        catch {
+            Out-LogFile "Failed to retrieve location for IP $IPAddress : $_" -isError
+            return [PSCustomObject]@{
+                IP               = $IPAddress
+                CountryName      = "Failed to Resolve"
+                RegionName       = "Unknown"
+                RegionCode       = "Unknown"
+                ContinentName    = "Unknown"
+                City             = "Unknown"
+                KnownMicrosoftIP = "Unknown"
+            }
+        }
+    }
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		Import-Module "C:\Users\Lorenzo\hawk\Hawk\Hawk.psd1"
		Start-HawkUserInvestigation -UserPrincipalName irelandl@semperhunt.onmicrosoft.com -DaysToLookBack 60 -FilePath C:\Temp