The SpamBouncer
Version 1.4

Updated October 13, 2001

If you have a version before the current version number or more than a month older than this date, please update. If you are running in COMPLAIN mode, you should update weekly.
Please also read "What's New" for new version information. New users should run with SPAMREPLY and BLOCKREPLY set to SILENT for a week or so until they are sure the program is installed correctly and isn't catching legitimate email. Beta version users should check the Beta Version comments at the top of the SpamBouncer program file when installing a new beta version.
Copyright (C) 1996-2001 by Catherine A. Hampton. If you abide by the Free Software Foundation's COPYING principles with this document and the spam software and forms, you're home free, but don't try to copyright it yourself or sell this information.

Contents


What's New with the SpamBouncer?

10/13/01


This is a housekeeping update, although a fairly extensive one. The NIMDA virus is now trapped by the SpamBouncer, and a number of new spam sites have been added to the Small Fry and Haven Domains sections.

8/24/01


This update contains a bug-fix for the HTML spam pattern matching filter, which had a typo that was causing legitimate email to get caught. Please update.

8/22/01


This update contains the following new and improved features:

Filtering mail sent through SOCKS proxies. The SpamBouncer now filters email from a list of known open SOCKS proxy servers. These are servers that accept connections from any user on ports other than the standard SMTP port, port 25, and allow the user to send outgoing email. These servers are easily abused by spammers to send direct-to-MX email from accounts at ISPs that block outgoing connections to port 25. SOCKS proxy filtering is disabled by detault; you must explicitly enable it to use it.Tell me more...

Improved filtering of HTML spam. The SpamBouncer now catches HTML email with inappropriate headers, or that does not also contain a plain text version. The HTML email sent by Microsoft products, Netscape, and other reputable products also contains a plain text version for those whose email software does not understand HTML. I have seen no legitimate personal email that comes as HTML only. Bulk email, especially marketing bulk email, sent by some non-spamming sites to subscribers does contain HTML. Since you are supposed to filter out your bulk email before sending it through the SpamBouncer, this filter should not result in loosing email you want to receive.

"Optin" Incorporated -- a new, prolific spammer. Spam sent through opthost.com or any IP address associated with Optin Incorporated now is filtered out. This spammer has sent approximately ten spams to various email addresses of mine in the last week, and I've received forwarded spam from a number of you as well. That justifies going after the idiots more aggressively than I normally would a new spammer. If you have SPAMREPLY set to COMPLAIN, complaints are sent to the appropriate upstream providers.

Improved spam complaints code. This allows the SpamBouncer to accept and respond appropriately to several incoming emails at once, and prevents a rare but annoying bug that resulted in a complaint containing copies of two spam messages. Most of you would not have experienced this problem, but users with high rates of incoming email (you know who you are) will find that their complaints now will contain only the appropriate spam and not an additional, unrelated spam as well.

In addition, there have been a bunch of updates to the Small Fry list, haven domains filter, and other pattern matching filters.

8/05/01


NOTE: The SpamBouncer Updates mailing list blew up this morning while processing subscriptions. Unfortunately I didn't keep a copy of the subscriptions file. :( So if you attempted to subscribe within the last two months, that is why you didn't get update notice in your email. Please resubscribe.

This was an extensive update. Among the more important changes, and changes most affecting users, are the following.

Filtering at the Mail Server Level. The new FILTER variable allows you to use the SpamBouncer to filter incoming email and then deliver it to multiple mailboxes on your system, or forward it to different locations.Tell me more...

Blackhole List Support. In the last three months, ORBS has gone away entirely, MAPS has gone subscriber-only, and a raft of new blackhole lists with a bewildering range of criteria have started up. In response to this,I've made the following changes to the SpamBouncer's blacklist support:

  • The MAPS RBL is no longer enabled by default. As of August 1, 2001 you must subscribe to MAPS to use the MAPS DUL (Dial-Up List), RBL (Realtime Blackhole List), and RSS (Relay Spam Stopper). Contact MAPS <http://www.mail-abuse.org> to become a subscriber. (Yes, I have done so -- I consider MAPS an asset to the community, free or not.) Tell me more...

  • The Open Relay Blackhole System (ORBS) is gone. Support for it has been removed from the SpamBouncer.

  • Support for six new blacklists has been added. These blacklists are:

Email Virus filtering. The SpamBouncer now filters out five common email viruses, including the destructive SirCam worm. In addition, it looks for and filters out any email with a hidden executible attachment.Tell me more...

