Writing scripts for remote actions on Mac

If you need help performing the operations described in this article, please contact your Nexthink Certified Partner.

This article details the process of preparing Nexthink remote action scripts on Mac. The scripts are written in Bash, a command-line shell and scripting language supported by many UNIX-like operating systems, and then signed with a certificate for security purposes. Bash scripts are suited for automating tasks and configuration management; They allow for remote actions to be run on employee devices.

The main use cases for remote actions are on-demand data collection from devices, self-healing tasks and modifying configuration settings.

The article assumes that the reader is familiar with Bash scripting.

Refer to the Remote actions group in Community documentation for more information.

Creating the script

Generic scripts and input variables

Generic scripts are useful when a digitally signed script requires customization, as modifying a signed script breaks its signature. A generic script can be customized by parameters, keeping the signature intact.

Declare parameters at the beginning of a script for Bash positional parameters and enclose them between two special comments as follows:

# NXT_PARAMETERS_BEGIN
Parameter1=$1
Parameter2=$2
Parameter3=$3
# NXT_PARAMETERS_END

When uploading the script during the remote action configuration, the system takes the parameters between the special Nexthink comments in a Bash script and lists them in the Parameters section below the script text. Provide actual values to the parameters in the text input boxes displayed to the right of each parameter name.

Actual values are always passed to the script as text. If the script declares parameters with a type other than string, ensure that you provide values the script can convert to their expected type.

Creating output variables

Executing a script may generate output that you want to store as on-demand data. Nexthink provides a Bash script (nxt_ra_script_output.sh) that is installed on an employee device at the same time as Collector. The script includes functions to write results to the data layer.

To use the functions in the Nexthink script for remote action output, add the following header at the beginning of your Bash scripts:

#!/bin/bash
. "${NEXTHINK}"/bash/nxt_ra_script_output.sh

All write methods accept two arguments: the name of the output and the value to write. For instance, if you want to return the number of files in a directory to the data layer, the variable nfiles in your script contains that number. To write the value of nfiles through output with the name FileNumber to the data layer, call the function to write unsigned integers:

nxt_write_output_uint32 'FileNumber' $nfiles

The Remote Actions editor recognizes calls to write outputs in the script and lists the output variables in the Outputs section. Set the output's label to indicate how to refer to it in investigations and metrics.

The ending of each write method indicates the type of output. Because Bash is a loosely typed language, the type of output is interpreted depending on the context. The following is a list of available methods:

nxt write method	Constraints
nxt_write_output_string	0 - 1024 characters (output truncated if bigger)
nxt_write_output_bool	true / false
nxt_write_output_uint32	Min: 0 Max: 4 294 967 295
nxt_write_output_float	Min: -3.4E+38 Max: 3.4E+38
nxt_write_output_size	Min: 0 Max: 3.4E+38
nxt_write_output_ratio
nxt_write_output_bitrate
nxt_write_output_duration	Min: 0 ms Max: 49 days Precision in milliseconds
nxt_write_output_date_time	DD.MM.YYYY@HH:MM
nxt_write_output_string_list	0 - 1024 characters (output truncated if bigger)

Implementing campaigns

Combine remote actions with campaigns to help employees solve issues independently. Campaigns let you inform employees about the detection of an issue and guide them through its resolution.

To display a campaign on the desktop of an employee who is interacting with a device:

• The campaign must have a Remote action trigger and be published.

• The script of the remote action can be executed either:

  • In the context of the employee, if the action does not need any special privileges.

  • In the context of the local system account, if the action needs administrative privileges.

Obtaining a campaign identifier

The methods to run a campaign from a remote action require a campaign identifier to be passed as an argument. You can use both the campaign NQL ID (recommended) and the campaign UID (classic option).

Support for the NQL ID as an identifier requires Collector version 23.5 or later.

To pass the campaign identifier to a remote action, declare a parameter in the script of the remote action for each required campaign. Use the NQL ID (or UID) as the actual value for the parameter when editing the remote action.

For more information on how to get the NQL ID or the UID of a campaign, refer to the Triggering a campaign documentation.

Running a campaign from the script of a remote action

The following functions extend the scripting capabilities of remote actions.

nxt_run_campaign( id )

The function runs the campaign matching the NQL ID (preferred) or UID passed as a parameter and saves the answers internally.

• The function returns 0 if the campaign status is received.

• The function returns 1 in all other cases, and the error is reported in the logs.

Calling the function pauses the execution of the remote action until the employee either completes the campaign or dismisses it.

nxt_run_campaign_with_timeout( id timeout)

The function runs the campaign matching the NQL ID (preferred) or UID with the timeout in seconds (0 < T < 1 week) passed as a parameter, and saves the answers internally.

• The function returns 0 if the campaign status is received.

