Configuring Add-ins

Forefront TMG can be extended by add-ins, whose configuration settings can be accessed through the FPCExtensions object. Forefront TMG add-ins include application filters, which are represented by elements of the FPCApplicationFilters collection, and Web filters, which are represented by elements of the FPCWebFilters collection.

Each FPCApplicationFilter object or FPCWebFilter object representing an add-in is associated with a globally unique identifiers (GUID) that identifies the add-in. An object representing an add-in and other policy-defining objects can provide access to a collection of vendor parameters sets (FPCVendorParametersSets) that can contain configuration settings for add-ins.

This topic describes some details of configuring the following two add-ins:

DNS Filter

DNS Filter is an application filter that is installed with Forefront TMG. It intercepts and analyzes DNS traffic destined for the Internal network. DNS Filter is the backbone of the Forefront TMG intrusion detection mechanism. Intrusion detection identifies when an attack is attempted against your network and performs a set of configured actions, which are defined by alerts, in case of an attack. To detect unwanted intruders, Forefront TMG compares network traffic and log entries to well-known attack methods. Suspicious activities trigger alerts. Actions include connection termination, service termination, sending e-mail messages, and logging.

The following VBScript code example configures DNS Filter by setting values in the vendor parameters set associated with the filter in the collection of vendor parameters sets accessed through the object representing DNS Filter:

Set root = CreateObject("FPC.Root")
Set isaArray = root.GetContainingArray()
Set attackDetection = isaArray.ArrayPolicy.AttackDetection
Set dnsFilter = isaArray.Extensions.ApplicationFilters.Item("{49FE2B2F-3BB4-495C-87C8-3890C3C35756}")
dnsFilter.Enabled = True
Set vpSets = dnsFilter.VendorParametersSets
On Error Resume Next
vpSets.Add "{D96C5E7F-5B13-4E1A-94A1-36CA7B54604E}", False, False
On Error Goto 0		 ' If a vendor parameters sets for DNS Filter already exists
vpSets.Item("{D96C5E7F-5B13-4E1A-94A1-36CA7B54604E}").Value("DNS_Intrusion_detection") = "1"
vpSets.Item("{D96C5E7F-5B13-4E1A-94A1-36CA7B54604E}").Value("DNS_Hostname_Overflow") = "1"
vpSets.Item("{D96C5E7F-5B13-4E1A-94A1-36CA7B54604E}").Value("DNS_Length_Overflow") = "1"
vpSets.Item("{D96C5E7F-5B13-4E1A-94A1-36CA7B54604E}").Value("DNS_Zone_Transfer") = "0"
vpSets.Save

FTP Access Filter

FTP Access Filter is an application filter that is installed with Forefront TMG. It enables FTP protocols. When running in read-only mode, FTP Access Filter blocks all commands in the control channel except the following commands: ABOR, ACCT, CDUP, CWD /0, FEAT, HELP, LANG, LIST, MODE, NLST, NOOP, PASS, PASV, PORT, PWD /0, QUIT, REIN, REST, RETR, SITE, STRU, SYST, TYPE, USER, XDUP, XCWD, XPWD, SMNT. This should block any writing to the server side. The default list of allowed commands can be replaced by a customized list that is written to the collection of vendor parameters sets (FPCVendorParametersSets) associated with the filter. The Firewall service must restarted for the new settings to take effect.

The following VBScript code example configures FTP Access Filter to allow only the USER and PASS commands by setting values in the vendor parameters set associated with the filter in the collection of vendor parameters sets accessed through the object representing FTP Access Filter:

Dim root
Dim ftpFilter
Dim vpSet
On Error Resume Next
Err.Clear
Set root = CreateObject("FPC.Root")
' Get the filter's administration object
Set ftpFilter = root.GetContainingArray.Extensions.ApplicationFilters("{680A928F-22B3-11d1-B026-0000F87750CB}")
If ftpFilter Is Nothing Then
	Wscript.Echo "FTP Access Filter ({680A928F-22B3-11D1-B026-0000F87750CB}) is not installed in array." 
	WScript.Quit
End If
' Get the vendor parameter set containing the filter's configuration.
Set vpSet = ftpFilter.VendorParametersSets.Item("{680A928F-22B3-11D1-B026-0000F87750CB}")
'If this vendor parameters set does not exist, create it.
If vpSet Is Nothing Then
	WScript.Echo "Adding a vendor parameters set ({680A928F-22B3-11D1-B026-0000F87750CB})"
	Err.Clear
	Set vpSet = ftpFilter.VendorParametersSets.Add("{680A928F-22B3-11D1-B026-0000F87750CB}",False)
	ftpFilter.VendorParametersSets.Save
End If
' Add the required parameter.
vpSet.Value("AllowReadCommands") = "USER PASS"
vpSet.Save

HTTP Filter

HTTP Filter is a Web filter that is installed with Forefront TMG. It can be configured on a per-rule basis to block HTTP requests based on the following:

New Web publishing rules and access rules that allow HTTP traffic use a default HTTP filtering configuration, which is not defined in a vendor parameters set and cannot be exported to an XML file. In Forefront TMG Management, you can right-click the name of a Web publishing rule or an access rule that allows HTTP traffic and then click Configure HTTP to open the Configure HTTP policy for rule dialog box. After you click OK in this dialog box and click the Apply button, a new vendor parameters set containing the configuration for the HTTP Filter Web filter is created for the rule. This configuration can be exported from the vendor parameters set of the rule to an XML file and then imported from the XML file to other rules.

