How and when to use Nexthink remote actions

What is Nexthink?

The Nexthink platform collects rich data from the end user. For example, it collects events, such as high CPU consumption, application crashes and network responses, which are useful to understand possible issues on a device.

Nexthink also incorporates PowerShell into its platform as remote actions. Additionally, Nexthink provides PowerShell scripts as part of libraries that can be used quickly without the need to write new scripts.

PowerShell at scale

With Nexthink, administrators can run a PowerShell script instantly on every Windows device in their enterprise and receive output from that script to store in a database.

Scripts can run manually, on an automated schedule -- hourly, every few hours, daily, weekly, etc. -- or be invoked via the Nexthink Remote Action API. This flexibility increases the possible use cases for PowerShell in Nexthink.

Collecting data or remediation

The Nexthink platform is focused on data -- collection, storage and analysis -- as well as how to use that data to resolve issues at scale.

Devices in a Nexthink environment have the Nexthink Collector agent installed automatically to collect a wide variety of data that is stored in the Nexthink engine. However, PowerShell is another method for custom data collection. Generally, the purpose of a PowerShell script is to either collect data and send output to an engine or to remediate an issue on a device.

How to write a PowerShell script in Nexthink

Writing a Nexthink PowerShell script is not much different than any other PowerShell script, with a few exceptions:

1. IT admins must save the PowerShell script with UTF-8 BOM -- where BOM stands for byte order mark, a sequence of bytes preceding a string of text that indicates to the reader that the proceeding text is encoded in UTF-8.
2. The second -- and more interesting -- difference is that to store output of the script on a Nexthink engine requires adding a Nexthink assembly in the script.

In this code example below, we add the remote action to Microsoft's dynamic link library (DLL). To further simplify, use the environment variable $env:NEXTHINK.

function Add-NexthinkDLL {
    $remoteActionPath = "$env:NEXTHINK\RemoteActions\nxtremoteactions.dll"
    if (-not (Test-Path -Path $remoteActionPath)) { throw 'Nexthink DLL nxtremoteactions.dll not found. ' }
    Add-Type -Path $remoteActionPath
}
Add-NexthinkDLL

To send the output to the engine, call a method such as the command below, which sends a string output to the engine for whichever device runs the script. Set the arguments as the name of the field first (Test) and then the value to be stored in the field (Hello).

[Nxt]::WriteOutputString('Test', 'Hello')

PowerShell scripts can run either in the context of the currently logged-on user or as the SYSTEM account. This is suitable for instances whereupon IT admins must interact with the active user's environment -- but also in administrative task use cases, such as installing software for which the user account lacks authorization.

Example data collection script

One use case for Nexthink-managed device data collection is investigating whether a device caches its user's credentials. This is a common configuration, especially for laptops and remote workers, as it enables a user to log on to a home device without the need to authenticate directly to Active Directory.

In this code snippet below, we use PowerShell to obtain the value of the CachedLogonsCount registry key. If the value is 0, this means users are unable to log on remotely; if it's greater than 1, they are able.

function Get-CachedValue {
    $Path = 'HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon'
    $Key = 'CachedLogonsCount'
    $RegValue = Get-ItemProperty -Path $Path -Name $Key -ErrorAction Stop | Select-Object -ExpandProperty $Key
    if ($RegValue -eq "0"){
        [Nxt]::WriteOutputString('State','Cached credentials is disabled')
    }
    elseif ($RegValue -gt 0) {
        [Nxt]::WriteOutputString('State','Cached credentials is enabled')
    }
}
 
Get-CachedValue

After running this script on multiple devices, Nexthink administrators cannot query devices for this value in the Nexthink Finder application. Nexthink Finder is a Windows application for Nexthink environment management.

Example remediation script

In this next use case for Nexthink remote actions, we set the same registry key collected in the previous script. If, for example, a device has been stolen and IT must disable a domain user from logging on, they can use Nexthink and PowerShell to set that same registry key to 0. This effectively stops any domain user from logging in outside of the corporate network. Use the Set-ItemProperty cmdlet in the script. This script, and the previous one, must run in the SYSTEM context in Nexthink because they change a secured registry value.

function Set-CachedValue {
    $Path = 'HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon'
    $Key = 'CachedLogonsCount'
    $Value = '0'
        Set-ItemProperty -Path $Path -Name $Key -Value $Value -ErrorAction Stop -Verbose
}
Set-CachedValue