Managing the Reach script library

Depending on the permissions associated with your user role, and the Absolute product licenses associated with your account, the script library may not be available.

You can use the Absolute Reach® Script library in the Settings area to upload and manage custom Reach scripts that you want to run on your devices. When you create a custom Reach script, you can specify script configurations, which are saved with the script and applied when the script runs on a device.

Due to restrictions imposed by Microsoft, PowerShell is not supported on Windows 11 SE. The Reach feature uses PowerShell and is not supported on devices running Windows 11 SE.

To add, edit, or delete a custom Reach script in the script library, your user role must be granted the Manage permission for Reach Script. If the script is referenced in an Action rule, your user role must also be granted the Manage permission for Rules. The System Administrator and the Security Administrator roles are granted these permissions by default.

To view a Reach script in the Reach script library, your user role needs to be granted the View permission for Reach Script. All Administrator roles and the Security Power User role are granted this permission by default.

You can view information about Absolute and custom Reach scripts in the script library. You can also view a preview of the PowerShell and Bash scripts contained in the Reach script, and view the PowerShell script's signature.

To view a script:

  1. Log in to the Secure Endpoint Console as a user with the Manage permission for Reach Script.
  2. On the navigation bar, click Settings > Script library.

  3. Click the background of the script you want to view. To search for a script, enter all or part of the name or description in the Search field. The search results update dynamically as you type. Click Absolute or Custom to limit the search results. The script overview area opens to the right of the work area and shows the following information:

    • Script name
    • Script creator
    • Supported platform
    • Script description, if any

    • Action rule that is using the script, if applicable

      Click the rule name to view the rule details.

      Deleting a custom script that is being used by an Action rule deactivates the rule.

    • View Script link
    • Script variables
    • Advanced configuration options

  4. Click View Script.

    A preview of the script opens.

  5. To view the signature for a PowerShell script, click Show in the Signature section.
  6. To close the preview, click (Close).

  7. To close the script overview, click .

You create a new custom Reach script by giving the script a name and description, uploading a PowerShell script, a Bash script, or both to the custom Reach script, and setting the configurations required to run the script.

To create a custom Reach script:

  1. Log in to the Secure Endpoint Console as a user with the Manage permission for Reach Script.
  2. On the navigation bar, click Settings > Script library.
  3. On the quick access toolbar, click Create script.

  4. Click the script name and enter a descriptive title to help you identify the script.

    If you don't update the name of the script, the script is called Custom Script - <Date>.

  5. [Optional] Enter a description.

    Description can be a maximum of 255 characters.

  6. Verify that your script meets the following requirements and best practices.

    • The script is in one of the following formats:

      • PowerShell script (.ps1): for Windows devices

        If the script contains Unicode characters, use UTF-8 encoding and include the Byte Order Mark (BOM).

        We recommend that all PowerShell scripts use UTF-8 encoding and include the BOM.

      • Bash script (.sh): for Mac devices
    • The script doesn't exceed 1468 KB in size

    The following practices ensure that the Reach script produces the desired results before you use Absolute Reach to deploy a script across your fleet of devices:

    • Add error handling to your PowerShell and Bash scripts to help troubleshoot any issues that may arise. Script return codes show in Action Requests and Event History.
    • Before you upload a PowerShell script, review the PowerShell guidelines pertaining to the Absolute schema.
    • In the Secure Endpoint Console, use the Run Script option to deploy the script on a small subset of test devices and observe the results.

  7. Do one or both of the following depending on the type of script file you want to upload:

    1. Under Windows Devices, click Upload PowerShell Script, navigate to the location of the PowerShell script file (.ps1) that you want to upload and click Open.

      If the script isn't signed, you see a message that Absolute will sign the script.

      If the script is signed, the signature format is verified. If the format is invalid signature, you see an error message. Verify the signature and reupload the script. The signature is validated at the device when the script is used in a Run Script request.

    2. If your script includes parsed parameters, the Script Variables section shows the parameters that will be available as user-input fields on the Run script wizard. Review the field labels and any help text to make sure that they show as expected.

    3. If you want to specify one or more command line parameters to apply when the script runs on a device, enter them in the PowerShell Parameters field.

      The default parameters that will be used to run the script are displayed above the field. Any PowerShell parameters that you specify take precedence over the default parameters.

      This field isn't validated for correct syntax. Make sure that you enter the parameters correctly.

    4. Set the Advanced Configuration Options for the PowerShell script. These configurations are saved with the script and applied when the script runs on the device.

      Configuration Options
      Rights

      Select one of the following options:

      • Run with system account rights: run the script using the rights associated with the local system account

        Ensure that you select this option if the PowerShell script references Absolute .dll files, as non-system accounts do not have access to these files.

      • Run with logged in user rights: run the script using the rights of the logged in user

        Ensure that you select this option if the PowerShell script requires access to the device user's data or input from the device user (such as acknowledgment of a license agreement).
      Display Mode

      Select one of the following options (if available):

      • Hidden: run the script in the background so it is not visible to the user
      • Maximized: show the Windows PowerShell dialog on the device
      • Minimized: minimize the Windows PowerShell dialog to the Windows taskbar
      Run Condition

      Select one of the following options:

      • No user is signed in: run the script only when no user is logged in
      • User is or isn't signed in: run the script regardless of whether a user is logged in
      • User is signed in: run the script only when a user is logged in
      Maximum Run Time

      Specify the maximum number of minutes (or hours) the script can run before it is terminated. The default setting is 120 minutes, but any value between 1 minute and 24 hours is supported.

      To change this setting, enter a numerical value in the field. To change the unit of time to hours, click the Minutes field and select Hours.
      Run 32-bit version If you want to use the 32-bit version of PowerShell (x86) to run the script on 64-bit Windows devices, select the checkbox. If you leave the checkbox cleared, the 64-bit version of PowerShell is used to run the script on these devices.
    1. Under Mac Devices, click Upload Bash Script, navigate to the location of the Bash script file (.sh) that you want to upload and click Open.

    2. If you want to specify one or more command line parameters to apply when the script runs on a device, enter them in the Bash Parameters field.

      The default parameters that will be used to run the script are displayed above the field. Any Bash parameters that you specify take precedence over the default parameters.

      This field isn't validated for correct syntax. Make sure that you enter the parameters correctly.

    3. Set the Advanced Configuration Options for the Bash script. These configurations are saved with the script and applied when the script runs on the device.

      Configuration Options
      Rights

      Select one of the following options:

      • Run with system account rights: run the script using the rights associated with the local system account
      • Run with logged in user rights: run the script using the rights of the logged in user
      Display Mode This field is unavailable for Bash Scripts
      Run Condition This field is unavailable for Bash Scripts
      Maximum Run Time

      Specify the maximum number of minutes (or hours) the script can run before it is terminated. The default setting is 120 minutes, but any value between 1 minute and 24 hours is supported.

      To change this setting, enter a numerical value in the field. To change the unit of time to hours, click the Minutes field and select Hours.
  8. Click Save.

