NAME

Courier::Filter::Module::MIMEParts - A MIME part filter module for the Courier::Filter framework

VERSION

0.1

SYNOPSIS

    use Courier::Filter::Module::MIMEParts;

    my $module = Courier::Filter::Module::MIMEParts->new(
        max_size    => $max_size,
        signatures  => [
            {
                # One or more of the following options:
                mime_type   => 'text/html' || qr/html/,
                file_name   => 'file_name.ext' || qr/\.(exe|com|pif|lnk)$/,
                size        => 106496,
                digest_md5  => 'b09e26c292759d654633d3c8ed00d18d',

                # Optionally:
                response    => $response_text
            },
            ...
        ],

        logger      => $logger,
        inverse     => 0,
        trusting    => 0,
        testing     => 0,
        debugging   => 0
    );

    my $filter = Courier::Filter->new(
        ...
        modules     => [ $module ],
        ...
    );

DESCRIPTION

This class is a filter module class for use with Courier::Filter. It matches a message if one of the message's MIME parts matches one of the configured signatures.

Constructor

The following constructor is provided:

new(%options): RETURNS Courier::Filter::Module::MIMEParts

Creates a new MIMEParts filter module.

%options is a list of key/value pairs representing any of the following options:

max_size

An integer value controlling the maximum size (in bytes) of the overall message text for a message to be processed by this filter module. Messages larger than this value will never be processed, and thus will never match. If undef, there is no size limit. Defaults to undef.

As MIME processing is completely done in-memory in this version of the filter module, you should definitely restrict the message size to some sensible value that easily fits in your server's memory. 1024**2 (1MB) should be appropriate for most uses of this filter module.

signatures

REQUIRED. A reference to an array containing the list of signatures against which messages' MIME parts are to be matched. A signature in turn is a reference to a hash containing one or more so-called signature aspects (as key/value pairs). Aspects may either be scalar values (for exact, case-sensitive matches), or regular expression objects created with the qr// operator (for inexact, partial matches).

For a signature to match a MIME part, all of the signature's aspects must match those of the MIME part. For the filter module to match a message, any of the signatures must match any of the message's MIME parts.

An aspect can be any of the following:

mime_type

The MIME type of the MIME part ('type/sub-type').

file_name

The file name of the MIME part.

size

The exact size (in bytes) of the decoded MIME part.

digest_md5

The MD5 digest of the decoded MIME part (32 hex digits, as printed by `md5sum`).

Every signature may also contain a response option containing a string that is to be returned as the match result in case of a match. Defaults to "Prohibited MIME part detected.".

So for instance, a signature list could look like this:

    signatures  => [
        {
            mime_type   => qr/html/,
            response    => 'No HTML mail, please.'
        },
        {
            file_name   => qr/\.(exe|com|pif|lnk)$/,
            response    => 'Executable content detected'
        },
        {
            size        => 106496,
            digest_md5  => 'b09e26c292759d654633d3c8ed00d18d',
            response    => 'Worm detected: W32.Swen'
        },
        {
            size        => 22528,
            response    => 'Worm suspected: W32.Mydoom'
        }
    ]

All options of the Courier::Filter::Module constructor are also supported. Please see "new()" in Courier::Filter::Module for their descriptions.

Instance methods

See "Instance methods" in Courier::Filter::Module for a description of the provided instance methods.

SEE ALSO

Courier::Filter::Module, Courier::Filter::Overview.

For AVAILABILITY, SUPPORT, COPYRIGHT, and LICENSE information, see Courier::Filter::Overview.

AUTHOR

Julian Mehnle <julian@mehnle.net>