Utilizzare PowerShell per tracciare la posizione di un dispositivo tramite l’API GeoLocation di Google

Punti chiave

• Lo script traccia la posizione geografica di un dispositivo utilizzando l’API GeoLocation di Google.
• È stato progettato per aggiornare i campi personalizzati di NinjaOne con i dati relativi alla posizione.
• Lo script per tracciare la posizione di un dispositivo richiede una connessione Internet attiva ed è ottimizzato per i dispositivi Windows 10.
• L’API GeoLocation di Google offre una maggiore precisione e una copertura più ampia rispetto ad altri metodi.
• L’uso dello script per tracciare la posizione di un dispositivo solleva problemi etici e di privacy.
• Per evitare violazioni della privacy, è necessario ottenere autorizzazioni esplicite prima di utilizzare questo strumento.
• La comprensione dei limiti legati alle ricerche effettuabili per intervallo di tempo, e dei costi associati, quando si usa l’API di Google è fondamentale.
• NinjaOne, in combinazione con script come questo, offre solide funzionalità per le operazioni IT e la gestione delle risorse.

Nell’odierno ecosistema informatico interconnesso, una delle informazioni più preziose è la “posizione”. La capacità di tracciare la posizione geografica dei dispositivi può rivelarsi cruciale in molte operazioni IT, dalla gestione delle risorse al monitoraggio della sicurezza. Questo post del blog analizza uno script PowerShell che consente ai professionisti IT e agli MSP (Managed Service Provider) di tracciare la posizione di un dispositivo Windows e di memorizzarla utilizzando i campi personalizzati di NinjaOne.

Background

Lo script per tracciare la posizione di un dispositivo in questione aggiorna i campi personalizzati con le coordinate geografiche e l’indirizzo di un dispositivo, utilizzando l’API GeoLocation di Google. Per i professionisti IT e gli MSP, conoscere la posizione fisica di un dispositivo è fondamentale. Che si tratti di tracciare apparecchiature rubate, di controllare i dispositivi o di verificare la distribuzione geografica delle risorse IT, le applicazioni di questo script per tracciare la posizione di un dispositivo possono essere varie e profonde.

Lo script per tracciare la posizione di un dispositivo

#Requires -Version 5.1

<#
.SYNOPSIS
    Updates Custom Fields with the location of a device based on the Google GeoLocation API.
.DESCRIPTION
    Updates Custom Fields with the location of a device based on the Google GeoLocation API.

    The CustomFieldName parameter can be used to specify which custom field to save the Latitude and Longitude coordinates to.
    The AddressCustomFieldName parameter can be used to specify which custom field to save the address to.

    This script requires a custom field to save location data in NinjaRMM.
    The default for CustomFieldName is "Location".
    The default for AddressCustomFieldName is "Address".
    You can use any text custom field that you wish.
.EXAMPLE
    -GoogleApiKey "<GeoLocation API key here>"
    Saves the Latitude and Longitude coordinates to the custom field named Location.
.EXAMPLE
    -GoogleApiKey "<GeoLocation API key here>" -CustomFieldName "Location" -AddressCustomFieldName "Address"
    Saves the Latitude and Longitude coordinates to the custom field named Location as well as the address to Address.
.INPUTS
    None
.OUTPUTS
    None
.NOTES
    Minimum OS Architecture Supported: Windows 10
    Release Notes:
    Updated to work with either Parameters or Script Variables
By using this script, you indicate your acceptance of the following legal terms as well as our Terms of Use at https://www.ninjaone.com/terms-of-use.
    Ownership Rights: NinjaOne owns and will continue to own all right, title, and interest in and to the script (including the copyright). NinjaOne is giving you a limited license to use the script in accordance with these legal terms. 
    Use Limitation: You may only use the script for your legitimate personal or internal business purposes, and you may not share the script with another party. 
    Republication Prohibition: Under no circumstances are you permitted to re-publish the script in any script library or website belonging to or under the control of any other software provider. 
    Warranty Disclaimer: The script is provided “as is” and “as available”, without warranty of any kind. NinjaOne makes no promise or guarantee that the script will be free from defects or that it will meet your specific needs or expectations. 
    Assumption of Risk: Your use of the script is at your own risk. You acknowledge that there are certain inherent risks in using the script, and you understand and assume each of those risks. 
    Waiver and Release: You will not hold NinjaOne responsible for any adverse or unintended consequences resulting from your use of the script, and you waive any legal or equitable rights or remedies you may have against NinjaOne relating to your use of the script. 
    EULA: If you are a NinjaOne customer, your use of the script is subject to the End User License Agreement applicable to you (EULA).
#>

[CmdletBinding()]
param (
    [Parameter()]
    [String]
    $GoogleApiKey,
    [Parameter()]
    [String]
    $CustomFieldName = "Location",
    [Parameter()]
    [String]
    $AddressCustomFieldName = "Address"
)

