7.9 Extending Functionality Using External Commands

An external command is a custom executable, Windows command, or batch file that can be run by MailMarshal. The command can be used to check email messages for a condition, or to perform an action when a message meets some other condition.

You can use custom executable files or batch files with the Content Analysis Policy rule condition “Where the external command is triggered.” For instance, you can invoke fgrep.exe for advanced expression matching.

If you want to use an external command to check for a condition, the command must return a standard return code.

You can also use custom executable files with the Content Analysis Policy rule action “Run the external command.” For instance, a particular email subject line could trigger a batch file to start or stop a system service, or to send a page or network notification to an administrator.

Information 

Note: If a command action changes the message or attachments, you must set an option on the rule action to force the message to be repacked. For details, see “Run the external command”.

 

MailMarshal is provided with an external command for message release. See “Using the Message Release External Command”.

To use an external command in MailMarshal rules, you must first define it.

To create or edit an external command definition:

1.In the left pane of the Management Console select Policy Elements. In the right pane menu select External Commands.

2.To create a new external command, on the menu above the list click Add. To edit an existing external command, double-click an item in the list.

element-external-comand.png 

3.Enter a name for the external command.

4.Type the path for the executable file. You can also browse for the file by clicking Browse.

Information 

Note: To use a batch file, you must invoke the command interpreter explicitly as follows:
%Systemroot%\system32\cmd.exe /C {batchfile.cmd} [variables...]

 

5.In the Parameters field, enter any command line parameters necessary for the command. You can pass specific information about a message to the command using MailMarshal variables. Particularly note the variable {CmdFileName}.

6.The Timeout and Timeout per MB values control how long MailMarshal will wait for a response before ignoring the external command. The default values are very generous.

Information 

Note: If the external command executable uses 10% of the timeout time in actual processing (CPU usage), MailMarshal will terminate the command, log the event as a runaway process, and place the message in the Dead Letter\Unpacking folder.

 

7.The Single Thread setting indicates whether the command must operate on one message at a time, or can be invoked multiple times. In most cases this box should be left selected. You can multi-thread certain executable files.

8.The Only execute once for each message setting determines whether an external rule condition command will be run for each component of a message, or only once. For example if you are using fgrep to perform Regular Expression searches of attached files, this box should be cleared to ensure that MailMarshal passes each component of each message to fgrep.exe.

9.If you plan to use the external command as a rule condition, you must set the trigger return code information. You should find this information in the documentation of the executable.

Two fields allow you to enter trigger values which further specify the meaning of the code returned from the virus scanner.

If the code returned matches any value entered in the field Command is triggered if return code is, MailMarshal will consider the condition to be satisfied.

If the code returned matches any value entered in the field Command is not triggered if return code is, MailMarshal will consider the condition not to be satisfied.

If the code returned matches neither field, the file is moved to the Undetermined dead letter folder and an email notification is sent to the MailMarshal administrator.

Entries in both return code fields can be exact numeric values, ranges of values (for example 2-4), greater than or less than values (for example <5, >10). More than one expression can be entered in each field, separated by commas (for example 1,4,5,>10).

Trustwave MailMarshal 10.2.5 User Guide August 2024
< Previous Section   |   Next Section >
Full document: see MailMarshal Documentation.