Sign Remediation Scripts for Testing Purposes

This article explains how to quickly set up a test environment and self-sign new remediation scripts for testing purposes.

When a remediation script ready, you have to sign it BEFORE configuring Remediation action in Aternity.

On the machine prepared for signing, the PowerShell script Sign-RemediationScript.ps1 can sign remediation scripts. It uses the certificate created in the local certs store. The Source parameter is the path of the script to sign and Destination is the path where the signed file will be created.

The signed script can then be uploaded to the Aternity Remediation screen and executed on a user test device.

Example:
.\Sign-RemediationScript.ps1 -Source .\Network\Remediation-DNS-ClearCache.ps1 -Destination .\Signed\Remediation-DNS-ClearCache-signed.ps1

Output example:

    Directory: C:\Aternity\Remediation-Scripts-Library\Signed


SignerCertificate                         Status     Path
-----------------                         ------     ----
E2C88872665FE1B5B8430E53EC7213B1171241E3  Valid      Remediation-DNS-ClearCache-signed.ps1
Tip
Depending on your environment, you might need to set the PowerShell Execution Policy prior to running the preparation scripts. For example, when launching PowerShell console, the following command will be required to allow execution of any .ps1 script in the current PowerShell console session:
Set-ExecutionPolicy Unrestricted -Scope Process

Before you begin

  • Create PowerShell scripts (learn more). Remediation-DNS-ClearCache.ps1 is used as a sample in this article.

  • Deploy Aternity Agent on monitored user devices where the script will be running and trust the certificate of the publisher. The Agent setup automatically sets the Action Policy Execution parameter to Trusted.

  • Download the necessary scripts from the repository. To use the repository, you are required to log in to Aternity Customer Success site. Learn more.
    Script Name Description

    Prepare-RemediationSigning.ps1

    Used to set up a test environment

    Import-RemediationSigningCertificate.ps1

    Used to import the certificate into machine certs stores to establish the trust.

    Sign-RemediationScript.ps1

    Used to sign remediation scripts for running on test devices

    Clean-RemediationSigning.ps1

    Used to clean up all certificates in order to retry the setup from the beginning

    Export-RemediationSigningCertificate.ps1

Procedure

  1. Step 1 Make sure you have the necessary files (see the table above). If not, download them to the signing machine and extract them all to drive C:\.
  2. Step 2 Perform the following just once to set up a test environment ON THE SIGNING MACHINE (where you will sign remediation scripts):
    1. a Start PowerShell using Run as Administrator menu and run the following script:
      Prepare-RemediationSigning.ps1

      This command will generate a self-signed publisher certificate for code signing in the local certs store and export it as a certificate file (.cer). In the certs store, the certificate will have the subject Aternity Remediation Code Signing.

      #On the signing machine
      .\Prepare-RemediationSigning.ps1
      
  3. Step 3 On the signing machine, sign a script:
    # Depending on the environment the following line is not required. It sets the execution policy to be able to execute .ps1 script
    Set-ExecutionPolicy Unrestricted -Scope Process
    #
    Set-Location C:\Aternity\Remediation-Scripts-Library
    .\Prepare-RemediationSigning.ps1
    New-Item -Type Directory Signed
    .\Sign-RemediationScript.ps1 -Source .\Network\Remediation-DNS-ClearCache.ps1 -Destination .\Signed\Remediation-DNS-ClearCache-signed.ps1
    Output example:
    Directory: C:\Aternity\Remediation-Scripts-Library
    
    
    Mode                LastWriteTime         Length Name
    ----                -------------         ------ ----
    -a----         5/1/2019  12:02 PM            812 Aternity-Remediation-Certificate.cer
    
    
  4. Step 4 On the signing machine:
    1. a Sign in to Aternity.
    2. b Create a new remediation action.
    3. c Upload the signed script.
  5. Step 5 Perform the following just once to set up a test environment ON THE USER TESTING MACHINE:
    1. a Create a folder C:\install.
    2. b From the signing machine, copy the certificate Aternity-Remediation-Certificate.cer and the script Import-RemediationSigningCertificate.ps1 to that local folder.
    3. c From this local folder, start PowerShell using Run as Administrator menu and import the certificate.

      The following command will import the certificate into both Root CA and TrustedPublishers certificate stores to establish the trust.

      #On the user test device
      .\Import-RemediationSigningCertificate.ps1
      # Depending on the environment the following line is not required. It sets the execution policy to be able to execute .ps1 scrip
      Set-ExecutionPolicy Unrestricted -Scope Process
      #
      Set-Location c:\install
      .\Import-RemediationSigningCertificate.ps1
    4. d Deploy the Aternity Agent if not already done.
  6. Step 6 On the user test device, trigger the remediation action test in Aternity. Do one of the following:
    • Sign in to Aternity, under the Gear Icon > Remediation, select the action you want to run, open the the row's context menu on the right > , select Run and type the name of the user test device which you want to remediate.

    • Sign in to Aternity, locate the user test device (for example, type the device name in the Search bar), open the Device Events dashboard and run the remediation (select Run Action button).

  7. Step 7 Fix signing issues.
    The execution of the script Sign-RemediationScript.ps1 might return the following error:
    Set-AuthenticodeSignature : Cannot convert 'System.Object[]' to the type
    'System.Security.Cryptography.X509Certificates.X509Certificate2' required by parameter 'Certificate'. Specified method is not supported.
    At C:\Riverbed-Community-Toolkit-master\Aternity\Remediation\Sign-RemediationScript.ps1:27 char:40
    + Set-AuthenticodeSignature -Certificate $cert -FilePath $Destination
    +                                        ~~~~~
        + CategoryInfo          : InvalidArgument: (:) [Set-AuthenticodeSignature], ParameterBindingException
        + FullyQualifiedErrorId : CannotConvertArgument,Microsoft.PowerShell.Commands.SetAuthenticodeSignatureCommand
    

    It happens if the script Prepare-RemediationSigning.ps1 has run multiple times and you have now many certificates with the same subject name. The last version of the script will now give a more explicit message:

    Sign-RemediationScript.ps1 : Cannot choose which certificate to use. Multiple certs found with the same subject: Aternity Remediation Code Signing.
    Please remove extra certs, keep only one cert and retry.
    You can delete all existing using .\Clean-RemediationSigning.ps1
    At line:1 char:1
    + .\Sign-RemediationScript.ps1 -subject Aternity Remediation Code Signing
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException
        + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Sign-RemediationScript.ps1
    

    To fix, you can clean up all certificates with the following command and retry the setup from the beginning using Prepare-RemediationSigning.ps1, Sign-RemediationScript.ps1 and import new cert on the test devices.

    .\Clean-RemediationSigning.ps1