• The function returns 1 in all other cases, and the error is reported in the logs.

Calling the function pauses the execution of the remote action until the employee either completes the campaign, dismisses it or fails to finalize the campaign before the timeout.

nxt_run_standalone_campaign( id )

The function runs the campaign matching the NQL ID (preferred) or UID passed as a parameter and saves the answers internally.

• The function returns 0 if the campaign status is received.

• The function returns 1 in all other cases, and the error is reported in the logs.

Calling the function triggers the start of the campaign and continues the execution of the remote action without waiting for the employee's answers.

nxt_get_campaign_status( res_var )

The function returns the status of the last campaign.

• fully: the employee has fully answered the campaign questions.

• timeout: the campaign was timed out before the user finished answering.

• postponed: the employee agreed to participate in the campaign.

• declined: the employee declined to participate in the campaign.

• connectionfailed: the script was unable to connect to the Collector component that controls campaign notifications.

• notificationfailed: the script was unable to display the campaign successfully due to one of the following:

  • The campaign definition could not be retrieved from the platform because of a non-existing campaign or a non-published campaign.

  • Another campaign is already being displayed to the employee.

  • A non-urgent campaign cannot be shown due to the focus protection or do-not-disturb rules of Collector. Refer to the Limiting the reception rate of campaigns documentation for more information.

• Empty if the last campaign failed.

nxt_get_response_answer( res_var question_key)

Query the last campaign using a question label as a string parameter query_key. The function extracts the answer as a string value and saves it in the given variable res_var.

• Returns 0 if the campaign status is received.

• Returns 1 otherwise.

Encoding the script

To write Bash scripts for remote actions:

• Encode the files that contain the script in UTF-8, without BOM.

• End each line in the code with the usual character in UNIX systems: LF.

Ensure proper encoding to avoid errors or nonfunctioning scripts.

Code examples

Calling a campaign

In this example, the remote action executes a basic campaign call by its ID, outputting a status message if successful or an error message if unsuccessful.

if nxt_run_campaign "#my_campaign_nql_id"; then
    nxt_get_campaign_status status
    if [[ status == "fully" ]]; then
        echo "Campaign succeeded"
    else
        echo "Status is $status"
    fi
else
    echo "Campaign failed"
fi

Accessing the responses

In this example, the remote action calls for campaign answer data and outputs it as an array. Each answer is represented by its corresponding numbered option. Bash uses 0 as its lowest option, while Zsh uses 1.

nxt_get_campaign_status status
echo "The response status is $status"
nxt_get_response_answer answersArray key1
echo ${answersArray[1]}

Running a campaign with a timeout

In this example, the remote action is set to run a campaign that times out and closes after a specified time, using seconds as input.

# timeout is in seconds (100s or 00:01:40)

if nxt_run_campaign_with_timeout "#my_campaign_nql_id" 100; then
    nxt_get_campaign_status status
    if [[ status == "fully" ]]; then
        echo "Campaign succeeded"
    else
        echo "Status is $status"
    fi
else
    echo "Campaign failed"
fi

Running a non-blocking campaign

In this example, the remote action does not require user input and continues executing after triggering a campaign. The user can dismiss the campaign at any point. This is used mainly to provide users with information rather than to obtain data.

Refer to the Conducting engaging campaigns documentation for more information.

if nxt_run_standalone_campaign "#my_campaign_nql_id"; then
    nxt_get_campaign_status status
    if [[ status == "fully" ]]; then
        echo "Campaign succeeded"
    else
        echo "Status is $status"
    fi
else
    echo "Campaign failed"
fi

Signing the script

For security reasons, Nexthink requires Bash scripts for remote actions on macOS to be digitally signed with the codesign tool. Pack your signed script as a tar.gz file to preserve its extended attributes. Nexthink web interface only accepts files with the tar.gz extension when importing scripts for remote actions that target macOS.

Nexthink recommends signing all scripts in a production environment. Unsigned scripts should only be used in testing environments.

Creating a certificate

• Launch Keychain Access on your Mac device.

• Go to Keychain Access > Certificate Assistant > Create a Certificate…

• Enter the name of your certificate.

• Choose Code Signing for the Certificate Type.

• For testing purposes, you can leave Let me override defaults unchecked.

• Click Create and Done. The system has generated the certificate.

Signing

Sign the remote action scripts using the standard macOS codesign utility.

codesign -s <your certificate identity> --timestamp --prefix=<code signature identifier prefix> --force <script file name>

Parameters:

-s <your certificate identity>

The identity of your code signing certificate is in the Keychain. Generally, it is a certificate subject common name or a certificate hash. Refer to the codesign manual page documentation from UNIX for more information.

--timestamp

A trusted timestamp for a signature.

--prefix