The custom Reach script is added to the Reach script library. If the script contained both a PowerShell script file and a Bash script file, they're saved together in the custom Reach script. A Script created event is logged to Event History.

All script configurations are saved with the script as default values. If you entered PowerShell Parameters or Bash Parameters, they're also saved as defaults.

You can update the following custom Reach script properties:

  • Script name
  • Description
  • PowerShell and Bash parameters
  • Advanced configuration options

You can also replace the PowerShell or Bash script with a new script file, or if the custom Reach script only contains one kind of script, you can add the other.

To edit custom Reach script properties:

  1. Log in to the Secure Endpoint Console as a user with the Manage permission for Reach Script.

    To edit a custom script that is used by an Action rule, the Manage permission for Rules is also required.

  2. On the navigation bar, click Settings > Script library.
  3. Search for a script by entering all or part of the name or description in the Search field. The search results update dynamically as you type. Click Custom to limit the search results.

  4. Hover over the script's row to display the quick action bar and click (Edit).

    You can also edit a script by clicking Edit on the script's overview.

  5. Do one of the following:

    • If the Edit Script dialog opens, the script is used by an Action rule and your user role needs to be granted the Manage permission for Rules to edit the script. On the Edit Script dialog, do one of the following:

      • If you are granted the required permission, do one of the following:

        • To edit the script, click Continue.

        • To leave this script unchanged, and create a copy of the script for you to edit, click Make a copy.

      • If you are not granted the required permission, do one of the following:

        • To create a copy of the script for you to edit, click Make a copy.

        • To close the dialog and return to the Script Library, click .

    • If the Edit Script dialog does not open, the script is not used by an Action rule. Go to the next step.

  6. To update the script name or description, click the field and edit it.

  7. To edit any PowerShell Parameters or Bash Parameters for the script, click the field and edit the text.

    These fields isn't validated for correct syntax. Make sure that you enter the parameters correctly.

  8. To edit the Advanced Configuration Options, edit each configuration, as required:

    Configuration Options
    Rights

    Select one of the following options:

    • Run with system account rights: run the script using the rights associated with the local system account

      Ensure that you select this option if the PowerShell script references Absolute .dll files, as non-system accounts do not have access to these files.

    • Run with logged in user rights: run the script using the rights of the logged in user

      Ensure that you select this option if the PowerShell script requires access to the device user's data or input from the device user (such as acknowledgment of a license agreement).
    Display Mode

    Select one of the following options (if available):

    • Hidden: run the script in the background so it is not visible to the user
    • Maximized: show the Windows PowerShell dialog on the device
    • Minimized: minimize the Windows PowerShell dialog to the Windows taskbar
    Run Condition

    Select one of the following options:

    • No user is signed in: run the script only when no user is logged in
    • User is or isn't signed in: run the script regardless of whether a user is logged in
    • User is signed in: run the script only when a user is logged in
    Maximum Run Time

    Specify the maximum number of minutes (or hours) the script can run before it is terminated. The default setting is 120 minutes, but any value between 1 minute and 24 hours is supported.

    To change this setting, enter a numerical value in the field. To change the unit of time to hours, click the Minutes field and select Hours.
    Run 32-bit version If you want to use the 32-bit version of PowerShell (x86) to run the script on 64-bit Windows devices, select the checkbox. If you leave the checkbox cleared, the 64-bit version of PowerShell is used to run the script on these devices.
    Configuration Options
    Rights

    Select one of the following options:

    • Run with system account rights: run the script using the rights associated with the local system account
    • Run with logged in user rights: run the script using the rights of the logged in user
    Display Mode This field is unavailable for Bash Scripts
    Run Condition This field is unavailable for Bash Scripts
    Maximum Run Time

    Specify the maximum number of minutes (or hours) the script can run before it is terminated. The default setting is 120 minutes, but any value between 1 minute and 24 hours is supported.

    To change this setting, enter a numerical value in the field. To change the unit of time to hours, click the Minutes field and select Hours.
  9. If you are editing a script that is referenced in one or more Action rules, and you want to deactivate the rules while you review the new script within the context of the rule configurations, select the checkbox next to Deactivate rules associated with this script. After the review is complete, you can re-activate the rule.
  10. Click Save.