Advance Fee (4-1-9) Fund Fraud Spam. The SpamBouncer has a new filter to detect advance fee fraud spam. The 4-1-9 advance fee fraud started and is centered in Nigeria, but in the last year has migrated to a number of countries in West Africa. The fraud takes place via postal mail and fax, as well as email. Victims have lost significant sums of money, and in a few cases their lives, to these vicious criminals. :( If you have COMPLAIN or BOTH set to yes, the SpamBouncer will report any instances of this spam you receive to an international task force that is working to stop it.

Bugs fixed in SpamBouncer and sample procmail.rc file. Several bugs were fixed, including a bug in the Disclaimer pattern match filter that was occasionally catching email based on header strings. In addition, a long-reported bug in the procmail.rc file that misfiled bulk email has been fixed.

Spam Sites. There are a number of new recipes for sites that spam from a fixed location. If you have COMPLAIN or BOTH set to yes, the SpamBouncer will complain to the upstream providers of these sites.

Updated Small Fry list, Pattern Matching filters, etc. The usual housekeeping updates have been done.

I'd like to thank David Hampton, Eric Krichbaum, and Peter Wan for their help with the new virus filters; and too many people to list here for bug reports on the SpamBouncer, the sample procmail.rc filter, and the web page. :) You people are great!

Return to Table of Contents

What Does the SpamBouncer Do?

The SpamBouncer is a set of procmail recipes, or instructions, which search the headers and text of your incoming email to see if it meets one or more of the following conditions:

The SpamBouncer sorts suspected spam into three categories -- email sent by a virus, email from known spam sources which is definitely spam, and email which is probably spam, but might also be legitimate. It then tags each email with appropriate headers for the spam classification, and responds according to the parameters you have set.

Depending on how you set it up, it will:

If you get mail from friends who have accounts at a site listed in the SpamBouncer, you can put their names and email addresses in a text file and set the NOBOUNCE variable to point to it. If you want to receive mail from a site I have listed as a spam site, you can add the entire site name to the NOBOUNCE file. The SpamBouncer will check the NOBOUNCE file before filtering your email and will skip any email from a person or site listed in the NOBOUNCE file.

Please note that you can put entire domain names, not just email addresses, in NOBOUNCE. For example, if you want to accept all email from concentric.net without checking for spam, just put concentric.net in your NOBOUNCE file, with no username@ section. This will cause the SpamBouncer to skip all email from anyone at Concentric. (I do not recommend doing this except for small domains which you =KNOW= will not be sources of spam, though.)

What Do I Need to Run the SpamBouncer?

The SpamBouncer itself must run on a Unix server which has the Procmail mail filtering program installed, so only users who have access to a Unix shell account with Procmail installed can use it. This means that AOL users, Earthlink users, Mindspring users, Netcom Netcruiser/Netcomplete users, Compuserve users, Prodigy users, and others who do not have a Unix shell account as part of their service will have to find some other means of filtering spam. Sorry!

It is possible, however, for people who use Eudora, Pegasus Mail, and other POP clients to use the SpamBouncer on their Unix shell accounts to filter their email, and then use their favorite POP mail client to retrieve their filtered mail from the server. If their POP client programs can filter mail by headers, they can filter and delete known spam and probable spam directly into appropriate folders via the SpamBouncer's headers.

This means that anyone running any kind of computer, operating system, and software can use the SpamBouncer, provided they have and use a Unix shell account, and (if they want to use a POP mail program) have software capable of filtering their mail based on user-configurable headers.

If you are totally confused by now, PLEASE find a friend who understands what this means before you try to install the SpamBouncer. While I have made this as user-friendly as I could, using the SpamBouncer requires a certain level of knowledge about computers and the internet. It is not for computer or internet novices.

Return to Table of Contents

Before You Begin...

Because someone who evidently likes the SpamBouncer listed it for me in Yahoo and other search engines <wry grin>, I need to include the following disclaimers and warnings.

First, this is free software. No warranty is provided or implied -- users use the SpamBouncer at their own risk.

I wrote the SpamBouncer originally to filter my own mail, when spam started drowning out the real mail. I originally posted these filters to my web site so that users at my old ISP, Best Internet (long since bought out by Verio), and a few other experienced users could help me test them. I recommend that Procmail neophytes get help from an experienced Procmail user on their system to install the SpamBouncer, and run it in default "Silent Mode" until they are more confident of their skills.

The SpamBouncer is being developed on a Pentium-based server running OpenBSD, and running Procmail 3.14.

In addition to the Pentium-based system where I am developing the SpamBouncer currently, I have developed and tested the earlier versions of it on Linux, FreeBDS, SGI systems running Irix 5.3 and 6.2, SunOS 4.1.3, and Solaris 5.2. I know of no problems running on these systems. A number of users have also run the problem under various flavors of SunOS, Solaris, HPUX, and other versions of Unix with no trouble.

So please be careful, and keep a close eye on your account for a few days after installing to be sure it works properly.

Return to Table of Contents

How to Install and Use the SpamBouncer

Installing Procmail

To use these filters, you will need to have procmail installed on your system, and have set it up for your account. This does not mean you must read mail on your unix account -- if you have a shell account, these filters can be configured to filter mail and then deliver it to your POP mail box. If you don't know what kind of account you have, you probably shouldn't be using these filters until you learn something about Unix and shell accounts.

Since the way Procmail should be installed is different on different systems, if you do not already have Procmail installed, you will need to ask your system administrator or people on your local internet service provider for help. Those who have never used Procmail and want to get started with a simple Procmail setup can jump to Getting Started With Procmail, a tutorial with clear instructions about what information you will need to get from your system administrator to set up Procmail properly on your account, and a basic .procmailrc configuration file which should work well on most systems.

If you are an experienced Procmail user, please make sure that your .procmailrc file is configured to filter out your mailing lists before filtering for spam. The SpamBouncer tries to identify list mail and skip it, but some mailing lists do not use standard list "Precedence:" headers or headers recognisable by Procmail as coming from a daemon or list program. So please be sure you filter out your lists first, especially if you are running with SPAMREPLY set to BOUNCE or COMPLAIN!

In any event, you should always run in SILENT mode for a few days, until you are sure you have your mailing lists filtered out properly and that the filter is working properly on your account.

If you did not use procmail.rc from Getting Started With Procmail, here's a recipe to filter out list mail and other mail from automatic mailer programs, or mailer daemons, as they are usually called on Unix machines. Put it in your .procmailrc file before the INCLUDERC statement that calls the SpamBouncer.

# Filter out Mailing List Mail
:0:
* ^TO(listmom-talk@skylist.com|\
      orthodoxy@lists.best.com|\
      procmail@Informatik.RWTH-Aachen.DE)
$BULKFOLDER

You should substitute all mailing list addresses for mailing lists you receive for the list I gave -- you and I don't read mail from the same lists, at least as far as I know! :)

Return to Table of Contents

Retrieving the SpamBouncer Program Files

After you have installed Procmail for your system, you can install the SpamBouncer. You will need to download the SpamBouncer program files to your Unix account first. You can do this one of two ways -- by downloading them from the links below to your personal computer, or by ftp'ing them. The advantage to ftp is that it ensures that the file format will be right. Often, when you retrieve a text file using a WWW browser and then save it to your hard disk, the browser reformats the file. This type of reformatting can break Procmail configuration files like the SpamBouncer.

Lynx users should note that lynx reformats text files when downloading them via a normal link access command, which will break the SpamBouncer and most other Procmail scripts. If you're a lynx user, please remember to use the "D" command to download the SpamBouncer files instead of just accessing the link, or (even better) ftp the files from the links in the FTP column instead of trying to retrieve them from the http:// links in the WWW/HTTP column.

Via FTP
Via WWW/HTTP

To ftp the SpamBouncer, you must do this:

  1. Log on to your shell account, and type "cd" to be sure you are in your home directory.
  2. Type, "ftp ftp.spambouncer.org", and press <Enter>.
  3. When ftp prompts you to login, type "anonymous", press <Enter>, and then when prompted for your password, type your email address, and press <Enter> again. (This will log you in and take you to the location where the SpamBouncer files are stored.)
  4. Depending on whether you want to download the complete SpamBouncer archive or update an existing installation, you will need to do slightly different things at this point:
    • To retrieve the entire SpamBouncer program archive, when your prompt returns, type "binary" and press <Enter>. When your prompt returns, type "get spambnc.tar.Z" and press <Enter> to retrieve the Spam Bouncer archive.
    • To retrieve a compressed individual file or files to update an existing SpamBouncer installation, when your prompt returns, type "binary" and press <Enter>. When your prompt returns, type "get filename" and press <Enter>.
    • To retrieve an uncompressed individual file or files to update an existing SpamBouncer installation, when your prompt returns, type "ascii" and press <Enter>. When your prompt returns, type "get filename" and press <Enter>.
  5. When your prompt returns, type "bye" and press <Enter> to end your ftp session.

To download the SpamBouncer via your WWW browser, choose one of the links below and, when your web browser prompts you, save the file to your hard disk. The ZIP archives contain files intended for your PC, and the tar.Z archives contain files intended for your Unix server.

Here are FTP download URLs for the convenience of Lynx users or users of other browsers who are having trouble with file corruption when downloading the SpamBouncer from the standard HTTP urls above. Please use the links below only if the other links don't work for you.

Now, if you saved the SpamBouncer files on your local PC, you will need to ftp or upload them to your unix shell account. They should be put in their own directory.

To unarchive the ZIP format archive, type "unzip spambnc.zip" and press <Enter>. (Your Unix machine may respond with an "unzip: command not found" error message. If it does, you may not have the Unix program unzip, and should retrieve the tar.Z archive.) To unarchive the tar.Z file, type "uncompress spambnc.tar.Z", press <Enter>, and then type "tar -xvf spambnc.tar" and press <Enter> to extract the individual files.

Return to Table of Contents

The SpamBouncer Files and What They're For

The "index" file of the SpamBouncer, which may be named sb.rc, sb-old.rc or sb-new.rc depending on which version you downloaded, contains the basic script that calls all other files and scripts that comprise the SpamBouncer. The current production version of the SpamBouncer is the one containing sb.rc. The version containing sb-old.rc is the previous production release of the SpamBouncer. The version containing sb-new.rc is the current somewhat stable beta version.

Inexperienced users or users who don't want problems should not use the beta version, and all beta version users need to follow any warnings/instructions listed among the comments at the top of sb-new.rc.

All other files ending in .rc are subsidiary parts of the SpamBouncer that are called by the "index script".

The freemail file contains a sample text file which you may install and then set your FREEMAIL variable to point to. You do not need to install this file unless you want to customize the list of free email sites -- the SpamBouncer will use its own internal list if it can't find the text file.

The "legitlists" file contains a text file with the names of legitimate email lists (the opt-in variety), which you may getting trapped by the SpamBouncer. Just put each mailing list address on a separate line, just as you would with the NOBOUNCE file.

The other three files contain standardized autoresponder messages for the program. You may customize these to your taste. I do recommend that you leave the references to the SpamBouncer bypass email address in any edited version of the file spam, though, so that people know how to contact me if their mail is getting bounced because of a problem with the filter itself, or how it is installed. That way, I can contact you (hopefully), and prevent further damage.

If you customize the autoresponder messages, you probably want to keep them reasonably polite. There's no point flaming some poor innocent bystander because you're p*ssed at some spamming fool with a throwaway account. :)