A prefix to a code signature identifier. It attaches your company identity to an identifier and helps to make an identifier unique. See the code signature identifier generation rules on the codesign manual page documentation from UNIX.

--force

This forces a code signature to be rewritten if it already exists.

Example

Example of a test certificate for example_ra_script.sh remote action script:

codesign -s "RA scripts code signing certificate" --timestamp --prefix=com.my-organisation.remote-action.macos. --force example_ra_script.sh

The signature for the script file is generated in the file system extended attributes associated with the file. Use the codesign utility to get the code signature details and validate the signature:

Packaging

Package the remote action script with a .tar archive and .gzip compression. The extension ".tar.gz" is mandatory.

tar -czvf ./<your script name>.tar.gz ./<your script name>.sh

If the script file is signed, the tar utility will pack its extended attributes as well. This way, the system can transport the code signature and a script file.

Limitations

• Only one script can be put into one archive.

• A script file should be placed in the root package folder; the ./myscript/myscript.sh path is incorrect.

• A script must have the .sh extension.

• A script filename must be UTF-8 encoded, which is the default on macOS.

Example

Example of packaging the test.sh script:

tar -czvf ./example_ra_script.tar.gz ./example_ra_script.sh

The resulting example_ra_script.tar.gz is the remote action script file.

Nexthink recommends using this script to simplify the signing and packaging process.

#!/bin/bash
#
# script_signing.sh
# 
# Copyright (C) 2023 by Nexthink S.A., Switzerland. Any usage, copy or partial copy of
# this code without the explicit agreement of Nexthink S.A. is prohibited and will be
# pursued to the full extend of the law.
#
# The arguments for the script:
# - input script filename
# - output archive filename
# - Certificate owner
# - Prefix
#
 
 
# Error handling
set -euo pipefail
trap "echo unrecoverable error !" ERR
 
 
# Check codesign
if [[ ! -x /usr/bin/codesign ]]
then
    echo "Error: this script requires that codesign is installed"
    exit 2
fi
 
# Check tar
if [[ ! -x /usr/bin/tar ]]
then
    echo "Error: this script requires that tar is installed"
    exit 2
fi
 
 
# Check arguments
if [[ $# -lt 4 ]]
then
    echo "Usage: script_signing.sh inputScriptFilename outputArchiveFilename CertificateOwner prefix"
    echo "Example: ./script_signing.sh script.sh script.tar.gz \"John Doe\" com.john.remote-action.macos."
    exit 1
fi
 
/usr/bin/codesign -s "$3" --timestamp --prefix="$4" --force "$1"
/usr/bin/tar czf "$2" "$1"

Deploying the certificate to endpoints

If you have your code signing certificate in the Keychain and want to install its public version on endpoints, you need to export it first.

• Choose the Certificate (.cer) file format for a public certificate in the pop-up window.

Importing a certificate to the Keychain on endpoints

• Import your code-signed certificate into the System keychain to use remote action scripts with a Trusted Publisher execution policy.

• Double-click a .cer file and choose the System option in the Keychain drop-down menu.

• Enter the root password to import the certificate.

If the certificate is self-signed, it should also be trusted for code signing.

• Double-click the Keychain Access utility certificate and choose Always trust for the Code Signing option.

To automate these tasks, use the security utility (external link) or your automation framework.

Verify that the certificate was properly imported to an endpoint

• Copy and unpack your signed remote action script to the endpoint.

tar -xzvf example_ra_script.tar.gz

• Verify your signature.

codesign -vvvv -R="certificate leaf trusted" example_ra_script.sh

If the signature is properly imported, you should see the following output:

Maintaining the script

Comparison and validation

Before deploying a remote action script, it is possible to compare it with other scripts prepared by Nexthink. This step is optional but recommended if it is your first time preparing a script.

1. In the Nexthink Library, select Content.

2. Filter by Remote action.

3. Navigate to the Remote Actions management page.

4. Select any remote action script installed directly from the Nexthink Library that matches the target operating system.

5. Export the script and compare its syntax with your script’s.

Script termination and timeout

When launching subprocesses from your remote action script and the remote action script terminates or times out, Collector terminates the subprocesses automatically. If you want the subprocess to continue executing after the remote action is terminated, ensure that your script detaches the subprocess using the & character, for example:

some_script.sh -arg1 -arg2 &

Zsh command interpreter

Starting with Collector version 6.27.2, you can run scripts written for the Zsh Unix shell. You must add the following line of code at the very beginning of the shell script:

#!/bin/zsh

This is a character sequence known as a shebang (external link).

When the system triggers a remote action on a Mac, Collector checks the first line of code and executes the rest of the instructions using the specified interpreter. A script without a shebang will be executed using the Bash command interpreter.

Nexthink recommends always using a shebang in shell scripts and sticking to the standard interpreters.