sa-heatu(1)

💖 sa-heatu — the Spamasassin Heuristic Email Address Tracker Utility 💖

okay bestie, welcome to sa-heatu(1), a little tool that is genuinely so underrated. it's a user command, it lives in section 1 of the manual, and it is here to help you peek at — and clean up — your SpamAssassin auto-whitelist database. let's get into it 🫶

---

✨ SYNOPSIS ✨

sa-heatu [options] [dbfile [timestamp-file]]

---

🌸 DESCRIPTION 🌸

So. What does this do? It checks or cleans a SpamAssassin auto-whitelist (AWL) database file. That's the whole vibe.

Now lemme tell you why AWL is iconic. The Auto-WhiteList feature in Spamassassing keeps track of scores from messages you received before, and uses that to adjust the score of the message in front of you. Translation: senders who send you ham get a lil boost, and senders who have sent you spam before get penalized. So it's not just treating good senders like they're whitelisted — it's also treating spammers like they're blacklisted. double duty. main character energy honestly. 💅

Wanna turn AWL on in spamassassin? go read the docs:

perldoc Mail::SpamAssassin::Conf

This program is an enhanced version of the original AWL tool, no cap. You can examine and prune the AWL database, and you can remove single email entries one at a time. Which is so useful when a spammer sends one or more ham messages first and then hits you with spam — like, rude, and now you can deal with it. 🎀

Without any special options, the program just generates a summary of the database (peep FILES for where that lives):

$ sa-heatu -D -n /var/spool/spamassassin/auto-whitelist

   0 entries removed.
   0 entries would be expired.
   0 timestamps would be added.
   0 timestamps would be updated.

 308 entries input.
 308 entries output = input - expired - removed.

With option --verbose it generates output like this:

 AVG   TOTSCORE COUNT  EMAIL IPBASE

and here's the legend, bestie, so you're not squinting at the columns:

• AVG is the average score.
• TOTSCORE is the total score of all mails seen so far.
• COUNT is the number of messages seen from that sender.
• EMAIL is the sender's email address.
• IPBASE is the AWL base IP address.

🦋 about that AWL base IP address 🦋

The AWL base IP address is a way to identify the sender's IP address they frequently send from — approximately, but in a way that stays hard for spammers to spoof. The algorithm is literally this:

- Take the last Received header that contains a public IP address;
  namely one which is not in private, unrouted IP space.

- Chop off the last two octets, assuming that the user may be in
  an ISP's dynamic address pool.

Negative values indicate senders of ham, which is kinda funny and also very true:

average    total count
   6.8       6.8   1   support@midphase.com                     72.26
  -8.1     -16.2   2   users-return-@spamassassin.apache.org    98.109
   1.4      15.9  11   partners@us.cyberoam.com                 38.105
  13.9      13.9   1   obdg@borgard.com                         89.185

---

✨ OPTIONS ✨

one bullet per flag, exactly as the manpage gods intended. slay. 👑

• -D, --DONTupdatetimestamps — No timestamps processing is done. This one is an alias for --noTimestamps.
• -e, --expireOlderThan NUMBER — Expire entries older than NUMBER of days.
• -f, --firstTimes — Use this for the first run, so it avoids reading timestamps.
• -h, --help — Display short help.
• -n, --noTimestamps — No timestamps processing.
• -p, --prune NUMBER — Clean out infrequently-used AWL entries. NUMBER is how you pick the threshold for what gets kept versus deleted. Value 1 means that entries seen once are deleted.
• -q, --quiet — Be quiet. 🤫
• -r, --remove EMAIL — Remove EMAIL from database.
• -s, --showUpdates — Output entries updated or added or removed, in addition to the summary.
• -v, --verbose — Display more information. Heads up though: this may display a lot of information from the database. like, a LOT. 😭

---

🌈 EXAMPLES 🌈

Wanna see valid senders? bet:

sa-heatu --verbose -D | sort -n | head -n 20

Wanna see top spammers? also bet:

sa-heatu --verbose -D | sort -n | tail -n 20

Display a single record:

sa-heatu --verbose -n | grep -i foo@example.com

Remove the foo@example.com entry:

$ sa-heatu -n --remove foo@example.com

Using $HOME/.spamassassin/auto-whitelist

average    total count found
34.5      34.5   1     foo@example.com 41.202

    1 deleted.
  259 keys with 1 entry.
  658 keys with 2 entries.
 1675 entries.

Shrink the database considerably by removing entries that only have one hit:

sa-heatu --prune

Average total count email address ip network address last time updated — and note that the date and time stamp is the time sa-heatu was run, not the time the email was received:

sa-heatu --verbose -D | sort -n | head -5

---

🌸 ENVIRONMENT 🌸

None. that's it. nothing to see here. empty. blank. a void. 🕳️✨

---

🎀 FILES 🎀

• $HOME/.spamassassin — The default working directory of the program, where dbfile etc. are expected.

If dbfile is not given, "$HOME/.spamassassin/auto-whitelist" is used. Also see option auto_whitelist_path in the Spamassasin Perl module Mail::SpamAssassin::Plugin::AWL, which typically points to "/var/spool/spamassassin/auto-whitelist".

---

💜 SEE ALSO 💜

spamassassin(1) and Mail::SpamAssassin::Plugin::AWL(3p) — go read them, they're the friends of this page.

---

⭐ STANDARDS ⭐

http://wiki.apache.org/spamassassin/AutoWhitelist

---

🔥 AVAILABILITY 🔥

See STANDARDS for the download link.

The original version this program is based on is at:

http://svn.apache.org/repos/asf/spamassassin/branches/3.2/tools/check_whitelist

---

👑 AUTHORS 👑

The program was written by Dennis G German <DGermansa@Real-world-Systems.com>.

This manual page was written by Jari Aalto <jari.aalto@cante.net>. Released under license GNU GPL version 2 or (at your option) any later version. For more information about the license, visit <http://www.gnu.org/copyleft/gpl.html>.

---

and that's the whole page, bestie 💖 this one's sa-heatu, dated 2022-10-13, part of the sa-heatu(1) family — go forth and prune responsibly, mwah 🫶✨🌸