begin {
    function Test-StringEmpty {
        param([string]$Text)
        # Returns true if string is empty, null, or whitespace
        process { [string]::IsNullOrEmpty($Text) -or [string]::IsNullOrWhiteSpace($Text) }
    }
    function Get-NearestCity {
        param (
            [double]$lat,
            [double]$lon,
            [string]$GoogleApi
        )
        try {
            $Response = Invoke-RestMethod -Uri "http://maps.googleapis.com/maps/api/geocode/json?latlng=$lat,$lon&key=$GoogleApi"
        }
        catch {
            throw $Error[0]
        }
        return $Response.results[0].formatted_address
    }
    function Get-WifiNetwork {
        end {
            try {
                netsh.exe wlan sh net mode=bssid | ForEach-Object -Process {
                    if ($_ -match '^SSID (d+) : (.*)$') {
                        $current = @{}
                        $networks += $current
                        $current.Index = $matches[1].trim()
                        $current.SSID = $matches[2].trim()
                    }
                    else {
                        if ($_ -match '^s+(.*)s+:s+(.*)s*$') {
                            $current[$matches[1].trim()] = $matches[2].trim()
                        }
                    }
                } -Begin { $networks = @() } -End { $networks | ForEach-Object { New-Object -TypeName "PSObject" -Property $_ } }    
            }
            catch {
                # return nothing
            }
        }
    }

    # Check if Script Variables are being used
    if (-not $(Test-StringEmpty -Text $env:GoogleApiKey)) {
        $GoogleApiKey = $env:GoogleApiKey
    }
    if (-not $(Test-StringEmpty -Text $env:CustomFieldName)) {
        $CustomFieldName = $env:CustomFieldName
    }
    if (-not $(Test-StringEmpty -Text $env:AddressCustomFieldName)) {
        $AddressCustomFieldName = $env:AddressCustomFieldName
    }
    # Check if api key is set, error if not set
    if ($(Test-StringEmpty -Text $GoogleApiKey)) {
        # Both Parameter and Script Variable are empty
        # Can not combine Parameter "[Parameter(Mandatory)]" and Script Variable Required
        Write-Error "GoogleApiKey is required."
        exit 1
    }

    # Use the system's new line
    $NewLine = $([System.Environment]::NewLine)

    # Build URL with API key
    $Url = "https://www.googleapis.com/geolocation/v1/geolocate?key=$GoogleApiKey"
}
process {
    # Get WIFI network data nearby
    $WiFiData = Get-WifiNetwork |
        Select-Object @{name = 'age'; expression = { 0 } },
        @{name = 'macAddress'; expression = { $_.'BSSID 1' } },
        @{name = 'channel'; expression = { $_.Channel } },
        @{name = 'signalStrength'; expression = { (($_.Signal -replace "%") / 2) - 100 } }

    # Check if we got any number access points
    $Body = if ($WiFiData -and $WiFiData.Count -gt 0) {
        @{
            considerIp       = $true
            wifiAccessPoints = $WiFiData
        } | ConvertTo-Json
    }
    else {
        @{
            considerIp = $true
        } | ConvertTo-Json
    }

    # Get our lat,lng position
    try {
        $Response = Invoke-RestMethod -Method Post -Uri $Url -Body $Body -ContentType "application/json" -ErrorVariable Err
    }
    catch {
        Write-Error $_
        exit 1
    }

    # Save the relevant results to variable that have shorter names
    $Lat = $Response.location.lat
    $Lon = $Response.location.lng

    try {
        # Save Latitude, Longitude to the custom field from the CustomFieldName parameter
        Ninja-Property-Set -Name $CustomFieldName -Value "$Lat,$Lon"
    }
    catch {
        Write-Error "Failed to save to CustomFieldName($CustomFieldName)"
        exit 1
    }

    if ( $(Test-StringEmpty -Text $AddressCustomFieldName) -and $(Test-StringEmpty -Text $env:AddressCustomFieldName)) {
        # Both Parameter and Variable are empty
        Write-Output "$($NewLine)Location: $Lat,$Lon"
    }
    else {
        if ($(Test-StringEmpty -Text $AddressCustomFieldName)) {
            # Parameter was not used
            $AddressCustomFieldName = $env:AddressCustomFieldName
        }

        try {
            # Get City from Google API's
            # Google API: https://developers.google.com/maps/documentation/geocoding/requests-reverse-geocoding
            $Address = Get-NearestCity -lat $Lat -lon $Lon -GoogleApi $GoogleApiKey
        }
        catch {
            Write-Error "Failed to save to get nearest city."
            exit 1
        }

        try {
            # Save Lat and Lon to custom field
            Ninja-Property-Set -Name $AddressCustomFieldName -Value "$Address"
            Write-Output "$($NewLine)Location: $Address`: $Lat,$Lon"
        }
        catch {
            Write-Error "Failed to save to AddressCustomFieldName($AddressCustomFieldName)"
            exit 1
        }
    }
    exit 0
}
end {
    $ScriptVariables = @(
        [PSCustomObject]@{
            name           = "GoogleApiKey"
            calculatedName = "GoogleApiKey"
            required       = $true
            defaultValue   = $null
            valueType      = "TEXT"
            valueList      = $null
            description    = ""
        }
        [PSCustomObject]@{
            name           = "CustomFieldName"
            calculatedName = "CustomFieldName"
            required       = $false
            defaultValue   = [PSCustomObject]@{
                type  = "TEXT"
                value = "Location"
            }
            valueType      = "TEXT"
            valueList      = $null
            description    = ""
        }
    )
}

 

