Module Version: 0.93 (20140320075010) Latest Release: Mail-SpamAssassin-Contrib-Plugin-IPFilter-0.93

NAME

Mail::SpamAssassin::Contrib::Plugin::IPFilter - Blocks bad MTA behavior using IPTables and Redis.

SYNOPSIS

To try this out, add this or uncomment this line in init.pre:

LoadPlugin     Mail::SpamAssassin::Contrib::Plugin::IPFilter

Configuration defaults:

        filter_name spamipfilter
        iptables_bin $PATH/iptables

        redis_host 127.0.0.1
        redis_port 6379
        redis_auth [password]
        redis_key_prefix spam-ipfilter

        average_score_for_rule  8
        cache_decay_days 5      
        expire_rule_seconds 14400
        expires_multiplier_penalty 1.5  
        seconds_to_decay_penalty 300
        trigger_score 6
        trigger_messages 4
        trigger_sensitivity 4

        common_hosts gmail.com, google.com, yahoo.com, hotmail.com, live.com
        admin_message Your message to $recipient from $email was blocked and your IP address $ip blacklisted 
           due to excessive unsolicited bulk email. To reinstate your ability to send email to $recipient, 
           please reply to $admin using a different off-network email, including the body of this message, 
           with a request for reinstatement.
        verbose 0

DESCRIPTION

Mail::SpamAssassin::Contrib::Plugin::IPFilter blacklists unsolicited bulk email senders using IPTables and a Redis based cache. It will blacklist the sender IP using the smallest network possible, up to /24, when UCE originates from multiple hosts on the same network. Depending on the diversity and frequency of spam received on a server, it may take a couple of days to become effective. Thereafter, the cache state will decay to prevent spammers from burning IP blocks.

Responsible, well-known email hosts (common_hosts) are given special treatment to avoid blacklisting their networks. UCE originating from common_hosts is blacklisted on a per sender basis using SpamAssassin's AWL. The plugin may be configured to email the blacklisted sender a warning for remediation. A sane IPTables setup and non-volatile Redis configuration are assumed. Additionally, an entry is created in /etc/cron.d/ for required maintenence.

IPV6 support is experimental. Future versions may include a database shared by nodes participating in a system similar to a decaying blockchain.

PREFERENCES

The following options may be used in site-wide (local.cf) configuration files to customize operation:

filter_name
The name of the chain that Mail::SpamAssassin::Contrib::Plugin::IPFilter will create to block spammers. This will also be used as the file name in /etc/cron.d/. [a-zA-Z0-9_.]

iptables_bin
The path to iptables binary on your system.

redis_host
The IPv4 address of your Redis server.

redis_port
The port that Redis is listening on.

redis_auth
The Redis password, if any.

redis_key_prefix
The prefix for Redis keys created and used by Mail::SpamAssassin::Contrib::Plugin::IPFilter. ^[a-zA-Z0-9_.]$

average_score_for_rule
The average spam score for a host required to trigger a rule after trigger_messages.

cache_decay_days
After how long will entries in the cache decay, assuming no spam messages are seen. Note that the cache will decay according to: cumulative_spam_score_for_host * exp(-3*lastspam_delta/cache_decay_secs)

expire_rule_seconds
After how long will a block rule expire.

expires_multiplier_penalty
A factor used to penalize hosts with longer rule expiration based on the spam of score of the message resulting in a rule, relative to the average spam score required to set the rule.

seconds_to_decay_penalty
A frequency indicator used to tune penalization for a given host based on how many spam messages were seen for that host over a time period. PF = exp((-1/10 * lastspam_delta/seconds_to_decay_penalty))

trigger_score
The score for which Mail::SpamAssassin::Contrib::Plugin::IPFilter will process a spam message. This should be greater than the SpamAssassin required_score.

trigger_messages
The minimum number of spam messages from a given host before a rule is triggered.

trigger_sensitivity
A quantity indicator used to tune penalization for a given host based on how many spam messages were seen for that host. PF = exp(-3*trigger_sensitivity/spamhits)

common_hosts
Hosts which should not be blacklisted via IPTables rule, and fall back to SpamAssassin blacklist.

admin_email
The email address to send blacklist warnings from. If left unconfigured, no warnings will be sent.

admin_message
The warning message that will be sent. Paramaters $user, $domain, $ip, $email, $recipient and $admin may be used for templatization.

whitelist
Any email address or ip address to whitelist. Email addresses may be specified as foo@example.com or just @example.com to match the whole domain, and IPs may be specified as 1.2.3.4 or just 1.2.3. to match the class C address space.

verbose
Log additional information via Mail::SpamAssassin::Logger

NAME

SYNOPSIS

DESCRIPTION

PREFERENCES

AUTHOR