About Pre-Actions and Post-Actions

Field

Description

Action Name

The name of the software that you want to install.

Note: You can choose to enable or disable the Bypass Execution Policy while adding the Install Software pre-action or post-action to a Windows deployment job.

When you click the Click here link, you are navigated to the Configuration > Setup tab and then you can enable or disable the Bypass Execution Policy. For more information, see Bypass Execution Policy.

URL

Enter the download URL from where the software installer will be downloaded.
If you have configured the Qualys Gateway Services, the agent will proxy through QGS.

File Checksum/Hash

The agent validates the integrity of the downloaded file by comparing it to the hash that you provide. You can use publicly available methods, such as certUtil, to generate SHA256 for a file.

Detection Script (optional)

The detection script is used to determine whether to install the software on a specific asset. The script checks the pre-conditions that must be met for the software to be installed or updated.

The script returns one of the following codes after execution:

- Success, to indicate that the software can be installed on the asset: 0
- Failure, abort the action and not install the software: Nonzero (except 10 and 11)

Install Script

This script performs the installation. The installer file downloaded by our agent is stored at the following location: %ProgramData%\Qualys\QualysAgent\PatchManagement\PatchDownloads\

You can check details in the log to understand why an action failed.

The script returns one of the following codes after execution:

- Success, the software was installed: 0
- Failure, the software failed to install: Nonzero (except 10 and 11)
- Reboot needed
    – Success with reboot: 10
    – Failure with reboot: 11

You can use the Write-Host command in the Powershell script to provide a custom message that is returned in case the action fails.

Note that if the script indicates that a reboot is required, the agent uses the job reboot preferences to enforce a reboot. Only one reboot is enforced for a patch job.

Field

Description

Script Name

Enter the script name.

Note: You can choose to enable or disable the Bypass Execution Policy while adding the Run Script pre-action or post-action to a Windows deployment job.

When you click the Click here link, you are navigated to the Configuration > Setup tab and then you can enable or disable the Bypass Execution Policy. For more information, see Bypass Execution Policy.

Custom Script

You can enter a custom script that you want to execute on the assets.

- For Windows deployment job, you can only enter a Powershell script. The script returns one of the following codes after execution:
 a) Success, the custom script was executed successfully: 0
 b) Failure, the custom script failed to execute: Nonzero

You can use the Write-Host command in the Powershell script to provide a custom message that is returned in case the action fails.

- For Linux deployment job, you can only enter a Shell script.

Field

Description

Key PATH ending with Key name

Enter the key path, including the key name.

You can change the following registry keys:

 - HKEY_CURRENT_USER

 - HKEY_USERS

 - HKEY_LOCAL_MACHINE

 - HKEY_CLASSES_ROOT

 - HKEY_CURRENT_CONFIG

Note the following important points:

 - You cannot use a forward slash (/).

 - The path should not end with a backslash (\).

 - The path must contain at least one directory after the root path.

Registry Type

Select the registry key type.

 - REG_BINARY

 - REG_DWORD

 - REG_EXPAND_SZ

 - REG_MULTI_SZ

 - REG_QWORD

 - REG_SZ

Note: Only numerical values are accepted for the REG_BINARY, REG_DWORD, and REG_QWORD registry key type.

Registry Value name

Based on the registry type selected, enter the registry value name.

Registry Value data

Based on the registry type selected, enter the registry value data.

Add New Key

Select one of the following options:

 - True: if you want to add the registry key in case it doesn't exist.

 - False: if you don't want to take any action in case the registry key doesn't exist.

Field

Description

Action Name

Enter an action name.

Example: Uninstall Notepad++ 8.5

Uninstall Registry Key

Enter the registry key path containing the registry value name.

For example, for putty, HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\{1E0D5689-40F1-4E46-ABBB-EAAC68B5CD89}.

Software Display Name

Enter the value data for the value name DisplayName under the registry key path.

The value data is the exact name of the software that you want to uninstall.

Software Display Version

Enter the exact value data for the value name Version under the Registry key path. The value data is the version of the software that you want to uninstall.

Note: If you don't specify a version, then any installed version of the software will be uninstalled.

Uninstall Software Version Match

The Uninstall Software Version Match field is shown only when you enter details in the Software Display Version field.

Select Equals operator. With this release, we are supporting the Equals operator only, which is the default operator.

Note: When the Equals operator is selected, the software is uninstalled only if the Software Display Version that you provided matches the value data for the value name Version under the registry key.

***********************************************************************

# Sample pre-detection script for Qualys Patch Manager       *

#                                                            *

#     This sample script demonstrate detection of installed  *

#     software. It returns 0 if software can be installed    *

#     and returns 1 if installation is not required          *

#                                                            *

#                                                            *

#       Return Code                                          *

#                                                            *

#        0 - success                                         *

#        1 - failure                                         *

#*************************************************************

# required parameter

[string]$SoftwareName = "notepad++*"

[string]$SoftwareVersion = "8.1.2"

# Print OS info for asset information and troubleshooting

Write-Host "Gathering OS Information..."

$osInfo = Get-CimInstance Win32_OperatingSystem | Select-Object Caption, Version, ServicePackMajorVersion, OSArchitecture, CSName

$properties = @{

    Caption                 = $osInfo.Caption

    Version                 = $osInfo.Version

    ServicePackMajorVersion = $osInfo.ServicePackMajorVersion

    OSArchitecture          = $osInfo.OSArchitecture

    HostName                = $osInfo.CSNAme

}