Analisi dettagliata

Lo script per tracciare la posizione di un dispositivo può essere suddiviso in tre parti principali:

• Inizializzazione: Lo script per tracciare la posizione di un dispositivo inizia con la definizione di parametri quali GoogleApiKey, CustomFieldName e AddressCustomFieldName. Questi parametri fungono da input per personalizzare il comportamento dello script.
• Operazioni principali: La parte centrale dello script per tracciare la posizione di un dispositivo prevede:
• Verifica delle reti WiFi disponibili intorno al dispositivo.
• Creazione di un payload con i dati WiFi e invio al servizio di geolocalizzazione di Google per ottenere latitudine e longitudine.
• Recupero della città o dell’indirizzo più vicino utilizzando le coordinate ottenute.
• Aggiornamento dei campi personalizzati in NinjaOne con i dati relativi alla località.
• Operazioni conclusive: Le variabili degli script per tracciare la posizione di un dispositivo vengono inizializzate per memorizzare i dati e aiutare nelle operazioni successive.

Casi d’uso potenziali

Consideriamo un professionista IT, Alex, che lavora per un’azienda. È stato incaricato di controllare tutti i computer portatili in diverse filiali. Utilizzando questo script, Alex può recuperare rapidamente la posizione geografica di ciascun portatile, assicurandosi che i dispositivi si trovino effettivamente nelle sedi dichiarate.

Confronti

L’approccio dello script per tracciare la posizione di un dispositivo sfrutta l’API di Google GeoLocation, che offre dettagli precisi sulla posizione. Le alternative potrebbero essere l’utilizzo dei servizi di localizzazione nativi di Windows o di altre API di terze parti. Tuttavia, la quantità dei dati a disposizione e la solida infrastruttura di Google ne fanno una scelta privilegiata per questi campi di applicazione, perché garantiscono una migliore precisione e una copertura più ampia.

Domande frequenti

• Questo script per tracciare la posizione di un dispositivo funziona anche offline?
  Lo script per tracciare la posizione di un dispositivo richiede una connessione Internet attiva per comunicare con i servizi di Google.
• C’è un limite al numero di richieste di localizzazione?
  L’API GeoLocation di Google prevede dei limiti in base al tipo di account e alla tipologia di fatturazione scelta.
• Lo script per tracciare la posizione di un dispositivo funziona solo su Windows 10?
  Il requisito minimo per il sistema operativo dello script è Windows 10.

Implicazioni

Se da un lato la possibilità di tracciare la posizione di un dispositivo rappresenta un ottimo strumento per la gestione delle risorse e la sicurezza, dall’altro pone problemi di privacy. È fondamentale che i team IT si assicurino che questo strumento sia utilizzato in modo etico, con le dovute autorizzazioni e informando le persone coinvolte. Il tracciamento non autorizzato può portare a violazioni delle leggi e delle normative sulla privacy.

Raccomandazioni

• Fai in modo di avere sempre un’autorizzazione esplicita prima di eseguire questo script per tracciare la posizione di un dispositivo.
• Assicurati di aver compreso i limiti legati al numero di ricerche per intervallo temporale, e i costi associati, quando usi l’API GeoLocation di Google.
• Esamina e verifica regolarmente i log per evitare qualsiasi utilizzo scorretto.

Considerazioni finali

Per gli MSP e i professionisti IT, NinjaOne offre una piattaforma preziosa per centralizzare e ottimizzare le operazioni IT. L’integrazione di uno script come quello per tracciare la posizione di un dispositivo amplifica ulteriormente le capacità di NinjaOne, e lo aiuta a essere uno strumento indispensabile per i moderni ambienti IT. Gli script PowerShell, e in particolare quello descritto sopra, offrono un ulteriore livello di flessibilità e potenza agli utenti di NinjaOne, aiutandoli a tenere il passo in un mondo IT dinamico.