Create Scripts for Remediation on MAC Devices

In order to reduce the number of IT tickets and improve user experience, Aternity developed the Remediation feature. Remediation allows IT Service Desk personnel to identify issues that can cause problems and remotely fix them before they will be escalated. Running remediation actions remotely resolves performance issues on end user devices by one-click reducing the problem-solving time and the risk of human errors. Remediation actions can be triggered automatically based on Service Desk Alerts, manually by IT Service Desk personnel or from external systems using REST API.

To properly run remediation actions on MAC devices, you should create, sign, and upload scripts to Aternity.

MacOS supports running scripts in multiple languages such as shell scripting, Python, Perl, etc. To allow flexibility, the remediation feature will also support running scripts in any language that is supported by end user device.

The scripts should have the interpreter defined at the top of the script using the shebang syntax. Such scripts behave as an executable file and can be run directly on end user devices. For example,

if [[ -d ~/.Trash && "$(ls ~/.Trash)" ]]
    rm -rf ~/.Trash/*
    echo "Done!"
    echo "No Trash dir found."
For Agent 3.7.x, remediation is OFF by default. To turn it ON, do the following steps:
  1. Run the command that will restart the Agent and start the AterenityEUEScriptRunner process(es):
    # user install
    ~/Library/Aternity/Agent/bin/change-remediation-deployment on
    # system install
    sudo /Library/Aternity/Agent/bin/change-remediation-deployment on
  2. Contact Aternity SaaS Administration and ask to enable remediation for the account.

To... Do This...

Define Script Policy

Sign the scripts with a valid certificate.

Script policy is either blocked (no remediation actions can be run) or trusted (remediation actions signed with a trusted certificate can be run).

Run one of the commands, depending on the level (user or system):

# user install
~/Library/Aternity/Agent/bin/change-security-policy <blocked/trusted>

# system install
/Library/Aternity/Agent/bin/change-security-policy <blocked/trusted>

Learn script requirements

  • The interpreter used for the script should always be defined with the shebang syntax at the top of the script. Example for a bash script: #!/bin/bash

  • Remediation action status and output:

    • When the remediation action completes successfully, the stdout of the script is picked up and returned as output of the action. To limit the size of output of the remediation command, it is recommended to redirect output of commands run by the remediation script to stderr. For example: ping $myserver 1>&2 This also helps to capture the output of the command in case the remediation script returns an error.

    • When the remediation action is unsuccessful (returns error), the stderr of the script is picked up and returned as output of the action. To indicate the failure of the action, the script can set a non-zero return code. Also, to capture output messages in case of action failure, make sure to redirect stdout to stderr for such messages. For example:
      if [ -d /Users/$1 ]; then
          # make sure the error message goes to stderr
          echo "Could not find home dir for $1" 1>&2
          exit 1
    • In addition to the action output, the return code of the script is also picked up and reported back as a field for the action.

Sign scripts
Use the script signing tool in the Agent bin directory. The output file must be a zip. For example:
/Library/Aternity/Agent/bin/sign_script.zsh -i ~/Documents/
-k ~/Documents/key.pem -o ~/Documents/
The certificate corresponding to the key used to sign the script should be available on the system keychain of the end user device.

Create remediation action in Aternity

Learn here how to create remediation actions in Aternity.

Instead of PowerShell, you are uploading the zip file to Aternity.