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.1DESCRIPTION
The Karmasphere reputation service is a real-time reputation service for 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.
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 iskarmasphere.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 karma responses, in seconds. The default is
15. - karma_principal
-
An identifier used to authenticate client connections. This may be a login or account name. The precise details will depend on the policy of the query server being used. The default is
undef. - karma_credentials
-
The credentials used to authenticate the principal. This may be a password, or a certificate. The precise details may depend on the policy of the query server being used. The default is
undef.
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.
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.