Detective agency

As you probably know, one of UAG’s most important features is the endpoint detection mechanism. This engine runs a special detection script on connecting clients, which reports back to UAG certain properties of the endpoint. Then, the administrator can configure the UAG to reject or accept certain endpoints based on the detected properties.

A lesser known aspect of endpoint detection is the ability to create custom detection scripts, which can detect properties not originally covered by the default detection script. Our documentation discusses how to create a script, but provides little detail as to how they actually work. Here’s the low-down how-to!

The detection mechanism works by running a special VB-Script file on the client endpoint, so the customize it, you need to create your own script. What this script does is collect information, and send it back to UAG by populating certain variables, and then, UAG can use these variables as a basis for a decision as to ACCEPT or REJECT that endpoint. The process for creating a custom detection is:

1. Decide what values you want to collect from the endpoint

2. Write your custom script, and put it in the designated folder on UAG

3. Configure UAG to use that script

4. Write a custom endpoint policy to evaluate the custom values

5. Assign the custom policy to your trunks and applications

The values that you can collect may be anything you want, as long as you can collect it on the endpoint. You then send these values to UAG by using the following syntax:

Results("System_Windows_Version") = Whale.WindowsVersion

Results("Network_Domains_NetBIOS")=Whale.System.MachineDomain

What this does is query the special COM object that UAG installs on the client, and then put the result in the parameter list using the RESULTS function. The above are taken directly from the default detection script (which you can find and on your own server under <UAG Path>\von\InternalSite\Detection.vbs, but you could also use your own parameter names. You do need to make sure that the parameter names do not contain spaces, as this makes writing the endpoint policy a bit of a problem.

Another thing that’s important to note is that the detection script runs on the client endpoint under the context of the browser, and as such, it is restricted by default as part of the browser’s design. This means that your script can’t just use any old COM objects that you can use when running regular scripts on your computer. For example, you can’t use the FileSystemObject object and methods to read or write files to the client system. However, the built in COM object WHALE does provide some useful functionality. Here are some of methods you can use. Please refer to the default detection script to read more about how they work:

So, for example, if you want to check if certain software is installed on an endpoint, all you have to do is figure out the location of a file that would indicate that the application is there, and use the Whale.FileSystem.Exist method to check it. Alternatively, if you know a specific registry key that indicates the software is there, you can look for that using the Whale.Registry.RegRead method. Ultimately, you need to keep in mind that your control of the user’s system is limited, and all of these values can be spoofed by an advanced and savvy user, so it’s worth taking that into account.

To debug your script, you can use the command Whale.DebugEcho, like this:

Whale.DebugEcho "Starting detection at " & now

However, this is not visible to the user…the echo is used within a client component trace, if one is turned on. To provide you with simple on-screen output, simple use the MSGBOX standard VBScript command. Once your script is ready, or at least starting to take shape, the next step is to put it on the UAG server. To do so, place it under <UAG Folder>\von\InternalSite\CustomUpdate. Now, you need to let UAG know that it is supposed to use it. To do this, create a text file with the following syntax:

Save the file under <UAG Path>\von\InternalSite\inc\CustomUpdate, and name it according to your trunk’s name and type, based on the following template:

<TrunkName><https:1/http:0>Detect.inc

For example, If you are creating this for an HTTP trunk named “publicportal”, name the file “publicportal0Detect.inc”.

Now that the files are all in place, you can activate your configuration, and test the script. Any MSGBOX command will pop-up on the client during the detection, and the resulting parameters will be reported to the session manager. You can open the session in the UAG Web Monitor, and go to the PARAMETERS page, and see the values reported by your script. Note that the default script also runs, so you will see the values reported by it, in addition to yours.

If your values are reported as expected, the next step is to create a custom endpoint policy that looks for these values and acts on them. Keep in mind that an endpoint policy is just a collection of values and Boolean operators – it’s not a real script. Such a policy is evaluated by UAG, and the variables in it are replaced by values collected from the endpoint. Once collected, the server evaluates the “total” value of the policy, and will allow the user access if they evaluate to a Boolean “1” (or True).

For example, let’s say you want to allow access only to computer who have Office 2007 installed. To do this, you might check if the file winword.exe exists. In a policy, this would look like this:

Results(“Office2007_installed”) = Whale.FileSystem.Exist (“c:\Program Files\Microsoft Office\Office12\WINWORD.EXE”)

Then, you would create a simple endpoint policy saying simply:

Then, assign that policy to an application, or to the trunk itself! You could also go further and check the version of the file, or look for certain keys under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0 to see other properties of office…it’s really up to you how deep you want to go into this.

Blog post written by Ben Ari