Return to Table of Contents

Where to Put the SpamBouncer

The best way to use the SpamBouncer is to save the files in a location to which everyone on your system has read access. If you aren't sure how to do this, ask you system administrator or an experienced user on your system. If you install the filter this way, a user can create a symbolic link to the shared SpamBouncer directory in his home directory. This means you or one person can keep the filter up to date for everyone, sparing a lot of people a lot of extra work.

If a particular user wants to modify the filter, he can simply create a private directory, copy the necessary files to it, and make whatever changes he wants. If he does the last, of course, he is responsible for updating his copy of the filter manually.

Return to Table of Contents

Configuring the SpamBouncer

After setting up the SpamBouncer directory, you should set or modify the following variables in your .procmailrc file:

     DEFAULT={NO DEFAULT}
     FORMAIL={NO DEFAULT}
     SBDIR={NO DEFAULT}
     ADMINFOLDER=${DEFAULT}
     ALTFROM=${LOGNAME}@${HOST}
     BLOCKFOLDER=${DEFAULT}
     BLOCKREPLY=SILENT
     BULKFOLDER=${DEFAULT}
     BYPASSWD=syzygy
     CHINESE=no
     DATE=date
     DEBUG=no
     DORKSLCHECK=no
     DULCHECK=no
     FILTER=no
     FREEMAIL=INTERNAL
     GARBLEDCHARSET=yes
     GLOBALNOBOUNCE=NONE
     GREP=fgrep
     JAPANESE=no
     KOREAN=no
     LEAN=yes
     LEGITLISTS=NONE
     MYEMAIL=$HOME/.myemail
     NOBOUNCE=${HOME}/.nobounce
     NOLOOP=${ALTFROM}
     NSLOOKUP=nslookup
     ORBLCHECK=no
     ORBZINCHECK=no
     ORBZOUTCHECK=no
     ORDBCHECK=no
     OSDIALCHECK=no
     OSSPAMCHECK=no
     PATTERNMATCHING=SILENT
     PROXYSOCKS=no
     RBLCHECK=yes
     RM=rm
     RSSCHECK=no
     RUSSIAN=no
     SENDMAIL=/usr/sbin/sendmail
     SPAMFOLDER=${DEFAULT}
     SPAMHAUSORGCHECK=yes
     SPAMREPLY=SILENT
     TEST=test
     THISISP=${HOST}
     TURKISH=no
     VIRUSFOLDER=${SPAMFOLDER}

