Courie...:Parts(3pm)

💅 Courie...:Parts(3pm) 💅

okay bestie, gather round 🫶 this is the Courie...:Parts(3pm) page from the User Contributed Perl Documentation, and it's all about one very specific little module. no cap, it's niche but it slays. let's get into it ✨

---

🌸 NAME 🌸

Courier::Filter::Module::Parts — a Message (MIME multipart and ZIP archive) parts filter module for the Courier::Filter framework. it's giving security guard energy but make it Perl 💜

---

✨ SYNOPSIS ✨

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

my $module = Courier::Filter::Module::Parts->new(
    max_message_size
                    => $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 ],
    ...
);

---

🦋 DESCRIPTION 🦋

so this class is a filter module class you use with Courier::Filter. what does it do? it matches a message if one of the message's parts (that's MIME parts, or files inside a ZIP archive) matches one of the configured signatures. literally the vibe check for every little piece of your mail 🔍💖

🎀 Constructor 🎀

new(%options): returns Courier::Filter::Module::Parts

creates a shiny new Parts filter module 💫

%options is a list of key/value pairs, and it can be any of these:

• views — an arrayref holding the global default set of views the filter module should apply to message parts when it's matching the configured signatures against them. a view is just how a MIME part's (MIME-decoded) data gets interpreted. defaults to ['raw']. 👑

these are the views that are supported:

• raw — the MIME part gets MIME-decoded but not otherwise transformed. then the raw MIME part is matched against the configured signatures.
• zip — if the MIME part has a file name ending in ".zip", it's considered a ZIP archive, and all unencrypted files in the archive get matched as individual message parts against the configured signatures. lowkey important: the zip view requires the Archive::Zip Perl module to be installed. if it's not there, no zip vibes for you 😭

• max_message_size
• 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 bigger than this value will never be processed, and thus will never match. if it's undef, there's no size limit at all. defaults to 1024**2 (that's 1MB).

bestie listen 👀 because MIME multipart and ZIP archive processing can be quite CPU- and memory-intensive (even though the Parts filter module has made 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.

ngl, the "max_message_size" option used to be called "max_size", but the latter is deprecated now and may not be supported in future versions of the Parts filter module. so like, move on already 💀

• max_part_size — an integer value controlling the maximum size (in bytes) of any single message part (i.e. a MIME part in a message, or a 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 it's undef, there's no size limit.

by default it defaults to the value of the "max_message_size" option, so honestly you don't really need to specify a part size limit if you're comfortable 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 is what prevents huge files from being decompressed. protect yourself, queen 🛡️

• signatures — Required. a reference to an array containing the list of signatures that message parts are to be matched against. 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. and for the filter module to match a message, any of the signatures must match any of the message's parts. and a signature aspect can be any of the following:

• mime_type — the MIME type of the message part, formatted as 'type/sub-type'.
• file_name — the file name of the message part.
• size — the exact size (in bytes) of the decoded message part.
• digest_md5 — the MD5 digest of the decoded message part (32 hex digits, exactly as printed by md5sum).
• encrypted — a boolean value denoting whether the message part is encrypted and its contents are inaccessible to the Parts filter module.

💜 Signature options 💜

and a signature option can be any of the following:

• views — an arrayref containing the set of views the filter module should apply to message parts when matching this signature against them. for the list of supported views, go look at the description of the constructor's "views" option. defaults to the global set of views specified to the constructor.
• response — a string that is to be returned as the match result in case of a match. defaults to "Prohibited message part detected.".

🍓 Example 🍓

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)'
    }
]

also, all options of the Courier::Filter::Module constructor are supported by the constructor of the Parts filter module too 🫶 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. that's it, that's the section, go read the other page bestie 😌

---

👑 SEE ALSO 👑

• Courier::Filter::Module
• Courier::Filter::Overview

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

---

💖 AUTHOR 💖

Julian Mehnle <julian@mehnle.net> — we stan a legend 🫶

---

and that's a wrap on this page, bestie!! it's giving perl v5.34.0, dated 2022-10-21, and it lives under Courie...:Parts(3pm). go forth and filter those message parts, you absolute icon 🌈💅✨