In this section:
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:
- In the Rules ribbon, select Add Rule.
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.
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.
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.
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.
- 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.
- Select Click here to edit the script. Click Import to import an existing script.
- 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.
- 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.
Click Click here to edit the script.
The Configure this Scripted Rule dialog displays.
- In the Script tab, add or amend the script to be used when your users log on.
- In the Options tab, select the script execution setting from the list of available options in the Define the execution settings section.
- To specify the script time settings, select the appropriate options in the Define the script time settings section.
- Click OK.
The following VBscript demonstrates how to control the applications to which a user has access.
’Name of Filter scan expected to pass
ExpectedFilter = "FWALL"
’Get Server Name
Set objNTinfo = CreateObject ("WinNTSystemInfo")
ServerName = lcase (objNTInfo.ComputerName)
’Set initial return value
ScriptedRule = False
’Create MetaFrame Session Object
Set MFSession = Createobject ("MetaFrameCOM.MetaFrameSession")
’Initialize the session filters for this session
For Each x in MFSession.SmartAccessFilters
’return true if our filter is found
If x = ExpectedFilter Then
AMScriptRule.Log "SmartAccessFilter match found."
The following VBscript can be used to determine if a computer is in a Computer Organizational Unit:
ScriptedRule = vbFalse
strCompName = AMScriptRule.StationName
Set oRootDSE = GetObject("LDAP://RootDSE")
strDNSDomain = oRootDSE.Get("DefaultNamingContext")
Set oOU = GetObject("LDAP://OU=TheOUyouAreSearching,OU=Parent,OU=Parent," & strDNSDomain)
For each member in oOU
If UCase(strCompName) = UCase(member.CN) Then
ScriptedRule = vbTrue
The following sample VBScript shows the main components of a script and demonstrates how to access information about the username of the user logging on to the system, and match with a specific domain and organizational unit:
'Get the username of the user logging in (also works when running as SYSTEM)
strUserName = AMScriptRule.UserName
'Get the domain of the user logging in (also works when running as SYSTEM)
strUserDomain = AMScriptRule.UserDomain
'Look up user environment variables (when running as SYSTEM, only SYSTEM variables are available)
strClientName = AMScriptRule.ExpandEnvironment ("%ClientName%")
'Log the output
AMScriptRule.Log strUserName & " logged in on " & strClientName
'Check if the user is a member of the domain
If strUserdomain = "MyDomain" Then
'If so, see if the user is in the MyOU OU
Set objOU = GetObject ("LDAP://ou=MyOU,dc=MyDomain,dc=com")
objOU.Filter = Array("user")
For Each objUser In objOU
'Check if there is a match with the user logging on
If objUser.sAMAccountName = strUserName Then
'if there is, then set the function to True
MyScript = True
'Unless there is a username match, the function defaults to False
The following sample Windows PowerShell script shows the main components of a script and demonstrates how to access information about the username of the user logging on to the system, and match with a specific domain and organizational unit:
#Script checks if the current user is a member of the OU specified
# Return 0 if TRUE
# 1 otherwise
$logonuser = $env:username
$bindpt = [adsi] "LDAP://OU=TS_Users,OU=Users,OU=MyUser,OU=MyOU,DC=MyDomain,DC=com"
$users = New-Object System.DirectoryServices.DirectorySearcher $bindpt
$users.Filter = "(&(objectClass=User)(sAMAccountName=$logonuser))"
$obj = $users.FindOne()
if($obj -eq $null)
#" Not a Member"