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 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 the script will be running must have Aternity Agent installed and trust the certificate of the publisher. The Agent setup automatically sets the Action Policy Execution parameter to Trusted.

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.

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 this script just once:
      Prepare-RemediationSigning.ps1

      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 user test 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 (launch PowerShell using Run as Administrator menu). 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 signing machine, 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 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
    
  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 (select 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 using Run as Administrator menu 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 Deploy 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