Agent Script Enforcement Profile

Agent Script Enforcement profiles allows Policy Manager to execute 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 policy. OnGuard Agent executes them one after another.

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.

 

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

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 Uniform Resource Locator. URL is a global address used for locating web resources on the Internet.

Script Execution Timeout (Seconds)

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 the Add link. The Add Enforcement Profiles dialog opens.

3. From the Template drop-down, select Agent Script Enforcement.

Figure 1  Agent Script Enforcement > Profile Configuration Dialog

4. 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 /
Device Group List

These parameters are disabled because they are 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 Script Enforcement > Attributes dialog:

Figure 2  Agent Script Enforcement > Attributes Configuration Dialog

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

Table 2: Agent Script Enforcement > Attributes Parameters

Attribute

Action/Description

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 or program. This attribute accepts comma-separated multiple SHA256 checksums to allow execution of different versions of the same script or 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 Uniform Resource Locator. URL is a global address used for locating web resources on the Internet. Encoded JSON JavaScript Object Notation. JSON is an open-standard, language-independent, lightweight data-interchange format used to transmit data objects consisting of attribute–value pairs. JSON uses a "self-describing" text format that is easy for humans to read and write, and that can be used as a data format by any programming language. format.

URL Uniform Resource Locator. URL is a global address used for locating web resources on the Internet. Encode replaces double quotes, spaces, and Unicode characters with their ASCII American Standard Code for Information Interchange. An ASCII code is a numerical representation of a character or an action. 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 or program is launched successfully.

Failure Message

Enter the message to be shown to the end user when execution of the script or program fails.

Progress Message

This message will be shown on the OnGuard Progress Page (see OnGuard Settings and Agent Library Updates) while OnGuard Agent is executing the custom script and states what action is being performed.

Description

Provides a description of the custom user interface window or script.

Download URL Uniform Resource Locator. URL is a global address used for locating web resources on the Internet.

If the script or program configured in the Path of the Script attribute is not present on the client machine, enter the URL Uniform Resource Locator. URL is a global address used for locating web resources on the Internet. of the remote server from which OnGuard Agent can download the script or program.

OnGuard Agent supports downloading scripts only from HTTP Hypertext Transfer Protocol. The HTTP is an application protocol to transfer data over the web. The HTTP protocol defines how messages are formatted and transmitted, and the actions that the w servers and browsers should take in response to various commands. and HTTPS Hypertext Transfer Protocol Secure. HTTPS is a variant of the HTTP that adds a layer of security on the data in transit through a secure socket layer or transport layer security protocol connection. URLs Uniform Resource Locator. URL is a global address used for locating web resources on the Internet..

For HTTPS Hypertext Transfer Protocol Secure. HTTPS is a variant of the HTTP that adds a layer of security on the data in transit through a secure socket layer or transport layer security protocol connection. URLs Uniform Resource Locator. URL is a global address used for locating web resources on the Internet., OnGuard skips server certificate verification.

NOTE: OnGuard Agent does not support downloading files from URLs Uniform Resource Locator. URL is a global address used for locating web resources on the Internet. that require credentials.

Script Execution Timeout (Seconds)

Specify the Script Execution Timeout attribute value in the number of seconds. The value must be an integer between 60 and 3600.

When this attribute is configured, OnGuard Agent waits for the specified time for the custom script to finish execution. If the custom script does not finish execution within the specified time, OnGuard Agent returns failure for that script.

 

When this attribute is not configured, OnGuard Agent uses varying timeout values, depending upon whether or not custom remediation is enabled.

When Custom Remediation is enabled: the default value is 20 minutes.

When Custom Remediation is not enabled: 1 minute.

6. Click Save.

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