The script is updated and a Script updated event is logged to Event History.

All script configurations are saved with the script as default values. If you entered parameters, they're also saved as defaults.

You can't directly edit a PowerShell or Bash script within a Custom Reach script. Instead, you must copy the script text, make the changes on your local machine, and then upload the edited script. If you make changes to a PowerShell script that you've signed, make sure to resign the script when you've made the changes. If you don't update the signature, you can upload the script successfully because the format is valid, but when you use the script in a Run Script request with signature validation enabled, the signature validation fails and the script fails to run on your devices.

To add or replace a PowerShell or Bash script

  1. Log in to the Secure Endpoint Console as a user with the Manage permission for Reach Script.

    To edit a custom script that is used by an Action rule, the Manage permission for Rules is also required.

  2. On the navigation bar, click Settings > Script library.
  3. Search for a script by entering all or part of the name or description in the Search field. The search results update dynamically as you type. Click Custom to limit the search results.

  4. Hover over the script's row to display the quick action bar and click (Edit).

    You can also edit a script by clicking Edit on the script's overview.

  6. [Update script only] Click View Script.
  7. [Update script only] Copy the script text and paste it into a text editor, such as NotePad++.
  8. [Update script only] Make the changes to the script and save it to a location on your local computer.
  9. [Update PowerShell script only] If you sign your own scripts, resign the script.
  10. Upload the PowerShell or Bash script by clicking Upload <script format> Script and setting the required configurations.
  11. If you are editing a script that is referenced in one or more Action rules, and you want to deactivate the rules while you review the new script within the context of the rule configurations, select the checkbox next to Deactivate rules associated with this script. After the review is complete, you can re-activate the rule.
  12. Click Save.

The script is updated and a Script updated event is logged to Event History.

All script configurations are saved with the script as default values. If you entered parameters, they're also saved as defaults.

If you no longer want a script to be available to run from the Secure Endpoint Console, you can delete a custom Reach script from the Reach script library.

Note that any pending Run Script requests aren't impacted when you delete a script. Those requests are completed as expected.

If you delete a custom script that is used by an Action rule:

  • The rule is deactivated, and a Rule updated event is logged to Event History.
  • In the Policies > Rules area, the rule shows a icon to indicate that an item used by the rule has been deleted. Edit the rule and replace the deleted script with another script.

To delete a script:

  1. Log in to the Secure Endpoint Console as a user with the Manage permission for Reach Script.

    To delete a custom script that is used by an Action rule, the Manage permission for Rules is also required.

  2. On the navigation bar, click Settings > Script library.
  3. Search for a script by entering all or part of the name or description in the Search field. The search results update dynamically as you type. Click Custom to limit the search results.

  4. Hover over the script's row to display the quick action bar and click (Delete).

    You can also delete a script by clicking on the script's overview.

  5. Click OK.

The script is removed from the script library and a Script deleted event is logged to Event History.