Managing protocol message definitions

Article
02/25/2011

Updated: February 1, 2011

Applies To: Forefront Threat Management Gateway (TMG)

Forefront TMG uses protocol message definitions to identify specific types of protocol messages. When Forefront TMG determines that a protocol message is of a type defined in a protocol message definition, it exempts it from malware inspection. Forefront TMG provides the following predefined protocol message definitions for identifying types of protocol messages.

Client-to-Server RPC over HTTP
Server-to-Client RPC over HTTP
Streaming Media

A single protocol message definition is defined by an FPCProtocolMessageDefinition Forefront TMG administration COM object, and all the protocol message definitions defined in an Forefront TMG array are contained in the FPCProtocolMessageDefinitions collection for the array. The FPCProtocolMessageDefinitions collection is accessed through the ExemptedProtocolMessages property of the FPCMalwareInspectionSettings object for the array.

The FPCProtocolMessageDefinition object holds a collection of FPCProtocolMessageDefinitionParameter objects that comprise the protocol message. Each parameter in a protocol message definition maps a parameter name to a value.

In addition, the FPCProtocolMessageDefinitions collection provides the GetSupportedParameters method, which retrieves a SafeArray containing the names of the supported parameters.

Listing protocol message definitions

The Microsoft Visual Basic Scripting Edition (VBScript) code in ListProtocolMessageDefinitions.vbs (listed later in this document) retrieves the collection of protocol message definitions defined in the local Forefront TMG array and displays the name, protocol, and parameters for each protocol message definition.

This script, as presented, must be run on a computer running Forefront TMG with the Microsoft Firewall service installed, but it can be modified to run on a remote management computer.

To use this script, paste the code in the script listing into a text editor, save it in a file named ListProtocolMessageDefinitions.vbs, and then run it from a command prompt.

Usage:

CScript ListProtocolMessageDefinitions.vbs

To list protocol message definitions

Create an instance of the FPC COM object, which is known as the root object and provides access to the other Forefront TMG administration COM objects.
Get references to the FPCArray object and the FPCProtocolMessageDefinitions collection for the local array.
If the collection contains at least one FPCProtocolMessageDefinition collection that defines a protocol message definition, iterate through the FPCProtocolMessageDefinitions collection and display the name retrieved from the Name property, the protocol retrieved from the TransportProtocol property, and the name and value of each parameter retrieved from each FPCProtocolMessageDefinitionParameter object in the FPCProtocolMessageDefinition collection.

Script listing: ListProtocolMessageDefinitions.vbs

'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Copyright (c) Microsoft Corporation. All rights reserved.
' THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE
' ENTIRE RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE     
' REMAINS WITH THE USER. USE AND REDISTRIBUTION OF THIS CODE, WITH OR
' WITHOUT MODIFICATION, IS HEREBY PERMITTED.
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' This script lists the protocol message definitions that are defined
' in the local array.
' This script can be run from a command prompt by entering the 
' following command:
'     CScript ListProtocolMessageDefinitions.vbs
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Option Explicit

Const fpcTransportProtocolUndefined = 0
Const fpcTransportProtocolHttp = 1

Sub ListProtocolMessageDefinitions()

    ' Declare the objects needed.
    Dim root         ' The FPCLib.FPC root object
    Dim tmgArray     ' An FPCArray object
    Dim definitions  ' An FPCProtocolMessageDefinitions collection
    Dim definition   ' An FPCProtocolMessageDefinition collection
    Dim parameter    ' An FPCProtocolMessageDefinitionParameter object
    Dim protocol     ' A String

    ' Create the root object.
    Set root = CreateObject("FPC.Root")

    ' Get references to the array object 
    ' and the protocol message definitions collection.
    Set tmgArray = root.GetContainingArray()
    Set definitions = _
        tmgArray.MalwareInspectionSettings.ExemptedProtocolMessages

    ' Display the protocol message definitions defined in the array.
    If definitions.Count > 0 Then
        WScript.Echo "Protocol message definitions:" & vbCrLf
        For Each definition in definitions
            WScript.Echo "Name: " & definition.Name
            Select Case definition.TransportProtocol
                Case fpcTransportProtocolUndefined 
                    protocol = "Undefined" 
                Case fpcTransportProtocolHttp 
                    protocol = "HTTP" 
            End Select
            WScript.Echo "Protocol: " & protocol & vbCrLf _
                & "Parameters:"
            For Each parameter in definition
                WScript.Echo vbTab & parameter.Name & " = " _
                    & parameter.Value
            Next
            WScript.Echo vbCrLf
        Next
    Else
        WScript.Echo "No protocol message definitions are defined."
    End If
