Writing scripts for remote actions on Mac

Contents

Writing scripts for remote actions on Mac

Overview

The payload of remote actions on Mac are Bash scripts that run on the devices of the employees. Bash is a command-line shell and scripting language that is supported by many UNIX-like operating systems, such as macOS, and suited for task automation and configuration management. Bash scripts are therefore ideal to get on-demand data from devices, perform self-healing tasks, or modifying the configuration of a device, which are typical use cases for remote actions.

Learn here the specifics of how to write Bash scripts for remote actions. This article assumes familiarity of the reader with Bash scripting.

Find more information about writing scripts for remote actions on Community:

Applies to platforms: PlatformWindows.png

Encoding

To write your own Bash scripts for remote actions, encode the files that hold the text of your scripts in UTF-8 (without BOM).

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

Failing to provide the right encoding to your script files will result in the inability of remote actions to run on the devices of the employees.

Signing and packaging your own scripts

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

To sign your script, type in:

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

Where the options are the following:

-s
The identity of your code signing certificate in the Keychain. Usually it's a certificate subject common name or a certificate hash. See the codesign manual page for the full description.
--timestamp
Generate a trusted timestamp for a signature.
--prefix
A prefix to a code signature identifier. Attaches your company identity to an identifier and helps to make an identifier unique. See the code signature identifier generation rules in the codesign manual page.
--force
Forces to rewrite a code signature if it already exists.

Package your script and signature as a tar.gz file to preserve the extended attributes before uploading to the Finder:

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

Writing generic scripts

Scripts may be written in a generic way so they can be adapted to particular use cases. To make your script generic, declare formal parameters at the beginning of the Bash script. Provide actual values to the parameters in the Finder, when editing the remote action that holds the script.

Genericity is specially useful in the case of digitally signed scripts that require some customization. When a script is signed, any modification to its text content breaks the signature. By making a signed script generic, you allow its customization via parameters. With parameters, the text of the script remains unchanged and thus the digital signature remains valid. The values for the parameters that a remote action passes to the script determine its actual behavior.

Declare parameters at the beginning of a script as usual 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


The editor of remote actions recognizes 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. Note that the actual values are always passed to the script as text: if the script declares parameters whose type is other than the string type, ensure that the values that you provide can be properly converted to the type of their corresponding parameter.

Output variables

The execution of a script may generate some outputs that you want to store as on-demand data in the Engine. To that end, Nexthink provides a Bash script (nxt_ra_script_output.sh) that is installed in the device of the employee at the same time as the Collector. The script includes functions to write results to the Engine.

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, let us suppose that you want to return the number of files in a directory to the Engine and that the variable nfiles in your script holds that number. To write the value of nfiles through an output with name FileNumber to the Engine, call the function to write unsigned integers:

nxt_write_output_uint32 'FileNumber' $nfiles


The editor of remote actions recognizes the calls to write outputs in the script and lists the output variables under the Outputs section below the script text. Set the label of the output to indicate how to refer to it in investigations and metrics.

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

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_string_list Same as string
The operations described in this article should only be performed by a Nexthink Engineer or a Nexthink Certified Partner.

If you need help or assistance, please contact your Nexthink Certified Partner.