Provided by: courier-filter-perl_0.200+ds-4_all bug


       Courier::Filter::Module::Parts - Message (MIME multipart and ZIP archive) parts filter
       module for the Courier::Filter framework


           use Courier::Filter::Module::Parts;

           my $module = Courier::Filter::Module::Parts->new(
                               => $max_message_size,
               max_part_size   => $max_part_size,
               views           => ['raw', 'zip'],
               signatures      => [
                       # One or more of the following options:
                       mime_type       => 'text/html' || qr/html/i,
                       file_name       => 'file_name.ext' || qr/\.(com|exe)$/i,
                       size            => 106496,
                       digest_md5      => 'b09e26c292759d654633d3c8ed00d18d',
                       encrypted       => 0,

                       # Optionally any of the following:
                       views           => ['raw', 'zip'],
                       response        => $response_text

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

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


       This class is a filter module class for use with Courier::Filter.  It matches a message if
       one of the message's parts (MIME parts, or files in a ZIP archive) matches one of the
       configured signatures.

       The following constructor is provided:

       new(%options): returns Courier::Filter::Module::Parts
           Creates a new Parts filter module.

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

               An arrayref containing the global default set of views the filter module should
               apply to message parts when matching the configured signatures against them.  A
               view is the way how a MIME part's (MIME-decoded) data is interpreted.  Defaults to

               The following views are supported:

               raw The MIME part is MIME-decoded but not otherwise transformed.  The raw MIME
                   part is then matched against the configured signatures.

               zip If the MIME part has a file name ending in ".zip", it is considered a ZIP
                   archive, and all unencrypted files in the archive are matched as individual
                   message parts against the configured signatures.  The zip view requires the
                   Archive::Zip Perl module to be installed.

           max_size (DEPRECATED)
               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 1024**2 (1MB).

               As MIME multipart and ZIP archive processing can be quite CPU- and memory-
               intensive (although the Parts filter module makes use of temporary files since
               version 0.13), 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.

               The "max_message_size" option was previously called "max_size", but the latter is
               now deprecated and may not be supported in future versions of the Parts filter

               An integer value controlling the maximum size (in bytes) of any single message
               part (i.e. MIME part in a message, or file in an archive) for that part to be
               processed by this filter module.  Parts larger than this value will never be
               processed, and thus will never match.  If undef, there is no size limit.

               Defaults to the value of the "max_message_size" option, so you don't really need
               to specify a part size limit if you are comfortable with using the same value for
               both.  See the "max_message_size" option for its default.

               If you make use of the 'zip' view, be aware of the risk posed by so-called
               decompression bombs, which allow messages to easily fall below the overall message
               size limit, while a file in a small attached ZIP archive can decompress to a huge
               size.  The part size limit prevents huge files from being decompressed.

               Required.  A reference to an array containing the list of signatures against which
               message 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) and any
               signature options (also as key/value pairs).

               Signature aspects

               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 message part, all of the signature's
               specified aspects must match those of the message part.  For the filter module to
               match a message, any of the signatures must match any of the message's parts.

               A signature aspect can be any of the following:

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

                   The file name of the message part.

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

                   The MD5 digest of the decoded message part (32 hex digits, as printed by

                   A boolean value denoting whether the message part is encrypted and its
                   contents are inaccessible to the Parts filter module.

               Signature options

               A signature option can be any of the following:

                   An arrayref containing the set of views the filter module should apply to
                   message parts when matching this signature against them.  For a list of
                   supported views, see the description of the constructor's "views" option.
                   Defaults to the global set of views specified to the constructor.

                   A string that is to be returned as the match result in case of a match.
                   Defaults to "Prohibited message part detected.".


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

                   signatures  => [
                           mime_type   => qr/html/i,
                           response    => 'No HTML mail, please.'
                           file_name   => qr/\.(com|exe|lnk|pif|scr|vbs)$/i,
                           response    => 'Executable content detected'
                           size        => 106496,
                           digest_md5  => 'b09e26c292759d654633d3c8ed00d18d',
                           views       => ['raw', 'zip'],  # Look into ZIP archives, too!
                           response    => 'Worm detected: W32.Swen'
                           size        => 22528,
                           # Cannot set a specific digest_md5 since W32.Mydoom
                           # is polymorphic.
                           response    => 'Worm suspected: W32.Mydoom'
                           encrypted   => 1,
                           views       => ['zip'],
                           response    => 'Worm suspected ' .
                                          '(only worms and fools use ZIP encryption)'

           All options of the Courier::Filter::Module constructor are also supported by the
           constructor of the Parts filter module.  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.


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

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


       Julian Mehnle <>