End Sub

ListProtocolMessageDefinitions()

Listing supported protocol message definition parameters

The VBScript code in ListSupportedProtocolMessageDefinitionParameters.vbs (listed later in this document) lists the supported protocol message definition parameters for the HTTP protocol.

This script, as presented, must be run on a Forefront TMG computer with the Microsoft Firewall service installed, but it can be modified to run on a remote management computer.

To use this script, paste the code in the script listing into a text editor, save it in a file named ListSupportedProtocolMessageDefinitionParameters.vbs, and then run it from a command prompt.

Usage:

CScript ListSupportedProtocolMessageDefinitionParameters.vbs

To list supported protocol message definition parameters

Create an instance of the FPC COM object, which is known as the root object and provides access to the other Forefront TMG administration COM objects.
Get references to the FPCArray object and the FPCProtocolMessageDefinitions collection for the local array.
In a For loop, iterate through the SafeArray of supported parameters retrieved by calling the GetSupportedParameters method for the HTTP protocol on the FPCProtocolMessageDefinitions collection and display the name of each parameter.

Script listing: ListSupportedProtocolMessageDefinitionParameters.vbs

'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Copyright (c) Microsoft Corporation. All rights reserved.
' THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE
' ENTIRE RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE     
' REMAINS WITH THE USER. USE AND REDISTRIBUTION OF THIS CODE, WITH OR
' WITHOUT MODIFICATION, IS HEREBY PERMITTED.
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' This script lists the supported protocol message definition
' parameters for the HTTP protocol.
' This script can be run from a command prompt by entering the 
' following command:
'     CScript ListSupportedProtocolMessageDefinitionParameters.vbs
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Option Explicit

' Define the constant needed.
Const fpcTransportProtocolHttp = 1

Sub ListSupportedParameters()

    ' Declare the objects needed.
    Dim root         ' The FPCLib.FPC root object
    Dim tmgArray     ' An FPCArray object
    Dim definitions  ' An FPCProtocolMessageDefinitions collection
    Dim name         ' A String

    ' Create the root object.
    Set root = CreateObject("FPC.Root")

    ' Get references to the array object 
    ' and the protocol message definitions collection.
    Set tmgArray = root.GetContainingArray()
    Set definitions = _
        tmgArray.MalwareInspectionSettings.ExemptedProtocolMessages

    WScript.Echo "The supported parameters are:"
    For Each name in _
        definitions.GetSupportedParameters(fpcTransportProtocolHttp)
        WScript.Echo vbTab & name
    Next
End Sub

ListSupportedParameters()

Creating a new protocol message definition

The VBScript code in AddProtocolMessageDefinition.vbs (listed later in this document) creates a new protocol message definition with the name specified by the user and configures the parameters with the names listed in the following table.

Parameter name	Description
RequestMethod	Specifies the HTTP method in a request that corresponds to the protocol message definition.
RequestUserAgent	Specifies the contents of the User-Agent header in a request that corresponds to the protocol message definition.
RequestContentType	Specifies the contents of the Content-Type header in a request that corresponds to the protocol message definition.
RequestAccept	Specifies the contents of the Accept header in a request that corresponds to the protocol message definition.
ResponseContentType	Specifies the contents of the Content-Type header in a response that corresponds to the protocol message definition.

This script, as presented, must be run on a Forefront TMG computer with the Microsoft Firewall service installed, but it can be modified to run on a remote management computer.

To use this script, paste the code in the script listing into a text editor, save it in a file named AddProtocolMessageDefinition.vbs, and then run it from a command prompt.

