Introduction

assassind is a SMTP mail relay that uses the SpamAssassin mail filtering system to flag messages as spam. It is meant to be used as a system-wide mail processor, especially on sites with multiple users who may have different requirements for filtering their spam. As such, it doesn't make any changes to message contents, or to a message's existing headers. Instead, it simply adds its own set of headers that users can then use in their message filtering systems (i.e., procmail or sieve).

Downloading and Installation

Debian GNU/Linux Users

If you are a Debian GNU/Linux user, simply add the following line to your /etc/apt/sources.list file, and install the assassind package.

deb http://www.rudedog.org/ debian/

All Others

assassind is a standard Perl script, and is available here. The latest version is 1.0.9.

In addition to the script, you need the following Perl packages:

SpamAssassin, natch.
The Mail-Audit package, which allows you to do all kinds of auditing on mail messages. If you're using any SpamAssassin scripts, you probably already have this package.
The Error package. This module lets Perl programs do exception handling in a OO-ish way.
The Net-Server package, a fantastic module for creating network servers in Perl.
The SMTP-Server module, by which implements a SMTP server.
The libnet package, used to implement a SMTP client.

What It Does

When assassind runs, it makes no changes to the message or its existing headers. Instead, it adds the following headers.

X-Spam-Color

This header contains a single color, which represents the likelihood that the message is spam. It uses the colors green, blue, yellow, orange, and red. Green mail is probably not spam, while red mail is so likely to be spam that you probably don't even have to look at it. If you live in the USA, these color choices may be familiar.

X-Spam-Status

This header is text of the form X-Spam-Status: Yes/No, hits=n required=n=list_of_matching_tests. This is a standard SpamAssassin header. Hits is the number of spam tests that matched (i.e., the message's total spam score). Required is the number of tests required for SpamAssassin to flag the message as spam. Finally, tests is the list of tests that passed.

X-Spam-Report

Finally, assassind adds one or more of these headers that provide a verbose report from SpamAssassin about the message. This header is mostly for your information. These headers are only added if SpamAssassin believes that the message is spam. This is typically when the message has a score greater than five.

Here are some sample headers from a recent spam message that I received that was offering me a free credit report.

X-Spam-Color: yellow
X-Spam-Status: Yes, hits=6.60 required=5.00 tests=NO_REAL_NAME,PLING,CLICK_BELOW,EXCUSE_14,CALL_FREE,CLICK_HERE_LINK
X-Spam-Report: 
X-Spam-Report: SPAM: -------------------- Start SpamAssassin results ----------------------
X-Spam-Report: SPAM: This mail is probably spam.  The original message has been altered
X-Spam-Report: SPAM: so you can recognise or block similar unwanted mail in future.
X-Spam-Report: SPAM: See http://spamassassin.org/tag/ for more details.
X-Spam-Report: SPAM: 
X-Spam-Report: SPAM: Content analysis details:   (6.6 hits, 5 required)
X-Spam-Report: SPAM: Hit! (0.6 points)  From: does not include a real name
X-Spam-Report: SPAM: Hit! (0.5 points)  Subject has an exclamation mark
X-Spam-Report: SPAM: Hit! (1.5 points)  BODY: Asks you to click below
X-Spam-Report: SPAM: Hit! (1.1 points)  BODY: Tells you how to stop further SPAM
X-Spam-Report: SPAM: Hit! (1.1 points)  BODY: Contains a tollfree number
X-Spam-Report: SPAM: Hit! (1.8 points)  BODY: Tells you to click on a URL
X-Spam-Report: SPAM: 
X-Spam-Report: SPAM: -------------------- End of SpamAssassin results ---------------------

Operation

There are a number of different ways to configure assassind. This section describes three common scenarios.

Running Between your Firewall and your Mail Server

In this scenario, the firewall accepts SMTP connections from the Internet, and is configured as a mail relay that forwards all messages to the system running assassind. assassind could be running on the same system as the mail server (but on a different port), or it could be running on a different system. assassind's default operation assumes that it is running on port 2025 and on the same system as the mail server.

If assassind and your mail server are on the same system, simply start assassind with the following command:

assassind

If assassind is on a different system, start assassind with the following command:

assassind --relayhost=mailserver.dom.ain

Running on the Firewall With an Internal Mail Server

In this scenario, the firewall itself is running assassind. It accepts messages on port 25 and forwards them to the mail server, which also listens on port 25. There are some drawbacks to this method:

SpamAssassin is fairly resource intensive, so you may need a more powerful firewall.
assassind does no anti-relay checking, so your internal mail server will have to do that. In addition, there may be some relaying tricks that can be exploited by a clever spammer. If you choose to go with this scenario, you should verify that you haven't inadvertently turned your network into a spam relay by using one of the standard open relay blackhole testing systems.
SpamAssassin is a complicated piece of software, and may have security bugs that may compromise your firewall.

To run assassind in this scenario, start it on your firewall with the command

assassin --relayhost=mailserver.dom.ain

Running on a System Directly Connected to the Internet

In this scenario, your mail server is directly connected to the Internet. To force the messages to go through assassind, your mail server is configured to listen on some other port (e.g., port 2025), while assassind is configured to listen on port 25.