Guest

Cisco Email Security Appliance

How do I test a message or content filter to ensure it is working as designed?

Document ID: 117902

Updated: Jul 08, 2014

Contributed by Tomki Camp and Enrico Werner, Cisco TAC Engineers.

   Print

Question

How do I test a message or content filter to ensure it is working as designed?

Filters can be tested to ensure they are working properly by debugging the filter. Debugging a filter is a two-step process that requires a system quarantine area.

Create a new System Quarantine in the GUI called 'FilterDebug'. Quarantines are configured under 'Monitor->Quarantines.  If you have some quarantine space available, click on the 'Add Quarantines' button to configure the FilterDebug quarantine.  If there is not enough space available, you will have to edit some other quarantine and lower the space it uses to make some free space available.

Create the filter with the rules (the matching criteria) you expect to use and set the action to "Quarantine('FilterDebug')".

To debug your matching rules, enable the filter on the appropriate Mail Policy (where you intend it to run in production) and generate traffic.

Messages that match your rules will go into the FilterDebug quarantine, where you can examine them and satisfy yourself that your rules are matching precisely what you want.  Release those messages from quarantine, and they will be delivered normally.  If you want to watch this for a while, set the quarantine retention period to something acceptably short and examine the quarantine at regular intervals to see what kinds of messages are matching your criteria.

To debug your filter actions, create a new Mail Policy that has only one test recipient. Disable your rule in all other Mail Policies, and enable it in this new Mail Policy.  Edit your rule to take the actions you want.  You can remove the Quarantine rule.

Generate traffic and check the message as it is delivered  (or not, depending on your filter) to the test recipient to verify this is what you want. Now you can enable the completed rule in the Mail Policies for your production deployment and disable it from the test recipient policy.

A similar procedure can be used to debug message filters.  Begin by building the criteria you want to use in production:

RedirectEarningsReports:
if  (recv-listener == "InboundMail")
and (subject == "(?i)quarterly earnings") {
  quarantine ("FilterDebug");
}

This is done in the CLI:

smtp.example.com>filters
Choose the operation you want to perform:
- NEW - Create a new filter.
- DELETE - Remove a filter.
- IMPORT - Import a filter script from a file.
- EXPORT - Export filters to a file
- MOVE - Move a filter to a different position.
- SET - Set a filter attribute.
- LIST - List the filters.
- DETAIL - Get detailed information on the filters.
- LOGCONFIG - Configure log subscriptions used by filters.
- ROLLOVERNOW - Roll over a filter log file.
[]> new
Enter filter script.  Enter '.' on its own line to end.
RedirectEarningsReports:
if  (recv-listener == "InboundMail")
and (subject == "(?i)quarterly earnings") {
  quarantine ("FilterDebug");
}
.
1 filters added.
Choose the operation you want to perform:
- NEW - Create a new filter.
- DELETE - Remove a filter.
- IMPORT - Import a filter script from a file.
- EXPORT - Export filters to a file
- MOVE - Move a filter to a different position.
- SET - Set a filter attribute.
- LIST - List the filters.
- DETAIL - Get detailed information on the filters.
- LOGCONFIG - Configure log subscriptions used by filters.
- ROLLOVERNOW - Roll over a filter log file.
[]>
smtp.example.com >commit
Please enter some comments describing your changes:
[]> add RedirectEarningsReports filter test actions (incomplete)
Changes committed: Wed Nov 24 12:00:10 2004 MST

Examine the quarantined messages using the GUI and release messages.  Continue watching the message stream in this way until you are satisfied.  Next, add your test recipient to the rules, and change the actions to what you want to run in production:

RedirectEarningsReports:
if  (recv-listener == "InboundMail")
and (subject == "(?i)quarterly earnings")
and (rcpt-to == "(?i)alan@exchange\\.scu\\.com$")  {
  alt-rcpt-to ("sam@exchange.scu.com");
}

In the CLI, you need to delete and recreate the filter:

smtp.example.com> filters
Choose the operation you want to perform:
- NEW - Create a new filter.
- DELETE - Remove a filter.
- IMPORT - Import a filter script from a file.
- EXPORT - Export filters to a file
- MOVE - Move a filter to a different position.
- SET - Set a filter attribute.
- LIST - List the filters.
- DETAIL - Get detailed information on the filters.
- LOGCONFIG - Configure log subscriptions used by filters.
- ROLLOVERNOW - Roll over a filter log file.
[]> list
Num Active Valid Name
  1   N      Y   betatest
  2   N      Y   StripInboundExes
  3   Y      Y   RedirectEarningsReports
Choose the operation you want to perform:
- NEW - Create a new filter.
- DELETE - Remove a filter.
- IMPORT - Import a filter script from a file.
- EXPORT - Export filters to a file
- MOVE - Move a filter to a different position.
- SET - Set a filter attribute.
- LIST - List the filters.
- DETAIL - Get detailed information on the filters.
- LOGCONFIG - Configure log subscriptions used by filters.
- ROLLOVERNOW - Roll over a filter log file.
[]> delete
Enter the filter name, number, or range:
[]> 3
1 filters deleted.
Choose the operation you want to perform:
- NEW - Create a new filter.
- DELETE - Remove a filter.
- IMPORT - Import a filter script from a file.
- EXPORT - Export filters to a file
- MOVE - Move a filter to a different position.
- SET - Set a filter attribute.
- LIST - List the filters.
- DETAIL - Get detailed information on the filters.
- LOGCONFIG - Configure log subscriptions used by filters.
- ROLLOVERNOW - Roll over a filter log file.
[]> new
Enter filter script.  Enter '.' on its own line to end.
RedirectEarningsReports:
if  (recv-listener == "InboundMail")
and (subject == "(?i)quarterly earnings")
and (rcpt-to == "(?i)alan@exchange\\.scu\\.com$")  {
  alt-rcpt-to ("sam@exchange.scu.com");
}
.
1 filters added.
Choose the operation you want to perform:
- NEW - Create a new filter.
- DELETE - Remove a filter.
- IMPORT - Import a filter script from a file.
- EXPORT - Export filters to a file
- MOVE - Move a filter to a different position.
- SET - Set a filter attribute.
- LIST - List the filters.
- DETAIL - Get detailed information on the filters.
- LOGCONFIG - Configure log subscriptions used by filters.
- ROLLOVERNOW - Roll over a filter log file.
[]>
smtp.example.com> commit
Please enter some comments describing your changes:
[]> set RedirectEarningsReports to test recipient
Changes committed: Wed Nov 24 12:10:07 2004 MST

Verify the actions do what you want.  (Depending on your filter, you may also verify some of the actions in the mail_logs.)  Last, put the final filter together by removing the test recipient:

RedirectEarningsReports:
if  (recv-listener == "InboundMail")
and (subject == "(?i)quarterly earnings") {
  alt-rcpt-to ("sam@exchange.scu.com");
}

One potentially confusing aspect of filters and quarantines is the handling of message bodies versus message headers.  In the ESA, the message body and header are dealt with separately. If you examine messages in the quarantine after applying actions, you will not see any header manipulation done to the message (but it will be completed upon delivery.)  This is because header processing is done separately, in parallel, as a message progresses through the pipeline.  The message is reunited with its (potentially modified) header before delivery, but is not seen in the quarantine.  You will see any changes to the body of the message, such as attachment stripping or footer stamping, in the quarantine.

Updated: Jul 08, 2014
Document ID: 117902