Mail::SpamAssassin::Plugin::Karmasphere - Query the Karmasphere reputation system


        loadplugin Mail::SpamAssassin::Plugin::Karmasphere

        karma_feedset connect
        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.

karma_range rulename context min max

A karma score range. context is either connect or content

karma_feedset context feedsetname

The feedset name to query in the given context information. The default for the connect context is The default for the content filter context is karmasphere.contentfilter.



Hostname or IP address of the Karmasphere query server. The default is


Port number of the Karmasphere query server. The default is 8666.


The timeout for receiving Karmasphere responses, in seconds. The default is 15.


An identifier may be used to authenticate queries from SpamAssassin to Karmasphere. It is not required for most cases. See

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:

        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:

$self->add_connect_authentication($scanner, $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.

$self->add_connect_received($scanner, $query)

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.

$self->add_connect_envfrom($scanner, $query)

Adds the information gathered from $scanner->get('EnvelopeFrom:addr') to the given connection query packet.

$self->add_connect_other($scanner, $query)

By default, this does nothing. This is the recommended extension point for custom fields in the connection query packet.

$self->add_content_urls($scanner, $query)

Adds URLs found in the body to the given content query packet.

$self->add_content_other($scanner, $query)

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 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

Then add the following lines to the end of

 ifplugin Mail::SpamAssassin::Plugin::Karmasphere

 karma_feedset connect
 karma_feedset content

 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


 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,, Mail::SpamAssassin, Mail::SpamAssassin::Conf, Mail::SpamAssassin::Logger, "spamassassin/" 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.