Managing protocol message definitions
Microsoft Forefront Threat Management Gateway 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