$obj = New-Object -TypeName PSObject -Property $properties

Write-Output $obj

Write-Host "Looking for package installation...`n"

# Check install key in both wow64 and normal path. Application can be either 32-bit or 64-bit.

$32bit = Get-ItemProperty HKLM:\SOFTWARE\Wow6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*

$64bit = Get-ItemProperty HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*

$programs = $32bit + $64bit

$packageFound = $false

foreach ($program in $programs) {

    $program = Write-Output $program | Where-Object Displayname -like $SoftwareName

    if ($null -ne $program.DisplayName) {

        $LastModified = (Get-Item $program.uninstallstring).lastwritetime

        $properties = @{

            ProgramName     = $program.DisplayName

            Publisher       = $program.Publisher

            Version         = $program.DisplayVersion

            UninstallString = $program.UninstallString

            LastModified    = $LastModified

        }

        $package = New-Object -TypeName PSObject -Property $properties

        Write-Output $package

        $packageFound = $true

        break;

    }

}

if ($packageFound -eq $false) {

    Write-Host "No installed package found"

    # Package needs to be isntalled

    exit 0

}

Write-Host "Checking installed software version..."

[System.Version] $installedVersion = $package.Version

[System.Version] $ExpectedVersion = $SoftwareVersion

if ($installedVersion -lt $ExpectedVersion) {

    Write-Host "Installed software is older then required version. Patch upgrade needed"

    exit 0

}

else {

    Write-Host "Installed software is up to date."

    exit 1

}>

#*************************************************************

# Sample install script for Qualys Patch Manager             *

#     This sample script demonstrate installation of         *

#     software. It returns 0 if software is installed        *

#     successfully and returns 1 if installation fails.      *

#       Return Code                                          *

#        0 - success                                         *

#        1 - failure                                         *

#*************************************************************

[string]$PackageName = "npp.8.1.2.Installer.x64.exe"

[string]$InstallerLocation = $Env:ProgramData + "\Qualys\QualysAgent\PatchManagement\PatchDownloads\"

[string]$Arguments = "/S"

#set this 1 if reboot is required after package installation

[int]$RebootFlag = 1

function Get-QualysScriptReturn {

    param (

        [ValidateRange(0, 1)]

        [Int]

        $Success_Code,

        [ValidateRange(0, 1)]

        [Int]

        $RebootFlag

    )

    return $Success_Code + ($RebootFlag * 10)

}

function Start-Program {

    param (

        [ValidateNotNullOrEmpty()]

        [string]

        $ProgramFullPath,

        [Parameter(Mandatory = $false)]

        [string]

        $Arguments        

    )

    try {   

        $pinfo = New-Object System.Diagnostics.ProcessStartInfo

        $pinfo.FileName = $ProgramFullPath

        $pinfo.RedirectStandardError = $true

        $pinfo.RedirectStandardOutput = $true

        $pinfo.UseShellExecute = $false

        if ($null -ne $Arguments) {

            $pinfo.Arguments = $Arguments

        }    

        $pinfo.WorkingDirectory = Get-Location

        $p = New-Object System.Diagnostics.Process

        $p.StartInfo = $pinfo

        $p.Start() | Out-Null

        $p.WaitForExit()

        $stdout = $p.StandardOutput.ReadToEnd()

        $stderr = $p.StandardError.ReadToEnd()

        Write-Host "Process Stdout:`n $stdout"

        Write-Host "Process Stderr:`n $stderr"

        Write-Host "exit code: "$p.ExitCode

        return $p.ExitCode

    }

    catch {

        Write-Host -ForegroundColor DarkRed "Failed to execute program" $_.Exception.Message

        return 1

    }

}

Write-Host "Running install script to install -"$PackageName

Write-Host "Looking package installer..."

$InstallerFullPath = $InstallerLocation + $PackageName

if (Test-Path $InstallerFullPath) {

    Write-Host "Found installer at "$InstallerFullPath

}

else {

    Write-Host "Installer does not exist at "$InstallerFullPath

    exit 1;

}

Write-Host "Launching installer..."

$ReturnCode = Start-Program $InstallerFullPath $Arguments

if ($ReturnCode -eq 0) {

    Write-Host -ForegroundColor Green "Installation successfull..."

    exit Get-QualysScriptReturn 0 $RebootFlag;

}

else {

    Write-Host -ForegroundColor DarkRed "Installation failed. See output for more details."

    exit 1

}

#*************************************************************

#     Sample custom script for Qualys Patch Manager          *

#                                                            *

#     This sample script checks whether a specific file      *

#     (pc.txt) already exists in a particular folder;        *

#   if not, it generates a list of all AD computers and      *

#   saves it to a new file named pc.txt. It returns 0 if      *

#     file does not exists and latest AD computer list is    *

#   saved and returns 1 if file already exists.              *

#                                                            *

#       Return Code                                          *

#        0 - success                                         *

#        1 - failure                                         *

#*************************************************************

  #create array of text files

  $files=Get-ChildItem C:\data\*.txt | select -expand fullname

  #check if file exists inside the array

  $files -match "pc.txt"

  #if matching return “True” key then exit, if “False” then create a report

  if($files -eq 'False'){

    Get-ADComputer -Filter * | Export-Csv -Path C:\data\pc.txt

exit 0

  }

  else{

     exit 1

  }