The variables are shown with the default values which the SpamBouncer will assign if they are not already set in your .procmailrc file. These defaults will prevent problems, but also will cause the SpamBouncer not to do very much. So you want to set the correct variables for your system and account.

Please note that those variables in red have no defaults and MUST BE SET or the SpamBouncer will simply pass all your mail on to you unfiltered!

Here's what each variable is for:

DEFAULT
The email inbox to which your system delivers mail by default, or (if you use your shell account to read mail) to which you want your mail delivered by default. If you normally read mail using a POP mail program, like Eudora, Internet Explorer, Netscape, or Pegasus mail, ask your system administrator for the name and location of your POP mailbox, and set DEFAULT to that path and file name.

FORMAIL
The full path to your system's copy of formail. If this is not set properly, the SpamBouncer is unable to sort and tag your email, and so will simply pass it on unfiltered to you.

SBDIR
The directory where your SpamBouncer program and auxiliary files are located.

ADMINFOLDER
ADMINFOLDER is for mail from mailer daemons (usually bounced mail -- mail that could not be delivered), and for mail from administrative addresses like root, admin, sysadmin, and abuse. Shell readers will want to set this to an appropriate folder separate from their DEFAULT folder. (I use admin.incoming.) POP mail readers may set this to DEFAULT, and use their POP program's filters to sort it out after downloading.

ALTFROM
ALTFROM should be set a different email address than your usual email, but a valid address, and preferably one which DOES NOT forward to your normal email account. This is used to avoid giving spammers at some particularly egregious sites your usual email address, and to bypass blocks that some spammers and spam friendly sites will put to prevent your sending them mail if you complain often enough and effectively enough. I recommend using an account at a free email site, like yahoo.com, for this purpose.

BLOCKFOLDER
Where to store message tagged as questionable by the filter. I recommend not deleting these, but putting them in a folder of their own. I use block.incoming. POP mail users whose client programs have the ability to filter mail into separate folders (like Eudora and Pegasus mail) can set this to DEFAULT, and let their mail filters sort it into an appropriate folder on their home systems. Users of MAILDIR may set BLOCKFOLDER to a directory rather than a filename, and users with exotic ideas about spam management <grin> may forward this email to a different address using normal sendmail syntax.

BLOCKREPLY
How to handle mail which the filter tags as probable spam, but which may contain some real email as well. Valid values are SILENT, which simply files the mail in the BLOCKFOLDER, and NOTIFY, which sends a notice and copy of his email back to the sender with instructions on how to bypass the SpamBouncer if his email is not spam.

BULKFOLDER
How to handle bulk mail which the filter does not tag as probable spam -- bulk email which is probably legitimate. The default value is DEFAULT. If you read mail on your shell account, change this to a separate folder from your normal incoming folder, especially if you get a lot of email or are on many mailing lists, and you'll be able to find your personal mail much more easily. :)

BYPASSWD
A password which, when included on the Subject: line of an email, causes the SpamBouncer to pass the mail immediately into your incoming mail box without further filtering. It allows people who happen to have accounts at ISPs which are blocked in the SpamBouncer, or whose email is being trapped by an error in the SpamBouncer, to contact you and arrange to have the problem fixed or get into your nobounce list. Change this if spammers start using it, but it is very unlikely tht they will. (It never has happened to me in the three years since I started developing the SpamBouncer.)

CHINESE
Set CHINESE=yes if you receive email in Chinese. Otherwise leave it set to no (the default), and the SpamBouncer will send any email in this language to the BLOCKFOLDER.