The following VBScript subprocedure, which is adapted from the HttpFilterConfig.vbs sample in the Forefront TMG Software Development Kit (SDK), exports the configuration for the HTTP Filter Web filter from the corresponding vendor parameters set of the specified policy rule to the specified file.

Sub ExportConfiguration(ruleName, fileName)
	const FilterGUID = "{f1076e51-bbaf-48ba-a2d7-b0875211e80d}"
	const Error_FileNotFound = &H80070002
	const ConfigParamName = "XML_POLICY"
	Dim rule, vpSets, vpSet
	Dim errorCode, errorDescript
	Dim xmlText
	Dim fso
	Dim file
	Set fso = CreateObject("Scripting.FileSystemObject")
	On Error Resume Next
	Set rule = rules.Item(ruleName)
	Select Case Err.Number
		Case Error_FileNotFound:
			WScript.Echo "The policy rule " & ruleName & " could not be found."
			WScript.Quit
		Case 0:
		Case Else
			' Add code to display the error.
			WScript.Quit
	End Select
	On Error GoTo 0
		 Set vpSets = rule.VendorParametersSets
	On Error Resume Next
	Set vpSet = vpSets.Item(FilterGUID)
	errorCode = Err.Number
	errorDescript = Err.Description
	On Error GoTo 0
	Select Case errorCode
		Case 0:
		Case Error_FileNotFound:
			WScript.Echo "The rule is using the default HTTP Filter configuration, which is not" & VbCrLf _ 
					 & "defined in a vendor parameters set and cannot be exported to an XML" & VbCrLf _ 
					 & "file."
			WScript.Quit
		Case Else
			Err.Raise errorCode,, errorDescript
	End Select
	xmlText = vpSet.Value(ConfigParamName)
	Set file = fso.OpenTextFile(fileName, ForWriting, True)
	file.WriteLine(xmlText)
	file.Close
	WScript.Echo "The configuration was exported successfully."
End Sub

The following VBScript subprocedure, which is also adapted from the HttpFilterConfig.vbs sample in the Forefront TMG SDK, imports the configuration for the HTTP Filter Web filter from the specified file to a new vendor parameters set of the specified policy rule.

Sub ImportConfiguration(ruleName, fileName)
	const FilterGUID = "{f1076e51-bbaf-48ba-a2d7-b0875211e80d}"
	const Error_FileAlreadyExists = &H800700B7
	Dim rule, vpSets, vpSet
	Dim errorCode, errorDescript
	Dim xmlText
	Dim fso
	Dim file

	Set fso = CreateObject("Scripting.FileSystemObject")
	On Error Resume Next
	Set rule = rules.Item(ruleName)
	Select Case Err.Number
		Case Error_FileNotFound:
			WScript.Echo "The policy rule " & ruleName & " could not be found."
			WScript.Quit
		Case 0:
		Case Else
			' Add code to display the error.
			WScript.Quit
	End Select
	On Error GoTo 0
	Set vpSets = rule.VendorParametersSets
	On Error Resume Next
	' Create a vendor parameters set for the HTTP Filter Web filter
	' in the vendor parameters sets collection of the specified rule.
	Set vpSet = vpSets.Add(FilterGUID, False)
	errorCode = Err.Number
	errorDescript = Err.Description
	On Error GoTo 0
	Select Case errorCode
		case 0:
		case Error_FileAlreadyExists:
			set vpSet = vpSets(FilterGUID)
		case Else
			Err.Raise errorCode,, errorDescript
	End Select
	Set file = fso.OpenTextFile(fileName)
	xmlText = file.ReadAll
	vpSet.Value(ConfigParamName) = xmlText

	rule.Save
	WScript.Echo "The configuration was imported successfully."
End Sub

However, the maximum length of HTTP request headers is a global setting that resides in the vendor parameters set of HTTP Filter and applies to all Web publishing rules and access rules that allow HTTP traffic.

The following VBScript subprocedure configures this setting using the value passed to it.

Sub SetNewSize(newLimit)
	const FilterGUID = "{f1076e51-bbaf-48ba-a2d7-b0875211e80d}"
	const ConfigParamName = "XML_POLICY"
	const Error_FileAlreadyExists = &H800700B7
	Dim httpFilter, vpSets, vpSet, newVal
	Dim errorCode, errorDescript
	Dim root

	Set root = WScript.CreateObject("FPC.Root")
	Set httpFilter = root.GetContainingArray.Extensions.Webfilters.Item(FilterGUID)
	Set vpSets = httpFilter.VendorParametersSets
	On Error Resume Next
	Set vpSet = vpSets.Add(FilterGUID, False)
	errorCode = err.Number
	errorDescript = err.Description
	On Error GoTo 0
	Select Case errorCode
		Case 0:
		Case Error_FileAlreadyExists:
			Set vpSet = vpSets.Item(FilterGUID)
		Case Else
			Err.Raise errorCode,, errorDescript
	End Select
	newVal = "<Configuration MaxRequestHeadersLen="" " & newLimit & " ""/>"
	vpSet(ConfigParamName) = newVal 
	httpFilter.Save
	WScript.Echo "The maximum header length was set successfully."
End Sub

See Also

Forefront TMG Administration Script Samples


Send comments about this topic to Microsoft

Build date: 11/30/2009

© 2008 Microsoft Corporation. All rights reserved.