The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Mail-Karmasphere-Client-2.18
River stage zero No dependents
++
/ Mail::SpamAssassin::Plugin::Karmasphere

NAME

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

SYNOPSIS

        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

DESCRIPTION

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.

USER SETTINGS

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 karmasphere.email-sender. The default for the content filter context is karmasphere.contentfilter.

ADMINISTRATOR SETTINGS

karma_host

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

karma_port

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

karma_timeout

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

karma_principal

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

karma_credentials

See karma_principal, above.

Karma_credentials corresponds to "password".

TEMPLATE TAGS

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.

INTERNALS

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.

BUGS

Ensure that Authentication-Results headers are only honoured when not preceded by a Received line.

INSTALLATION

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.

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

TODO

Use the data fields from the Karma response to construct an explanation message.

SEE ALSO

Mail::Karmasphere::Client, http://www.karmasphere.com/, Mail::SpamAssassin, Mail::SpamAssassin::Conf, Mail::SpamAssassin::Logger, "spamassassin/26_karmasphere.cf" in eg

COPYRIGHT

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.