Sign and Test Remediation Scripts

This article explains how to set up a quick test environment and sign new remediation scripts.

When you have a Remediation script ready (for example, Remediation-DNS-ClearCache.ps1), you have to sign it before configuring Remediation action in Aternity. The monitored user device where it will be run must have Aternity Agent installed and trust the certificate of the publisher. The Agent setup by default sets Action Policy Execution to Trusted.

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 line would all to execute any script .ps1 file in the current PowerShell session:
Set-ExecutionPolicy Unrestricted -Scope Process

Before you begin

  • Create PowerShell scripts (learn more).

  • Learn how to return an error status in the remediation script: The SetFailed method returns an error with the message in the parameter. [ActionExtensionsMethods.ActionExtensionsMethods]::SetFailed("message")

Procedure

  1. Step 1 Set up a test environment (you do this just once).
    1. a On the signing machine (computer where you are going to sign Remediation scripts), run the script Prepare-RemediationSigning.ps1 just once. It 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
      
      Output example:
      Directory: C:\Aternity\Remediation-Scripts-Library
      
      
      Mode                LastWriteTime         Length Name
      ----                -------------         ------ ----
      -a----         5/1/2019  12:02 PM            812 Aternity-Remediation-Certificate.cer
      
      
    2. b On the test user device where the Aternity Agent is installed, copy the certificate file (.cer) and the script Import-RemediationSigningCertificate.ps1 to a local directory. Then from this local directory execute the Powershell script with administrator privileges (i.e. launch Powershell with Run as Administrator). It will import the certificate into both Root CA and TrustedPublishers machine certs stores to establish the trust.
      #On the user test device
      .\Import-RemediationSigningCertificate.ps1
  2. Step 2 Sign a new script.

    On the machine prepared for signing, the Powershell script Sign-RemediationScript.ps1 can sign remediation scripts. It uses the certificate created previously 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 in a Aternity remediation action 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
    
  3. Step 3 Execute the action in 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 (click Run Action button).

  4. Step 4 Test Remediation.
    1. a (On the signing machine): Download the kit archive and extract all in C:\
    2. b Launch PowerShell as Administrator to prepare signing cert and 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
    3. c Sign in to Aternity, create a new remediation action for DNS-ClearCache and upload the signed script.
    4. d (On the user test device): Create a folder C:\install and retrieve from the signing machine the certificate Aternity-Remediation-Certificate.cer and the script Import-RemediationSigningCertificate.ps1 into that folder.
    5. e Open PowerShell as Administrator and import the certificate.
      # 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
    6. f Install the Aternity Agent (if not already done).
    7. g (In Aternity): Under the Gear Icon > Remediation, open the the row's context menu on the right > for DNS-ClearCache, select Run and type the name of the user test device where you want to apply the remediation.
  5. Step 5 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