Introduction

UI Search is a TMG feature designed to help administrators instantly filter Firewall Policy rules according to a search criteria string. This feature resembles the "Search Inbox" in Microsoft Outlook and is generally designed to deliver similar functionality.

 

UI1

Usage – visual filtering

UI search can be used to filter rules according to the attributes shown in the management console as column names. All these attributes are supported for localized version of TMG in the very same form as they're shown in UI.

A simple example would be finding all deny rules (Search for “Action:Deny”). For an empty user policy combined with a default system policy, the resulting set of rules will look the following way:

UI2

Now, if we'd like to see only those rules that deny access to HTTP protocol, search for: “Action:deny protocol:http”. The query and result would look like this:

UI3

We get a single rule which is a subset of the previous query. Here we can see some potential ambiguity: when filtering on “HTTP” both “HTTP” and “HTTPS” will be found since the value is matched as a substring.

Another nice example would be searching for rules governing traffic from external network to local host (search for ‘from:external to:”local host”’):

clip_image008

Usage – search in depth

The same search can be used to find rules where any of their sub-properties fit the search criteria. A good example of that would be searching for rules according to a protocol description:

Consider the following protocol:

clip_image010

This protocol got a twin brother: “System Center Operation Manager Agent Installation”. If we search for 'Description:"Microsoft System Center Operation Manager 2007 Agent"' or just "Microsoft System Center Operation Manager 2007 Agent", we get the two rules referring these protocols:

clip_image012

Another example is filtering rules that deal with download.windowsupdate.com URL. In the example below the URL is part of the “Microsoft Update Sites” Domain name set.

clip_image014

And another one:

clip_image016

Here we note that all rules except the last one were matched according to their description, while the last one is matched according to its users. We can differentiate the result by more precise queries (‘user:”network service”’):

clip_image018

and (‘description:”network service”’)

clip_image020

Queries syntax

Warning: The following sections contains technical mambo jambo. Use at your own risk!

Documentation of the syntax the query follows is available in http://technet.microsoft.com/en-us/library/dd897127.aspx

The search string uses the following grammar:

S -> CriterionList

CriterionList -> CriterionList Criterion | Criterion

Criterion -> Token CLN Token | Token

Token -> TokenType1| DBQ TokenType2 DBQ | SLQ TokenType3 SLQ

Tokens:

CLN -> :

DBQ -> “  //double quote

SLQ -> ‘  //single quote

TokenType1 -> [^ \t\n:\"\']* //sequence of characters NOT containing spaces, tabs, caret returns, colons, double and single quotes

TokenType2 -> [^\"]  //sequence of characters NOT containing double quotes

TokenType3 -> [^\’]  //sequence of characters NOT containing single quotes

Please note that double or single quotes must be used when the search string contains spaces, otherwise it will be processed as two separate search strings.

Implementation details

There are situations in which a search executed from the UI will return more matches, than the exact same search executed using the COM interface. This happens because the UI initializes the full COM sub-tree for rule objects, creating all underlying children (including those that are implicitly set to defaults and are created by demand), while direct search through the COM interface won't see the default children and won't perform lookup on them. However, this will never happen for the matching object that were created or modified by a user.

 

Written by: Dima Datsenko, Software Design Engineer, Forefront Threat Management Gateway

Reviewed by: Ori Yosefi, Senior Program Manager, Forefront Threat Management Gateway