Usage:

CScript AddProtocolMessageDefinition.vbs /name:value [/rqm:value] [/ua:value] [/rqct:value] [/ra:value] [/rsct:value] [/h | /?]

Here value specifies the value supplied for the applicable argument. The meanings of the arguments are summarized in the following table.

Argument	Meaning
/name	Name of new protocol message definition.
/rqm	Set the RequestMethod parameter to the value specified in value.
/ua	Set the RequestUserAgent parameter to the value specified in value
/rqct	Set the RequestContentType parameter to the value specified in value
/ra	Set the RequestAccept parameter to the value specified in value
/rsct	Set the ResponseContentType parameter to the value specified in value
/h /?	Display the usage information.

After you run the script, check the Configuration tab for the Monitoring node to verify that the changes were applied.

To add a protocol message definition

Create an instance of the FPC COM object, which is known as the root object and provides access to the other Forefront TMG administration COM objects.
Get references to the FPCArray object and the FPCProtocolMessageDefinitions collection for the local array.
Call the Add method on the collection with the name supplied by the user and the constant that specifies the HTTP protocol to create a new FPCProtocolMessageDefinition collection, which represents the new protocol message definition.
For each parameter specified by the user, call the Add method on the FPCProtocolMessageDefinition collection created to set the applicable parameter to the value specified by the user.
Call Save on the collection of protocol message definitions to write the changes to persistent storage.

Script listing: AddProtocolMessageDefinition.vbs

'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Copyright (c) Microsoft Corporation. All rights reserved.
' THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE
' ENTIRE RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE     
' REMAINS WITH THE USER. USE AND REDISTRIBUTION OF THIS CODE, WITH OR
' WITHOUT MODIFICATION, IS HEREBY PERMITTED.
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' This script creates a new protocol message definition with the name
' specified by the user and configures the following parameters in it:
'   RequestMethod - the HTTP method specified in a request
'   RequestUserAgent - the contents of the User-Agent header in a
'     request
'   RequestContentType - the contents of the Content-Type header in
'     a request
'   RequestAccept - the contents of the Accept header in a
'     request
'   ResponseContentType - the contents of the Content-Type header in
'     a response
' This script can be run from a command prompt by entering the 
' following command:
'     CScript AddProtocolMessageDefinition.vbs /name:value [/rqm:value]  
'     [/ua:value] [/rqct:value] [/ra:value] [/rsct:value]
'     [/h | /?]
' After you run the script, check the Configuration tab for the
' Monitoring node to verify that the changes were applied.
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Option Explicit

' Define the constant needed.
Const Error_AlreadyExists = &H800700B7
Const fpcTransportProtocolHttp = 1

Main(WScript.Arguments)

Sub Main(args)
    Dim argsN        ' A WScript.Arguments.Named object
    Dim num          ' An Integer

    Set argsN = args.Named 

    num = 0
    If argsN.Exists("name") Then
        num = num + 1
    End If
    If argsN.Exists("rqm") Then
        num = num + 1
    End If
    If argsN.Exists("ua") Then
        num = num + 1
    End If
    If argsN.Exists("rqct") Then
        num = num + 1
    End If
    If argsN.Exists("ra") Then
        num = num + 1
    End If
    If argsN.Exists("rsct") Then
        num = num + 1
    End If
    If argsN.Exists("h") Then
        num = num + 1
    End If
    If argsN.Exists("?") Then
        num = num + 1
    End If
    If argsN.Count <> args.Count Or argsN.Count <> num Then
        WScript.Echo "An invalid argument was entered."
        Usage()
    End If

    If argsN.Exists("h") And argsN("h") <> "" Then
        WScript.Echo "An invalid argument value was provided."
        Usage()
    End If
    If argsN.Exists("?") And argsN("?") <> "" Then
        WScript.Echo "An invalid argument value was provided."
        Usage()
    End If
    If argsN.Exists("h") Or argsN.Exists("?") Or args.Count = 0 Then
        Usage()
    End If
    If Not argsN.Exists("name") Then
        WScript.Echo "The /name argument is required."
        Usage()
    End If
    If argsN.Exists("name") And argsN("name") = "" Then
        WScript.Echo "No value was provided for /name."
        Usage()
    End If
    If argsN.Exists("rqm") And argsN("rqm") = "" Then
        WScript.Echo "No value was provided for /rqm."
        Usage()
    End If
    If argsN.Exists("ua") And argsN("ua") = "" Then
        WScript.Echo "No value was provided for /ua."
        Usage()
    End If
    If argsN.Exists("rqct") And argsN("rqct") = "" Then
        WScript.Echo "No value was provided for /rqct."
        Usage()
    End If
    If argsN.Exists("ra") And argsN("ra") = "" Then
        WScript.Echo "No value was provided for /ra."
        Usage()
    End If
    If argsN.Exists("rsct") And argsN("rsct") = "" Then
        WScript.Echo "No value was provided for /rsct."
        Usage()
    End If

    AddProtocolMessageDefinition(argsN)