DATE
The local Unix date program. This is set to "date" by default, since date is usually in a directory which is in your default system path. (The system path is a list of directories your Unix shell searches when you tell it to run a program and don't tell it specifically where to look.)

If your SpamBouncer's staledating routine is working and it is turning its autocomplaints off when you haven't upgraded recently, there is no need to set this -- the default is usually correct. If staledating is not working, set this variable to point to your system's date program and that should fix the problem.

DEBUG
Set DEBUG=yes if instructed, to generate a log file so that I can figure out what's going wrong on your system. :> When I refine this variable, it might be useful to advanced Procmail users, but for now do not use it unless I instruct you to.

DORKSLCHECK
If set to "yes", tells the SpamBouncer to check the Dorkslayers blacklist, which lists IP addresses of open mail relays, and block email sent to your system via one of these IP addresses. That will block a considerable amount of spam. It also risks blocking legitimate email, since for various reasons a number of ISPs and business do not choose to close open relays. You can avoid blocking email from users who must use an open relay by putting the email address of any such user in your NOBOUNCE file.

This variable is set to no by default.

The Dorkslayers blacklist, at <http://www.dorkslayers.com>, is a "son of" the original Dorkslayers blacklist created by Alan Hodgson, and of the original ORBS blacklist managed by Alan Brown. It contains relays that were on both lists shortly before they were shut down. Its policy about adding relays is a bit undefined; I would not count on this list being up-to-date.

DULCHECK
If set to "yes", tells the SpamBouncer to check the Mail Abuse Prevention System (MAPS) Dial-Up List (DUL), which lists IP addresses that are part of ISP dial-up pools, and block email sent directly to your system from these IP addresses. As of August 1, 2001 you must subscribe to MAPS to use the DUL. Contact MAPS at <http://www.mail-abuse.org> to subscribe. The DUL will block a considerable amount of spam. It also risks blocking legitimate email, though, especially if you correspond with users who own Unix systems and run their own mail servers. You can work around this by putting the email addresses of any such users in your NOBOUNCE file.

This variable is set to "no" by default.

The DUL, at <http://www.mail-abuse.org/dul/>, is designed to stop spam sent directly from a spammer's computer to your mailbox. Spammers often bypass their ISPs outbound mail servers in order to hide what they are doing from their ISPs for as long as possible. The DUL helps catch this spam.

FILTER
If set to "yes", tells the SpamBouncer not to file blocked email, spam, or suspected virus email in the appropriate folder, but to pass it on to the user along with the other email. The user must then use his/her own filters to process this email. This variable is intended for administrators who want to use the SpamBouncer to filter incoming email for an entire server before delivering it to individual users. The individual users can then choose whether to filter their own email using the SpamBouncer's headers or to ignore the headers and receive their email unfiltered.

This variable is set to "no" by default.

FREEMAIL
Tells the SpamBouncer where to find your freemail file, a text file of domains offering free email accounts commonly used or forged by spammers. The domains should be listed singly, with one appearing on each text line, and with no blank lines in the file. Be sure you do not create an empty FREEMAIL file, either.

In addition to the name of this text file, this variable has two other valid settings. If FREEMAIL is set to INTERNAL, that will cause the SpamBouncer to filter its default set of free email sites, as documented on this WWW page. If FREEMAIL is set to NONE, the SpamBouncer will skip this filter entirely and not block any free email sites. Setting FREEMAIL to NONE will not exempt mail from these sites from other spam filtering, though -- it will simply mean that such mail is not automatically diverted to your BLOCKFOLDER.

GARBLEDCHARSET
Controls the GARBLEDCHARSET filter, which tests for email with non-Latin character sets, and missing, wrong or corrupted MIME headers which should accompany any such character sets. This filter has been refined considerably, but may still occasionally catch email in heavily-modified Latin character sets (such as Baltic or some Eastern European languages), and will tend to catch email with non-Latin character sets, such as Russian, Greek, Arabic, Hebrew, etc.

The default for this variable is yes, which enables this filter. Users who expect to receive email in a non-Latin character set, or who find it is catching too much legitimate email, can set this variable to no to disable the filter.

GLOBALNOBOUNCE
Points to a system-wide nobounce file, if your system administrator has provided one or if you are the system administrator and want to provide one. Please note that this is in addition to each user's individual NOBOUNCE file, and does not replace it. If you do not set this variable, it is automatically set to NONE, so you need to set it only if you have a system nobounce file.

See NOBOUNCE for a more complete description of how this file works.

GREP
A variant of Unix grep, a set of programs which searches files on Unix systems for specified strings of characters. This is set by default to "fgrep", a fast version of grep which is usually found in a normal system programs directory on Unix machines. Most versions of fgrep work properly with the SpamBouncer.

If NOBOUNCE and LEGITLISTS are working on your system, there is no need to set this variable. If NOBOUNCE is not working, set this variable to point to one of your system's grep programs other than fgrep. Usually egrep will work, or agrep if that does not.

JAPANESE
Set JAPANESE=yes if you receive email in Japanese. Otherwise leave it set to no (the default), and the SpamBouncer will send any email in this language to the BLOCKFOLDER.

KOREAN
Set KOREAN=yes if you receive email in Korean. Otherwise leave it set to no (the default), and the SpamBouncer will send any email in this language to the BLOCKFOLDER.

LEAN
This variable turns off Pattern Matching on the body text only of messages over a certain size, and is set to yes by default. This is to prevent the SpamBouncer from hogging system resources on your server while filtering extremely large messages. The SpamBouncer is a large filter and can hog resources on an ISP or shared system if this limit is not in place.

Set LEAN=no only if you receive large quantities of spam with attached files, and then only if you run your own server or know that the server on which your email is filtered has sufficient resources to run the SpamBouncer on the full text of all incoming email.

LEGITLISTS
Tells the SpamBouncer about legitimate mailing lists which the SpamBouncer should not filter, but should deliver to the BULKFOLDER. Your LEGITLISTS file (whatever you name it and wherever you put it) should contain one email list address per line of text, and nothing else, like this:

     chitchat@borg.besties.com
     dylan-fanatics@lists.musicman.net

If you do not set this variable, it is automatically set to ${HOME}/legitlists. If the file does not exist, the SpamBouncer just skips this recipe.

MYEMAIL
Points to a text file similar to the NOBOUNCE file, containing a list of email addresses which belong to you. This helps the SpamBouncer with a number of internal routines, and will be implemented in future spam tests, as well. The default is ${HOME}/.myemail. If you do not set this variable to a different value, and if there is no .myemail file in your ${HOME} directory, the SpamBouncer will assume that ${LOGIN}@${HOST} is your email address.

NOBOUNCE
Tells the SpamBouncer where to find your NOBOUNCE file, a text file of email addresses and domains whose email you want the Spam Bouncer to skip filtering and deliver directly to you. Set this to point to the directory and filename where you keep that file. I name mine ".nobounce" and keep it in my home directory, and this is where the SpamBouncer looks if you don't set this variable.

Your NOBOUNCE file (whatever you name it and wherever you put it) should contain one email address per line of text, and nothing else, like this:

     goodguy@spamsite.com
     niceguy@roguesite.net

Please note that these names and addresses should be in plain text -- don't use Procmail regular expressions or wildcards, and don't try to escape the "." (periods) using a "\" (backslash). This will just confuse the SpamBouncer and cause your NOBOUNCE file not to work. :)

You can also include entire domain names (the portion of the email address to the right of the @ sign) if you want the Spam Bouncer to accept all email from anyone at those domains without checking. I do not recommend doing this, however, except for small domains which you know will not either send spam or be forged into spam by spammers. Since spammers often forge false email addresses in the From: and Reply-To: lines of their messages, you need to be careful or you will make it too easy for them.

In particular, do not put your own domain in your NOBOUNCE file, since a number of spammers use mailmerge spam programs to forge their victims' own email addresses or a phony email address at their victims' domains into their spams, specifically in order to evade filters like the SpamBouncer.

NOLOOP
Sets the X-Loop: header. I recommend leaving the default setting, which uses your ALTFROM address.

NSLOOKUP
Tells the SpamBouncer the path and filename of your system's nslookup program. You need to set this only if nslookup is not in your path (the list of directories which your system will search for a program) or if you have an alias set up for nslookup on your account. If you aren't having trouble getting RBLCHECK and DULCHECK to work on your system, you can leave this alone.

ORBLCHECK
If set to "yes", tells the SpamBouncer to check relays.orbl.org, the Open Relay Black List at at <http://www.www.orbl.org>, to see if an IP address is an open relay. The ORBL lists IP addresses associated with email servers which an automated script tested and found to be open relays. An email server listed in the ORBL has not necessarily been used to send spam; it merely can be used to do so. Using this or any open relay blacklist can result in blocking a considerable amount of legitimate email as well as spam, if you correspond with people at sites that host open relays.

This variable is set to no by default.

ORBZINCHECK
If set to yes, tells the SpamBouncer to check the Open Relay Blackholed Zones list, at <http://www.www.orbz.org>, to see if an IP address is a single-stage open relay. The ORBZ lists IP addresses associated with email servers which an automated script tested and found to be open relays. This list closely corresponds to the old ORBS inputs list. An email server listed in ORBZ has not necessarily been used to send spam; it merely can be used to do so. Using this or any open relay blacklist can result in blocking a considerable amount of legitimate email as well as spam, if you correspond with people at sites that host open relays.

This variable is set to no by default.

ORBZOUTCHECK
If set to yes, tells the SpamBouncer to check the Open Relay Blackholed Zones list, at <http://www.www.orbz.org>, to see if an IP address is part of a multi-stage open relay. This list closely corresponds to th eold ORBS outputs list.

This variable is set to no by default.

ORDBCHECK
If set to yes, tells the SpamBouncer to check the Open Relay Database, at <http://www.www.ordb.org>, to see if an IP address is an open relay. This list closely corresponds to the old ORBS inputs list. An email server listed in the ORBL has not necessarily been used to send spam; it merely can be used to do so. Using this or any open relay blacklist can result in blocking a considerable amount of legitimate email as well as spam, if you correspond with people at sites that host open relays.

This variable is set to no by default.

OSDIALCHECK
If set to yes, tells the SpamBouncer to check the Osirusoft Dial-Up blacklist at <http://relays.osirusoft.com>, to see if an IP address belongs to a dial-up pool. This list is designed to closely correspond to the MAPS DUL, except that you do not have to subscribe to use it.

This variable is set to no by default.

OSSPAMCHECK
If set to yes, tells the SpamBouncer to check the Osirusoft Confirmed Spam Sources blacklist at <http://relays.osirusoft.com>, to see if an IP address belongs to a site with a confirmed history of spamming or supporting spammers. This list is designed to closely correspond to the MAPS RBL, except that you do not have to subscribe to use it.

This variable is set to no by default.

PATTERNMATCHING
How to handle mail which the generic pattern matching filter tags as probable spam, but which may be legitimate email. Valid values are NONE, which skips pattern matching entirely; SILENT, which simply files the mail in the BLOCKFOLDER; and NOTIFY, which sends a notice to the sender that his email was blocked, and explains how to bypass spam filtering if his email was legitimate.

I recommend that users set this value to SILENT. Pattern matching occasionally filters out legitimate email -- there is no way to prevent this entirely. Since more and more spammers are using throwaway accounts, though, and forging their headers so heavily that it is difficult to spot spam through header analysis alone, setting PATTERNMATCHING to NONE will reduce the effectiveness of the SpamBouncer considerably.

The default setting for this variable is NONE, however, because I want to be sure that if you're using it, you have actually read these instructions and know that you are using it. So, if you want to enable it, you must set PATTERNMATCHING to SILENT in your .procmailrc.

PROXYSOCKS
If set to yes, tells the SpamBouncer to check its internal list of known open SOCKS proxy servers and filter out email sent via those servers. A SOCKS proxy server is a server that accepts inbound connections via a port other than the standard SMTP port, port 25, and allows a user to send outgoing email. Email sent through these servers is usually spam.

If such a server is secure and requires users to log on or authenticate themselves before sending email, the server does not pose a problem to the rest of us. An open SOCKS proxy server, however, is easily abused by spammers to send spam, even from dial-up accounts at ISPs that block outgoing SMTP connections. An open SOCKS proxy server is like an open SMTP relay, but with the added disadvantage that large ISPs cannot easily prevent access to such servers from their dial-up accounts. Because of this, some new spamming software is specifically designed to take advantage of such servers.

This variable is set to no by default. To enable SOCKS proxy filtering, set PROXYSOCKS=yes in your .procmailrc file.

RBLCHECK
If set to yes, tells the SpamBouncer to check the Mail Abuse Prevention System (MAPS) Realtime Blackhole List (RBL), which lists IP addresses associated with domains which have spammed repeatedly, and which have failed to clean up their acts despite the RBL team's efforts and assistance. As of August 1, 2001 you must subscribe to MAPS to use the MAPS RBL (Realtime Blackhole List). If you want to use the RBL, contact MAPS <http://www.mail-abuse.org> and become a subscriber. Sites listed on the RBL are highly likely to be the sources of spam, and will rarely be sources of email you want to receive.

This variable is set to no by default. To enable RBL-based filtering, set RBLCHECK=yes in your .procmailrc file.

RM
Tells the SpamBouncer the path and filename of your system's rm program -- the program which deletes files. You need to set this only if rm is not in your path (the list of directories which your system will search for a program) or if you have an alias set up for rm on your account. If you aren't having trouble with the SpamBouncer leaving temporary files on your system, you can leave this alone.

RSSCHECK
If set to yes, tells the SpamBouncer to check the MAPS Relay Spam Source (RSS) blacklist, which lists IP addresses associated with mail servers which are open relays, and through which spam has been sent at least once. As of August 1, 2001 you must subscribe to MAPS to use the RSS. If you want to use the RSS, contact MAPS <http://www.mail-abuse.org> and become a subscriber.

A relay listed in the RSS is not just an open relay; it is an open relay known to spammers which has been used to spam. The RSS blacklist is generally considered less aggressive than the other open relay blacklists, although they both list open relays. As such, it should block less legitimate email than the other blacklists, but will also miss spam sent through relays which have not been abused previously.

This variable is set to no by default. To enable RSS-based filtering, set RSSCHECK=yes in your .procmailrc file.

SENDMAIL
The full path to your system's copy of sendmail. The default value is /usr/sbin/sendmail, which will work on some systems, but not all. On almost all systems which use sendmail, however, this variable is set correctly as a global default by the system administrators. It does not hurt to check and be sure, though. If SENDMAIL is not set correctly, the SpamBouncer will be unable to send any autoreplies.

SPAMFOLDER
Where to store messages tagged as spam by the filter. If you want to just delete spam, set SPAMFOLDER to /dev/null. If you want to put the stuff in a backup folder, set SPAMFOLDER to a filename, perhaps spam.incoming. POP mail users whose client programs have the ability to filter mail into separate folders (like Eudora and Pegasus mail) can also set this to DEFAULT, and let their mail filters sort it into the trash folder or a special spam folder, if they want to engage in some spam tracking. :) Users of MAILDIR may set BLOCKFOLDER to a directory rather than a filename, or you may forward this email to a different address using normal sendmail syntax.

