This page refers to an older version of the product.
View the current version of the online Help.

Scripted Rules

In this section:

• About Scripted Rules
• VBScripts
• Windows PowerShell Scripts
• Add a Scripted Rule
• Edit a Scripted Rule
• Sample Scripts

About Scripted Rules

Scripted rules allow custom rules to be created using Windows PowerShell or VB Scripts. The success or failure of the Script determines whether the security level, Allowed Items, and Denied Items that are part of the rule apply to the user.

Scripted rules can take advantage of any interface accessible via PowerShell or VBScript, such as COM (Component Object Model) and each script is evaluated under the following circumstances:

• When a new configuration is deployed to the computer.
• When a user logs on.

You create and edit scripts in the Scripted Rule dialog, which you access as follows:

1. In the Rules ribbon, select Add Rule.

2. In the drop down menu, select Scripted Rule.

   The Scripted Rule work area displays.

You can define when the script is to be run using the following Scripted Rule Options:

• Run script once per logon session as the logged on user - The script runs for each user logging on. Settings are only applied for the duration of the user session. Note that the script will also run if the desktop is unlocked.
• Run script once per logon session as the SYSTEM user - The script runs with SYSTEM account permissions once for each user logging on. Settings are only applied for the duration of the user session.

• Run script once per computer as the SYSTEM user - The script runs with SYSTEM account permission once at computer startup. Settings are applied to all user sessions until the computer restarts, the Application Control agent restarts or there is a configuration change.

  Caution: Running scripts as the SYSTEM user can cause serious damage to your computer and should only be enabled by experienced script authors.

• Do not execute script until user logon is complete - Select to prevent the script from running until user logon is complete.

• Wait for <n> seconds before script timeout - Allows you to specify the number of seconds to allow a script to continue running before the script times out. A setting of zero (0) seconds prevents the script timeout. If a timeout occurs the result is fail and settings cannot be applied.

VBScripts

Each script is run within a hosted script engine allowing greater control over the script execution whilst providing a high degree of input and output control.

• No VBS file is used.
• No separate process is spawned.

A script must be written as a function and can contain many functions, but a main start function must be specified. The start function is run by the Application Control agent and can be used to call other functions.

The AMScriptRule COM object is built into the scripting engine and provides access to the following methods:

• strUsername = AMScriptRule.UserName
• strUserdomain = AMScriptRule.UserDomain
• strSessionid = AMScriptRule.SessionID

• strStationname = AMScriptRule.WinStation

  The Microsoft standard in this instance means that WinStation returns the value of the name of the Terminal Services Session, which is determined by the type of session with typical values being ’Console’ or ’RDP-Tcp#34’, instead of the Window Station name which is typically WinSta0.

The AMScriptRule COM object also includes the following methods:

• strLog = AMScriptRule.Log "My Log Statement"

  Allows you to output logging strings to the agent log file for use with debugging scripted rules.

• strEnvironmentvar = AMScriptRule.ExpandEnvironment ("%MyEnvironmentVariables%")

  Expands environment variables of the user running the script.

Using WScript. shell to expand environment variables only returns SYSTEM variables.

Windows PowerShell Scripts

If the script returns (exits) with a value of 0, the script will pass and the rules are applied. If any non-zero value is returned, the script will fail and the rules will not apply.

Each PowerShell script is executed in an instance of PowerShell.exe and as such Application Control neither enforces nor adds any specific syntax – all correctly formed PowerShell will work.

PowerShell must be installed on any endpoints that will be using the script.

Add a Scripted Rule

1. Click the Add Rule drop-down arrow on the Rules ribbon and select Scripted Rule.

   A new rule is added to the All Scripted Rules work area. The Scripted Rule dialog displays.

2. To enter a script, do one of the following:
   • Type the script in the Current Script area.
   • Open an existing script in a script editor and copy/cut the content and paste.
3. Select Click here to edit the script. Click Import to import an existing script.

Edit a Scripted Rule

1. Use the Scripted Rule dialog to create and maintain rules based on custom VB and PowerShell Scripts that are run whenever a user logs on.
2. To open the Scripted Rule dialog for a specific rule, you can either:
   • Navigate to the scripted rule in the navigation pane and select it.

   • Select the Rules node in the navigation tree. In the All Rules dialog, double-click the rule that you want to edit.

   The Scripted Rule dialog displays.

3. Click Click here to edit the script.

   The Configure this Scripted Rule dialog displays.

4. In the Script tab, add or amend the script to be used when your users log on.
5. In the Options tab, select the script execution setting from the list of available options in the Define the execution settings section.
6. To specify the script time settings, select the appropriate options in the Define the script time settings section.
7. Click OK.

Sample scripts

Related topics

Rules