End Sub

Sub AddProtocolMessageDefinition(argsN)

    ' Declare the objects needed.
    Dim root          ' The FPCLib.FPC root object
    Dim tmgArray      ' An FPCArray object
    Dim definitions   ' An FPCProtocolMessageDefinitions collection
    Dim newDefinition ' An FPCProtocolMessageDefinition collection

    ' Create the root object.
    Set root = CreateObject("FPC.Root")

    ' Get references to the array object 
    ' and the protocol message definitions collection.
    Set tmgArray = root.GetContainingArray()
    Set definitions = _
        tmgArray.MalwareInspectionSettings.ExemptedProtocolMessages

    ' Create the new definition
    On Error Resume Next
    Set newDefinition = _
        definitions.Add(argsN("name"), fpcTransportProtocolHttp)
    If Err.Number = Error_AlreadyExists Then
        WScript.Echo "A protocol message definition with the name " _
            & "specified already exists."
        WScript.Quit
    End If
    On Error GoTo 0

    If argsN.Exists("rqm") And argsN("rqm") <> "" Then
        WScript.Echo "Setting the RequestMethod parameter ..."
        newDefinition.Add "RequestMethod", argsN("rqm")
    End If

    If argsN.Exists("ua") And argsN("ua") <> "" Then
        WScript.Echo "Setting the RequestUserAgent parameter ..."
        newDefinition.Add "RequestUserAgent", argsN("ua")
    End If

    If argsN.Exists("rqct") And argsN("rqct") <> "" Then
        WScript.Echo "Setting the RequestContentType parameter ..."
        newDefinition.Add "RequestContentType", argsN("rqct")
    End If

    If argsN.Exists("ra") And argsN("ra") <> "" Then
        WScript.Echo "Setting the RequestAccept parameter ..."
        newDefinition.Add "RequestAccept", argsN("ra")
    End If

    If argsN.Exists("rsct") And argsN("rsct") <> "" Then
        WScript.Echo "Setting the ResponseContentType parameter ..."
        newDefinition.Add "ResponseContentType", argsN("rsct")
    End If

    WScript.Echo  "Saving ..."
    definitions.Save
    WScript.Echo "Done!"
End Sub

Sub Usage()
    WScript.Echo "Usage:" & VbCrLf _
        & "  " & WScript.ScriptName & " /name:value [/rqm:value] " _
        & "[/ua:value] [/rqct:value] [/ra:value] [/rsct:value] "_
        & "[/h | /?]" & VbCrLf _
        & "" & VbCrLf _
        & "    /name - Name of new protocol message definition" _
        & VbCrLf _
        & "    /rqm  - Set RequestMethod parameter" & VbCrLf _
        & "    /ua   - Set RequestUserAgent parameter" & VbCrLf _
        & "    /rqct - Set RequestContentType parameter" & VbCrLf _ 
        & "    /ra   - Set RequestAccept parameter" & VbCrLf _ 
        & "    /rsct - Set ResponseContentType parameter" & VbCrLf _ 
        & "    value - Definition name or parameter value" & VbCrLf _
        & "    /h /? - Display this help."
    WScript.Quit