SPAMHAUSORGCHECK
If set to yes, tells the SpamBouncer to check its internal list of sites on Steve Linford's spamhaus.org web site. These sites are mostly unrepentant and aggressive spammers. You are very unlikely to get legitimate email from any of them.

This variable is set to no by default. To enable spamhaus.org filtering, set SPAMHAUSORGCHECK=yes in your .procmailrc file.

SPAMREPLY
How to handle mail which the SpamBouncer tags as definitely spam, and which should contain no valid mail whatsoever. Valid values are SILENT, which simply files the mail in the SPAMFOLDER; BOUNCE, which sends a simulated MAILER-DAEMON bounce message to the spammer in hopes that he will think your address is no good and remove it from his list; COMPLAIN, which sends a complaint and copy of the spam to the spammer's postmaster for spammers which the SpamBouncer knows about and has this information, and in most cases also the upstream ISPs; and BOTH, which (not surprisingly) both sends a bounce and complains.

New users should set this to SILENT until they're sure everything is working properly.

TEST
A variant of Unix test program, a small program which looks for a file or directory and reports whether it exists or not. This is set to "test" by default, since this program is normally found on the system path.

If NOBOUNCE and LEGITLISTS are working on your system, there is no need to set this variable. If NOBOUNCE is not working, set this variable to point directly to your system's test program.

