The Auto-Whitelist

Introduction

The auto-whitelist, or AWL, tracks scores for your regular correspondents in a small on-disk database. In 3.1, it is a plugin, loaded by default in the file v310.pre. In 3.0, it is enabled by default and turned off with the configuration setting use_auto_whitelist 0. In earlier versions, it is enabled using the -a flag to spamassassin or spamd.

The AWL is actually a very simple system. In short, the AWL is a score averaging system. It keeps track of the historical average of a sender, and pushes any subsequent mail towards that average.

So if someone that never sent you mail before sends you a mail that scores 20, and then sends you a second mail that would score 2.0 without the AWL, the AWL will push the score up to 11 on the second mail. This is auto blacklisting, based on their past history of spam.

If that same person sent you a mail that scored 0, and then later sent one that scored 7, the AWL would push the score down to 3.5. This is auto-whitelisting based on past history of nonspam.

A "sender" is identified using both the address they sent with, and their IP address, so spam claiming to be From you with forged headers will fail to get through.

But the "auto whitelist" isn't really a whitelist per-se. It does however have a "learning white/blacklist" type behavior as a result of it's averaging.

Sometimes it may appear that the AWL is assigning scores the wrong way; read AwlWrongWay for details.

How Does It Work?

The algorithm works using a database of entries. Each entry has a key formed by the From: address of the mail, and the IP address it originated at, and contains a TOTAL score and a COUNT number. The MEAN score is TOTAL/COUNT. The current algorithm works as follows:

1. Compute the SCORE of the message without AWL (auto-whitelist) 2. Compute AWL DELTA as (MEAN-SCORE)*auto_whitelist_factor 3. Increment TOTAL by SCORE 4. Increment COUNT by one 5. Set the final score of the message to SCORE+DELTA
   

auto_whitelist_factor can be tweaked in the configuration, and you may find this useful when starting off. The contents of the database can be examined using the program 'tools/check_whitelist'.

If you get the following error:

 $ /usr/share/doc/spamassassin-tools-3.0.0/tools/check_whitelist
Cannot open file /home/username/.spamassassin/auto-whitelist:

It seems that the check_whitelist program may be trying to open an older-format whitelist file. The check_whitelist program needs to be updated to use the new format (Berkley DB) whitelist and not the older format (pag/dir database).

Here is the solution:

 TODO: ADD THE SOLUTION 

How do I whitelist someone?

Not with the auto-whitelist! The auto-whitelist is an averaging system. Instead, you want to use the manual whitelist. See ManualWhitelist.