End Sub

Deleting a protocol message definition

The VBScript code in DelProtocolMessageDefinition.vbs (listed later in this document) deletes the protocol message definition specified by the user.

This script, as presented, must be run on a Forefront TMG computer with the Microsoft Firewall service installed, but it can be modified to run on a remote management computer.

To use this script, paste the code in the script listing into a text editor, save it in a file named DelProtocolMessageDefinition.vbs, and then run it from a command prompt.

Usage:

CScript DelProtocolMessageDefinition.vbs DefName

DefName specifies the name of the protocol message definition to be deleted.

After you run the script, check the Configuration tab for the Monitoring node to verify that the changes were applied.

To delete a protocol message definition

Create an instance of the FPC COM object, which is known as the root object and provides access to the other Forefront TMG administration COM objects.
Get references to the FPCArray object and the FPCProtocolMessageDefinitions collection for the local array.
Call the Remove method on the collection with the name supplied by the user to delete the protocol message definition specified by the user.
For each parameter specified by the user, call the Add method on the FPCProtocolMessageDefinition collection created to set the applicable parameter to the value specified by the user.
Call Save on the collection of protocol message definitions to write the changes to persistent storage.

Script listing: DelProtocolMessageDefinition.vbs

'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Copyright (c) Microsoft Corporation. All rights reserved.
' THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE
' ENTIRE RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE     
' REMAINS WITH THE USER. USE AND REDISTRIBUTION OF THIS CODE, WITH OR
' WITHOUT MODIFICATION, IS HEREBY PERMITTED.
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' This script deletes the specified protocol message definition.
' This script can be run from a command prompt by entering the 
' following command:
'     CScript DelProtocolMessageDefinition.vbs DefName
' After you run the script, check the Configuration tab for the
' Monitoring node to verify that the changes were applied.
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Option Explicit

' Define the constant needed.
const Error_FileNotFound = &H80070002

Main(WScript.Arguments)

Sub Main(args)
    If(args.Count <> 1) Then
        Usage()
    Else
       DelProtocolMessageDefinition args(0)
    End If
End Sub

Sub DelProtocolMessageDefinition(definitionName)

    ' Declare the objects needed.
    Dim root          ' The FPCLib.FPC root object
    Dim tmgArray      ' An FPCArray object
    Dim definitions   ' An FPCProtocolMessageDefinitions collection

    ' Create the root object.
    Set root = CreateObject("FPC.Root")

    ' Get references to the array object 
    ' and the protocol message definitions collection.
    Set tmgArray = root.GetContainingArray()
    Set definitions = _
        tmgArray.MalwareInspectionSettings.ExemptedProtocolMessages


    ' Delete the specified protocol message definition.
    On Error Resume Next
    definitions.Remove(definitionName)
    If Err.Number = Error_FileNotFound Then
        WScript.Echo "The protocol message definition specified "_
            & "could not be found."
        WScript.Quit
    Else
        WScript.Echo "Removing the " & definitionName _
            & " protocol message definition  ..."
    End If
    On Error GoTo 0

    WScript.Echo  "Saving ..."
    definitions.Save
    WScript.Echo "Done!"
End Sub

Sub Usage()
    WScript.Echo "Usage:" & VbCrLf _
        & "  " & WScript.ScriptName & " DefName" & VbCrLf _
        & "" & VbCrLf _
        & "  DefName - Name of the protocol message definition "_
        & "to be deleted" 

    WScript.Quit
End Sub

Managing protocol message definitions

Listing protocol message definitions

To list protocol message definitions

Script listing: ListProtocolMessageDefinitions.vbs

Listing supported protocol message definition parameters

To list supported protocol message definition parameters

Script listing: ListSupportedProtocolMessageDefinitionParameters.vbs

Creating a new protocol message definition

To add a protocol message definition

Script listing: AddProtocolMessageDefinition.vbs

Deleting a protocol message definition

To delete a protocol message definition

Script listing: DelProtocolMessageDefinition.vbs

Additional resources