THISISP
Tells the SpamBouncer the domain name of your domain or ISP. This can be useful when you have a private domain which is different from the domain your mail server uses, as many people using an ISP will. This is set to ${HOST} by default; if your private domain is different from your ISP, set this variable to your private domain.

TURKISH
Set TURKISH=yes if you receive email in Turkish. Otherwise leave it set to no (the default), and the SpamBouncer will send any email in this language to the BLOCKFOLDER.

VIRUSFOLDER
Where to store messages that the SpamBouncer tags as viruses. This is set by default to the SPAMFOLDER. After you have tested your setup and are certain it works, you may want to change this to /dev/null. Virus-infected email is almost always email the user has no idea he/she sent. It contains nothing most people would want to see, and if you retrieve it into most of the popular Windows-based email programs, you might infect your system.

After setting the variables in your .procmailrc, add this line to your .procmailrc file at the point where you want to filter your mail for spam:

     INCLUDERC=${SBDIR}/sb.rc

This line should appear after recipes for mail you don't want to filter for spam and before recipes for mail you do want to filter for spam. Users of procmail.rc will have the correct lines in the correct location already, and will just need to uncomment whichever one they want to use.

Return to Table of Contents

Special Instructions for Eudora and Other POP Mail Clients

Users who get their mail using Eudora, Pegasus Mail, or another POP mail client which can filter mail by headers will need to set up their filters to look for the following headings:

X-SBClass: Admin
This header indicates mail sent to the ADMINFOLDER. You should create a folder for Admin mail on your client program, and then set your client program's filter to look for this header and filter mail which has it into the Admin folder.

X-SBClass: Blocked
This header indicates mail flagged as probable spam, but not certainly so. Create a folder for Blocked mail and set your client program's filters to put mail with this header into the Blocked Mail folder.

X-SBClass: Bulk
This header indicates mail flagged as bulk mail which is probably legitimate, such as that from known opt-in mailing lists or sent using known legitimate mailing list software, and which passed spam filtering. I recommend creating a separate folder for such mail, though, since that will make it easier to spot personal email, which is usually more important and should get priority.

X-SBClass: OK
This header indicates personal email which passed the spam checks. Set your client program's filters to put this mail in the normal incoming folder.

X-SBClass: Spam
This header indicates mail flagged as definitely spam. Most POP users will simply set the SpamBouncer to delete this mail outright. If you have set the SpamBouncer to deliver it to your POP mail account, though (perhaps because you want to learn more about spam), it will arrive with this header. Create a folder for Spam and set your POP client's program filters to put mail with this header in the Spam folder.

X-SBClass: Virus
This header indicates mail flagged as a virus. POP users should set the SpamBouncer to delete this mail outright.

Return to Table of Contents

Upgrading the SpamBouncer

Upgrading is easy. You just check the "What's New" notice to see if there are any new variables you should set or features you should be aware of, and then ftp the new version (or grab it with your WWW browser) and copy it over the old version. If you prefer, you can subscribe to the SpamBouncer Updates mailing list to get automatic notifications of updates via email. The mailing list is described in the next section.

That's all there is to it.

The SpamBouncer should be upgraded regularly -- weekly if you are using it with SPAMREPLY set to COMPLAIN and monthly otherwise. Spammers move around a lot. Prolific spammers tend to get disconnected quite a bit, even by spam-friendly providers, because they cause their providers so much trouble. This means that the complaint addresses in the Spam Bouncer's complaint lists must be updated constantly or complaints will go to the wrong place.

