7.8 Header Matching and Rewriting

MailMarshal can perform searches and replace text in email headers using a Regular Expression engine. You can apply rewriting globally when messages are received. You can also perform header searches and header replacements within Content Analysis Policy rules.

Caution 

Caution: Regular Expression matching and substitution provides very powerful capabilities. However, regular expressions are complex and can be difficult to construct. If headers are rewritten incorrectly, you may be unable to determine the sender or intended recipient of affected messages. Use this facility with care.

 

7.8.1 Changing and Adding Headers with the Receiver

MailMarshal provides global header rewriting to modify email header and envelope detail. Global rewriting is typically used to allow email aliasing. This action is performed by the MailMarshal Receiver during email message receipt.

Some examples of actions that can be performed are

Address modification: for example, changing user@host.domain.com to user@domain.com.

Field removal: for example, stripping out the received: lines from outbound messages.

Alias substitution: for example, replacing addresses via a lookup table, as in user1@olddomain.com being replaced by user2@newdomain.com.

Domain masquerading: for example, replacing all addresses in thisdomain.com with identical addresses in thatdomain.com.

To work with global header rewriting:

1.In the Management Console, select System Configuration and then expand Receiver Properties.

2.Select Header Rewrite from the right pane menu.

3.You can add a new global header rewrite rule, edit an existing rule, or delete an existing rule. You can also change the order of evaluation of the rules. For details of the rule editing processes, see “Using the Header Rewrite Editor”.

7.8.2 Using Rules to Find Headers

You can search email headers using regular expressions using the MailMarshal Content Analysis Policy rule condition “Where message contains one or more headers.” This rule condition allows matching based on the presence of specific email message headers, or specific content within any header.

To create a header match condition, in the rule condition window click New.

To perform more than one header match within a single condition, add a new header match rule for each match.

Information 

Note: If more than one header to match is entered within a single rule condition, all expressions must match for the condition to be true (logical AND). To check any of several headers (logical OR), use one rule per header.

 

For details of the rule editing processes, see “Using the Header Rewrite Editor”.

7.8.3 Using Rules to Change Headers

You can alter email headers using regular expressions using the MailMarshal Content Analysis Policy rule action “Rewrite message headers using expressions.” This rule action allows matching based on the presence of specific email message headers, or specific content within any header.

To create a header rewrite action, within the rule action window click Add.

To perform more than one header rewriting action within a single condition, add a header match rule for each header rewriting action.

Information 

Note: If more than one header to rewrite is entered within a single rule, the order in which rewriting is applied will be significant. Rewriting actions will apply in top down order as they are listed in the rule action window. To change the order, use the arrows in the window.

 

For details of the rule editing processes, see “Using the Header Rewrite Editor”.

7.8.4 Using the Header Rewrite Editor

This panel allows you to create a header matching or header rewriting rule. Header matching and rewriting uses regular expression matching and substitution. For more information about regular expressions, see “Regular Expressions”.

The header rewrite editor includes two tabs:

On the General tab you can name the rule, select the header or envelope fields to be matched, select the portion of the field to be modified and choose logging options.

On the Expressions tab you can enter matching and substitution expressions and test the rule.

You can also change the order of evaluation of header rewriting rules using the Move Up and Move Down buttons on the parent panel.

To use the Header Rewrite editor:

1.On the General tab, enter a name for the rewrite rule.

2.Optionally enter a comment to explain the purpose of the rule.

element-hrw-field.png 

3.Choose a parsing method from the list. Depending on this selection, MailMarshal will apply regular expression matching to parts or all of the selected headers.

Information 

Note: To insert a custom header, use the parsing method “Entire Line.” To match or modify all email addresses, use the method “Email Address”.

 

If you select the method “Entire Line” MailMarshal will use the entire text of the header as the input text for the substitution engine.

If you select the method “Email Address” MailMarshal will use each email address found in the line as the input text.

If you select the method “Domain” MailMarshal will use the domain part of each email address as the input text.

4.Select (toggle on) Match Case to perform a case sensitive search. Clear this option to make the search case insensitive.

Information 

Note: To search for email addresses or domains, use a case insensitive search.

 

5.If this is a rewriting rule, select whether the changes will be actually applied and/or logged. Select the check box Enable field changes to apply this rule to messages. Select the check box Log changes to write a log of changes to the MailMarshal logs for the message. If only Log changes is selected, the logs will show the changes that would have occurred.

6.Select the fields that you want the rule to apply to from the list. You can add one or more custom header field names.

7.Click Expressions to continue.

element-hrw-subst.png 

8.In the Optional Exclusion Filter field, you can enter a regular expression. If this expression is found in the input text, the search will return “not matched”.

9.In the Field Search Expression field, enter a regular expression that MailMarshal should use to select the data for matching or rewriting. If the input text matches this expression, the rule will match or rewrite it, subject to exceptions based on the exclusion filter.

10.If this is a rewriting rule, choose one of the rewriting methods:

Substitute into field using expression replaces the matched data using a sed or Perl-like syn­tax. You can use sub-expressions generated from the field search here. Refer to the sub-expres­sions as $1 through $9.

Information 

Note: If you replace the entire contents of a field, be sure to terminate the text with a CRLF (\r\n). You can insert this value through the arrow to the right of the field. If you enter $0 (the tagged expression containing the entire input line) at the end of the substitution expression, a CRLF will already be included.

 

Map using file provides for substitutions from a file, to allow a level of indirection in resolving what to substitute into the field. For details of syntax, see “Regular Expressions”. For details of where to place the file, see Help.

Delete the field removes the matching material from the header. When Entire line is selected in the parsing options, selecting Delete the field removes the entire header line from the message.

Insert if missing permits you to add a new header if any of the selected headers does not exist. MailMarshal will use the text of this field as the value of the new header line. For instance if you have added the custom header x-MyNewField then you might enter the value Created by Header Rewrite.

Information 

Note: In Content Analysis rule header rewriting, you can include MailMarshal variables in the Substitute or Insert text. For details, see Help.

11.To test the rule, enter an input string in the Source field and click Test. The result will appear in the Result field. For rewriting actions, the result will be the rewritten string. For matching, the result will be “matched” or “not matched”.

12.If this is a rewriting rule, adjust the order of evaluation using the arrows provided below the list of rules.

Information 

Note: If you use several header matching rules within a single Content Analysis Policy rule condition, all must evaluate true for the condition to be true.

If you create several rewriting rules for global Header Rewrite or within a single Content Analysis Policy rule action, the order of evaluation will be significant. Rewriting actions will be applied in top-down order as shown on the window.

 

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