Mail::SpamAssassin::Plugin::Karmasphere - Query the Karmasphere reputation system
loadplugin Mail::SpamAssassin::Plugin::Karmasphere karma_feedset connect karmasphere.email-sender karma_range KARMA_CONNECT_0_10 connect 0 10 score KARMA_CONNECT_0_10 0.1
The Karmasphere reputation service is a real-time reputation service for Internet identities. The aim of this plugin is to detect identities used by spammers and phishers, and thus detect zero-day spam runs and phishing scams. Conversely, it can also detect identities used by reputable senders, and thus use a whitelisting strategy to bypass further antispam checking and (one hopes) reduce false positives.
This plugin performs lookups against the Karmasphere reputation service. Two lookups are performed: One on the connect-time identities (client-ip, helo-address and envelope-from) and one on any identities found in the body of the message. Of these, the first is relatively trustworthy, since it works (where possible) with authenticated identities. The second works with unathenticated identities, but should still trap URLs used by spammers and phishing sites.
An extremely simplistic, minimal example configuration file is provided in the eg/spamassassin/ subdirectory of this distribution. An administrator would be expected to write a more complex configuration file including more useful score ranges. The details of a particular configuration file will depend on the choice of feedsets used for the various context.
The very similar-looking words 'context', 'connect' and 'content' are used throughout this document. Please read carefully.
Valid contexts are connect, for a karma query relating to connection-time metadata, and content for content-filtering data.
A karma score range. context is either connect or content
The feedset name to query in the given context information. The default for the connect context is karmasphere.email-sender. The default for the content filter context is karmasphere.contentfilter.
karmasphere.email-sender
karmasphere.contentfilter
Hostname or IP address of the Karmasphere query server. The default is query.karmasphere.com.
query.karmasphere.com
Port number of the Karmasphere query server. The default is 8666.
8666
The timeout for receiving Karmasphere responses, in seconds. The default is 15.
15
An identifier may be used to authenticate queries from SpamAssassin to Karmasphere. It is not required for most cases. See http://my.karmasphere.com/devzone/client/configuration#credentials
That web page talks in terms of "username" and "password.
Karma_principal corresponds to "username".
See karma_principal, above.
Karma_credentials corresponds to "password".
This module adds two extra template tags for header rewriting: _KARMASCORE(context)_ and _KARMADATA(context)_, which expand to the numeric score, and explanatory data generated by Karmasphere in the given context. For example, to generate a "traditional" karma header for the connect context, use:
context
add_header all Karma-Connect _KARMASCORE(connect)_: _KARMADATA(connect)_
Due to the limitations of SpamAssassin, it is impossible to generate a header "X-Karma". The generated headers are all prefixed with "X-Spam-". Post-filter programs designed to work with this Karma plugin will therefore need to look for the configured header variants instead of X-Karma.
The plugin hooks two points in the SpamAssassin scanner cycle. It sends Karmasphere queries during the parsed_metadata callback, and it receives responses during the check_post_dnsbl callback.
Several hooks are provided for the user to alter the query packet constructed. The routine which builds the packet by default calls the following routines on itself to add fields to the query:
Adds any information gathered from Authentication-Results headers to the given connection query packet. This is usually authenticated versions of of various identities checked by SPF, DKIM or other external mechanisms.
Adds any information gathered from Received headers to the given connection query packet. This frequently includes the client IP, mail from address, and so forth.
Adds the information gathered from $scanner->get('EnvelopeFrom:addr') to the given connection query packet.
By default, this does nothing. This is the recommended extension point for custom fields in the connection query packet.
Adds URLs found in the body to the given content query packet.
By default, this does nothing. This is the recommended extension point for custom fields in the content query packet.
The plugin is designed to be subclassed by modulesoverriding the add_*_other() routines. If you do this, you must load your subclass instead of this class in your configuration file.
If SpamAssassin's debugging for the 'karma' facility is enabled (i.e. would_log('dbg', 'karma') returns true), then access to the Mail::Karmasphere::Client Debug mechanism is provided via a global variable $Mail::SpamAssassin::Plugin::Karmasphere::DEBUG. If that variable contains a subroutine reference, the referenced subroutine will be called as the Mail::Karmasphere::Client Debug routine.
Developers needing more information about any of the above features should dig into the source code.
Ensure that Authentication-Results headers are only honoured when not preceded by a Received line.
These instructions get the plugin working with SpamAssassin.
After a successful CPAN install of Mail::Karmasphere::Client, you should find Karmasphere.pm present alongside your other SpamAssassin plugins.
First, we need to
loadplugin Mail::SpamAssassin::Plugin::SPF
Look in /etc/mail/spamassassin or /etc/spamassassin.
If init.pre exists, place the loadplugin line there. Otherwise, insert it at the top of local.cf.
init.pre
local.cf
Then add the following lines to the end of local.cf:
ifplugin Mail::SpamAssassin::Plugin::Karmasphere karma_feedset connect karmasphere.email-sender karma_feedset content karmasphere.email-body karma_range KARMA_CONNECT_POSITIVE connect 300 1000 karma_range KARMA_CONNECT_NEGATIVE connect -1000 -300 karma_range KARMA_CONTENT_POSITIVE content 300 1000 karma_range KARMA_CONTENT_NEGATIVE content -1000 -300 score KARMA_CONNECT_POSITIVE -2.0 score KARMA_CONNECT_NEGATIVE 2.0 score KARMA_CONTENT_POSITIVE -1.0 score KARMA_CONTENT_NEGATIVE 1.0 add_header all Karma-Connect _KARMASCORE(connect)_: _KARMADATA(connect)_ add_header all Karma-Content _KARMASCORE(content)_: _KARMADATA(content)_ endif # Mail::SpamAssassin::Plugin::Karmasphere
Use the data fields from the Karma response to construct an explanation message.
Mail::Karmasphere::Client, http://www.karmasphere.com/, Mail::SpamAssassin, Mail::SpamAssassin::Conf, Mail::SpamAssassin::Logger, "spamassassin/26_karmasphere.cf" in eg
Copyright (c) 2005-2006 Shevek, Karmasphere. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Mail::Karmasphere::Client, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mail::Karmasphere::Client
CPAN shell
perl -MCPAN -e shell install Mail::Karmasphere::Client
For more information on module installation, please visit the detailed CPAN module installation guide.