Agent Script Enforcement Profile

This section provides the following information:

Introduction
Configuring the Agent Script Enforcement Profile
Configuring Agent Script Enforcement Attributes
Viewing the Configuration Summary

Introduction

Agent Script Enforcement profiles allow execution of custom scripts on endpoint devices as part of agent enforcement. All the details of custom script configuration, such as the path of the custom script, the command to be executed, execution level, and so on, are configured in the Agent Script Enforcement profile.

You can select multiple Agent Script Enforcement Profiles in a rule in an enforcement profile. OnGuard Agent executes them one after another.

The Agent Script Enforcement profile is currently supported only with the OnGuard Agent for Windows.

OnGuard Agent applies the Agent Script Enforcement profile (that is, it executes a custom script) after first applying Agent Enforcement profiles (that is, after Agent Bounce is executed, if configured).

While applying an Agent Script Enforcement profile, OnGuard Agent does not check to see if a script is already running. It is possible for OnGuard Agent to launch the script multiple times if a previously launched script is still running. This can occur if OnGuard Agent performs multiple health checks (either manually triggered or caused by a change in health status). The script exits after performing its task.

Mandatory Agent Script Attributes

The following attributes are mandatory when configuring Agent Script Enforcement:

Path of the Script
Command to Execute
Execution Level

Optional Agent Script Attributes

The following attributes are optional when configuring Agent Script Enforcement:

SHA256 Checksum
Wait Time (Seconds) Before Executing Script
Pass Health Evaluation Results to Script
Success Message
Failure Message
Progress Message
Description
Download URL

Configuring the Agent Script Enforcement Profile

To configure an Agent Script Enforcement profile:

1. Navigate to Configuration > Enforcement > Profiles.

The Enforcement Profiles page opens.

2. Click Add.

The Add Enforcement Profiles dialog opens to the Profile tab.

Figure 1: Agent Script Enforcement > Profile Dialog

3. Specify the Add Agent Script Enforcement > Profile parameters as described in the following table:
Table 1: Add Agent Script Enforcement > Profile Parameters

Parameter

Action/Description

Template

Select the Agent Script Enforcement template.

Name

Enter the name of the enforcement profile.

Description

Optionally, enter a description of the enforcement profile (recommended).

Type

This field is populated automatically with type Agent.

Action

This parameter is disabled because it is not applicable to the Agent Script Enforcement Profile.

Device Group List

This parameter is disabled because it is not applicable to the Agent Script Enforcement Profile.

Add new Device Group

This parameter is disabled because it is not applicable to the Agent Script Enforcement Profile.

Configuring Agent Script Enforcement Attributes

Use the Attributes tab to configure the attribute name and attribute value for each attribute you add.

The following figure displays the Agent Enforcement > Attributes dialog:

Figure 2: Agent Script Enforcement > Attributes Dialog

Specify the Agent Script Enforcement > Attributes parameters as described in the following table:

Table 2: Agent Script Enforcement > Attributes Parameters

Attribute

Action/Description

Attribute Name

Select one of the following attribute names:

Path of the Script: Complete the path of the script/program, including the filename. This attribute checks for the existence of a file on an endpoint device and also verifies the SHA256 Checksum.
Command to Execute: Specify the complete command that OnGuard Agent should execute. You can use the command to launch scripts or pass command line arguments.
For example, to launch VBScript (InstallHotfixes.vbs) and pass All as an argument, you would enter the following:
cscript /nologo C:\Test\InstallHotfixes.vbs All
If it is not required to pass arguments, set the value of this attribute to the same value specified for Path of the Script.
SHA256 Checksum: Specify the SHA256 checksum of the script/program. This attribute accepts comma-separated multiple SHA256 checksums to allow execution of different versions of same script/program.
Execution Level: The attribute values are: User and System.
To launch the script/program as the current logged-on user, select User.
To launch the script/program as the system user with admin rights, select System.
Wait Time (Seconds) Before Executing Script: Specify the time (in seconds) after which OnGuard Agent should launch the script/program.
When Wait Time Before Executing Script is configured, the OnGuard Agent does not process events such as Interface Up/Interface Down and health changes during the wait time.
Pass Health Evaluation Results to Script: Check the check box (which sets the value to true) to enable OnGuard Agent to pass health evaluation results to the script/program as an argument. The default is false.
When the Pass Health Evaluation Results to Script attribute is set to true, OnGuard Agent passes health evaluation results to the script in a URL Encoded JSON format.
URL Encode replaces double quotes, spaces, and Unicode characters with their ASCII value in %XX format. For example, spaces are replaced by %20 and double quotes are replaced by %22.
Success Message: Enter the message to be shown to the end user when the script/program is launched successfully.
Failure Message: Enter the message to be shown to the end user when execution of the script/program fails.
Progress Message: This message will be shown on the OnGuard Progress Page (see Creating OnGuard Custom Web Pages) while OnGuard Agent is executing the custom script and states what action is being performed.
Description: Provides a description of the custom UI window or script.
Download URL: If the script/program configured in the Path of the Script attribute is not present on the client machine, enter the URL of the remote server from which OnGuard Agent can download the script/program.
OnGuard Agent supports downloading scripts only from HTTP and HTTPS URLs. For HTTPS URLs, OnGuard skips server certificate verification.
Also, OnGuard Agent does not support downloading files from URLs that require credentials.

Attribute Value

The Attribute Value set depends on the selected Attribute Name.

Viewing the Configuration Summary

The Summary page summarizes the parameters configured in the Profile and Attribute tabs.

The following figure displays the Agent Script Enforcement > Summary page:

Figure 3: Agent Script Enforcement > Summary Dialog