Share via

Configuring Add-ins

  • Article

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
  • FTP Filter
  • HTTP Filter

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:

  • Request payload length.
  • URL length.
  • HTTP request method, such as the POST, GET, or HEAD request method.
  • HTTP request file name extension, such as .exe, .asp, or .dll.
  • HTTP request or response header.
  • Signature or pattern in the request or response header or body.

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: 6/30/2010