Create and Validate PowerShell Scripts for Remediation Actions

Create PowerShell script(s), validate that they properly signed and encoded, and then upload them to Aternity in order to run remediation actions on end user monitored devices. This article provides tips for creating scripts that will properly run in Aternity and procedures for scripts' validation. Validation Tool checks that scripts are successfully signed with a trusted digital certificate and use the correct Windows UTF-8 encoding.
Validate that the script is properly signed and has a correct syntax
Tip

Find the shared samples of the scripts in the Aternity Scripts Library. Use the readme file to better understand how to use the repository, how to contribute and more.

Here are several TIPS about how to create scripts.
  • PowerShell supports the Windows UTF-8 file format ONLY (not UTF-8 BOM or UTF-16). Verify the file encoding prior to saving the file.

  • When creating a script, you must include the ActionExtensionsMethods.dll file. To do this, use the command:
    Add-Type -Path $env:STEELCENTRAL_ATERNITY_AGENT_HOME\ActionExtensionsMethods.dll
    Now you have two functions you can use:
    • SetScriptOutput - This function returns an output message with some additional information that you can later use to examine action results. For example, if your script cleared space, then it can return information about how much space was cleared. For example:
      #[ActionExtensionsMethods.ActionExtensionsMethods]::SetScriptOutput("<write here your message>")
    • SetFailed - This function identifies the action as failed. You should identify as a failure any case in which the action most likely failed to remedy the original issue. For example, if there was no space to clear, then the script should identify this action as a failure. As a parameter, send the type of a failure. For example:
      #[ActionExtensionsMethods.ActionExtensionsMethods]::SetFailed("<write your error here>")
  • (Optional) use a variable as your input parameter to perform a single action in multiple cases. For example, you can now create a script for restarting services and define that the name of the service is your input parameter (variable). In order to use an input parameter, the script should include the first argument with this exact syntax: $args[0]. For example:
    {
    	Add-Type -Path $env:STEELCENTRAL_ATERNITY_AGENT_HOME\ActionExtensionsMethods.dll
    	
    	$serviceName = $args[0]
        $service = Get-Service -Name $serviceName -ErrorAction Stop
    
    	if ($service.Status -eq 'Running')
        {
            Stop-Service -Name $service.Name
    		[ActionExtensionsMethods.ActionExtensionsMethods]::SetScriptOutput($service.name + " service is stopped")
        }
        else 
        {
            [ActionExtensionsMethods.ActionExtensionsMethods]::SetScriptOutput($service.name + " service is already in stopped state") 
        }
        
        
    }
  • Try a sample action script that performs a remediation successfully:
    {
                    Add-Type -Path $env:STEELCENTRAL_ATERNITY_AGENT_HOME\ActionExtensionsMethods.dll
                    # This script is a sample script that does nothing but it will finish successfully. 
     # Add your remedy logic here…
                    
                    # If you want this script to set an Output Message to be included in dashboards, then comment-out the next line and set the string parameter
                    #[ActionExtensionsMethods.ActionExtensionsMethods]::SetScriptOutput("<write here your message>")
    }
    catch
    {
                    [ActionExtensionsMethods.ActionExtensionsMethods]::SetFailed($_.Exception.Message)
    }
    
    
  • Try a sample action script that fails to perform remediation:
    {
                    Add-Type -Path $env:STEELCENTRAL_ATERNITY_AGENT_HOME\ActionExtensionsMethods.dll
                    # This script is a sample script that does nothing but ends with a failure
    # Add your remedy logic here…
                    
                    # In order to notify Aternity about the failure, comment-out the next line and set the string parameter with the error message to be included in dashboards
                    [ActionExtensionsMethods.ActionExtensionsMethods]::SetFailed("<write your error here>")
    }
    catch
    {
                    [ActionExtensionsMethods.ActionExtensionsMethods]::SetFailed($_.Exception.Message)
    }
    

Procedure

  1. Step 1 Create a PowerShell script.

    See the tips above.

  2. Step 2 Sign the script(s) with a trusted certificate before executing them on monitored devices.
  3. Step 3 Make sure the signing policy was set up during the Agent deployment (learn more).
    For security reasons, by default, the Agent runs only scripts that are signed either by Aternity or by certificates listed in the Trusted Publishers store of the device on which you run the script. To open the Certificates dialog-box and to see the certificates included in the Trusted Publishers store of the device, open a Command Prompt window and run the certlm command.
    Launch Local Computer Certificates
    Tip

    If using the default signing policy during Agents mass deployment (Trusted), make sure to place your certificates in the folder shown in the above figure.

    It is possible to change the default parameter of the signing policy in the Agent's batch file ONLY during its deployment (learn more). There are three possible options to alter:
    • Trusted - The default policy that automatically applies during Aternity Agent mass deployment. This setting enforces the usage of digital signing of scripts and allows running only the scripts that are signed and secured.

    • Unrestricted - Aternity Agent runs any script, both signed and not signed.

    • Blocked - Aternity Agent blocks any script, either signed or not.

    Currently, changing the signing policy is supported ONLY for the mass installation batch file by entering the following parameter: ACTION_EXECUTION_POLICY=Unrestricted or ACTION_EXECUTION_POLICY=Blocked

    If the certificate you use for signing is not listed in the Trusted Publishers store, you have an option to explicitly specify in the Agent's batch file what certificate the Agent should trust. You can define up to two certificates during Agent's mass deployment: TRUSTED_CERTIFICATE_SUBJECT1= and TRUSTED_CERTIFICATE_SUBJECT2=. Enter the value to specify the subject of the certificate.

  4. Step 4 Validate the script signature and encoding.
    Note

    The tool interface may vary depending on the deployed Agent version on your device.

    1. a Run the Validation Tool by executing PowerShellValiadtion.exe from the Agent setup folder (for example, ...ProgramFiles\Aternity Information Systems\Agent.

      The tool should be used for validation of any PowerShell script file signatures, like Remediation scripts or PowerShell monitor scripts.

    2. b Go to the Signing Policy tab.
    3. c Depending on the script you validate, select the Remediation or PowerShell monitors radio button to show the signing policy deployed on monitored devices for running that type of scripts. Learn more
    4. d Click Select to browse to the required script.
      Run the Validation Tool
    5. e Once the file is selected, click Validate and check the results in the Results area.

      The tool validates a script signing, a script encoding (must be Windows UTF-8 only) and whether there are not allowed characters (the sequence of CRCRLF characters).

      If there are issues with the signature, the result will be invalid.

      Make sure to use the correct encoding
      See the list of potential issues and sample messages in case of signing problems:
      • Signing issue: Script is not signed, or script signature is corrupted - Displayed in case the script is not signed at all or its signature was manipulated.
      • Signing issue: Script signature is not valid - Displayed in case the signature does not match the script.
      • Signing issue: The root certificate is not trusted - Displayed in case the root certificate of the certificate that was used to sign the script is not in the trusted root certification authorities.
      • Signing issue: The certificate is not trusted - Displayed in case the certificate that was used to sign the script is not in the trusted publishers and is not explicitly trusted by the Agent.

      Fix all issues and make sure the validation passes.

      Make sure the script complies with the rules

      Depending on the file you select, the fields in the Policy area are being populated with the data from the Agent configuration and show the installed values for the selected file: whether the policy is Trusted, Unrestricted or Blocked (learn more).

  5. Step 5 Proceed with remediation actions setup in Aternity.