Providers get annoyed when they get complaints about a problem they've already fixed, or at least done everything they can to fix. Once they've kicked a spammer off their system, there is very little else they can do, and sending complaints to them just wastes their time and resources.

I do my part by updating the addresses, but that helps only if you do yours by keeping your copy of the SpamBouncer up to date.

So, if you can't upgrade frequently or don't want to bother updating all the time, please set SPAMREPLY and BLOCKREPLY to SILENT. That way you'll still get the benefits of the filter, but you won't risk causing trouble for an ISP that has already kicked its spammers off.

In addition, today's rogue ISP may be tomorrow's good guys. An example of that is erols.com, which a few years ago was the source of a huge amount of spam and which today is one of the leaders in the fight against it. (Erols also has one of the most entertaining "abuse@" people in the business -- Afterburner.) I regularly review the sites on the blocked list and retire those who have adopted and enforced solid no-spamming policies. That reduces the size of the filter and the resources it takes while keeping it as efficient as possible.

So, please keep up to date! :)

Return to Table of Contents

How to Troubleshoot and Report Trouble

If you are having trouble with the SpamBouncer, first please make sure you:

The SpamBouncer is set up to avoid replying to bounced messages and autoreplies to its own bounces, but some spammers set their adminstrative accounts to autoreply to spam complaints and misconfigure their autoresponders to remove the "X-Loop" header, which should NEVER be removed by any autoreply script. In general, it is not a good idea to autoreply to mail from administrative accounts at all, so the SpamBouncer is set up to filter it out first.

Please report spam which the SpamBouncer does not catch to <spamtrap@spambouncer.org> so that I can modify the SpamBouncer to catch it. Many spammers have gotten wise to me -- I'm on their remove lists even if they won't put you or others there. <wry grin> So I depend on my users to keep me up-to-date on what kind of spam is out there.

Report any problems to the author at ariel@spambouncer.org, and she'll get to work on fixing them ASAP.

Return to Table of Contents

The SpamBouncer Updates Mailing List

Updates to the SpamBouncer are announced via the SpamBouncer Updates mailing list, in addition to this Web page. The list is a low-volume announcements-only list that gets less than one email per week. I keep it this way so that people who hate getting spammed :) can subscribe without being overwhelmed with email. (If you want to discuss spam and how to fight it, I recommend the SPAM-L mailing list, described in the following section.)

The SpamBouncer Updates list runs on a Majordomo list server, a widely used mailing list management program. If you are unfamiliar with Majordomo, the instructions below should explain how to subscribe to and unsubscribe from the SpamBouncer Updates list. For more information on Majordomo and how to use it, refer to Majordomo Mailing List User Commands at the University of Rochester. For more information on Majordomo itself and how it works, refer to the Majordomo FAQ.

I must approve all subscriptions to the mailing list, so I suggest you send me email letting me know who you are and why you are subscribing before you subscribe to the list. :) (Where possible, I would prefer to keep spammers off of it.)

Subscribing

  1. Send email to updates-request@lists.spambouncer.org, with any subject line you like (the list server will ignore it), and the following text in the message body:

subscribe <your email address>
end
This will tell the Majordomo list server that you want to subscribe to the SpamBouncer Updates mailing list.
The list server will then send you two messages: a notice to the email address from which your subscription was sent and a confirmation message to the email address that you asked to have subscribed to the list. The notice explains that the subscription must be confirmed from the address that was subscribed to the list. The confirmation message asks you to copy a line of text from it, paste that line of text in a new email, and send the email back to the list server. The message will read like this:
Someone (possibly you) has requested that your email address be added to or deleted from the mailing list "spambouncer-updates@aziz.devnull.net".
If you really want this action to be taken, please send the following commands (exactly as shown) back to "Majordomo@aziz.devnull.net":
auth 3de6896e subscribe spambouncer-updates someone@example.com
If you do not want this action to be taken, simply ignore this message and the request will be disregarded.
The text you need to copy is the line beginning with auth. The jumble of letters and numbers after auth is called a token, and will be different for each person. Because it is different for each person, if you send back the exact token, the mailing list knows you really asked to subscribe. That prevents others from subscribing you to the mailing list without your permission.

  1. Copy the line of text beginning with auth and containing the token from the message the Majordomo list server sends to you into a new email, and send the new email back to updates-request@lists.spambouncer.org.

!
CAUTION!

  • Do NOT copy the line of text from the example shown above -- it is just an example and will not work for you. You must copy the line of text from the confirmation email sent to you.

If you followed these instructions correctly, the Majordomo list server will send you two more messages. The first is a short, machine-generated message showing that your subscribe command worked. The second is a message welcoming you to the SpamBouncer Upgrades list.

Unsubscribing

Send email to updates-request@lists.spambouncer.org, with any subject line you like (the list server will ignore it), and the following text in the message body:

unsubscribe <your email address>
end

This will tell the Majordomo list server that you want to unsubscribe from the SpamBouncer Updates mailing list. Majordomo will send you a message confirming that you have unsubscribed from the list. If you no longer have access to your old address, send me email and I will unsubscribe your old address manually.

Switching your Subscription to a Different Email Address

To switch your subscription to a new email address, you must unsubscribe your old address and subscribe the new one, following the instructions above.

Return to Table of Contents

Acknowledgments

First, I would like to thank Stephen van den Berg, the creator of procmail, for his wonderful tool. It is truly the friend of those who hate email spam and want it out of their lives. (It is also the friend of anyone who gets a lot of email.)

I would also like to thank the readers of the Procmail Mailing List for answering lots of often elementary questions, especially at the beginning, as I learned the program. I highly recommend the list for people who use the SpamBouncer. You can subscribe at procmail-request@Informatik.RWTH-Aachen.DE.

Finally, I'd like to thank one of the best sets of users anyone ever had -- you guys do a superb job keeping me up to date on what spammers are doing. I couldn't do it without you, seriously.

These filters are the result of several years of work and learning about Procmail. I hope the results will be as useful to others as they have been to me.

Return to Table of Contents


©1996-2001 by Catherine A. Hampton <ariel@spambouncer.org>. All rights reserved.