#   Copyright
#
#       Copyright (C) 2009-2010 Jari Aalto
#
#   License
#
#       This program is free software; you can redistribute it and/or modify
#       it under the terms of the GNU General Public License as published by
#       the Free Software Foundation; either version 2 of the License, or
#       (at your option) any later version.
#
#       This program is distributed in the hope that it will be useful,
#       but WITHOUT ANY WARRANTY; without even the implied warranty of
#       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
#       GNU General Public License for more details.
#
#       You should have received a copy of the GNU General Public License
#       along with this program. If not, see <http://www.gnu.org/licenses/>.
#
#   Description
#
#       To learn what TOP LEVEL sections to use in manual pages,
#       see POSIX/Susv standard and "Utility Description Defaults" at
#       http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11
#
#       This is manual page in Perl POD format. Read more at
#       http://perldoc.perl.org/perlpod.html or run command:
#
#           perldoc perlpod | less
#
#       To check the syntax:
#
#           podchecker *.pod
#
#       Create manual page with command:
#
#           pod2man PAGE.N.pod > PAGE.N

=pod

=head1 NAME

sa-heatu - Spamasassin Heuristic Email Address Tracker Utility

=head1 SYNOPSIS

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

=head1 DESCRIPTION

Check or clean a SpamAssassin auto-whitelist (AWL) database file.

The Auto-WhiteList (AWL) feature in Spamassassing tracks scores from
messages previously received and adjusts the message score, either by
boosting messages from senders who send ham or penalizing senders who
have sent spam previously. This not only treats some senders as if
they were whitelisted but also treats spammers as if they were
blacklisted. To enable AWL in spamassassin, read dcoumentation:

    perldoc Mail::SpamAssassin::Conf

This is an enhanced version of the original AWL tool. The AWL database
can be examined and pruned; single email entries can be removed. This
is useful when a spammer sends one or more ham messages before sending
spam.

Without special options, the program generates a summary of the
database (see FILES):

    $ 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 B<--verbose> it generates output:

     AVG   TOTSCORE COUNT  EMAIL IPBASE

I<AVG> is the average score; I<TOTSCORE> is the total score of all
mails seen so far; I<COUNT> is the number of messages seen from that
sender; I<EMAIL> is the sender's email address, and I<IPBASE> is the
B<AWL base IP address>.

I<AWL base IP address> is a way to identify the sender's IP address
they frequently send from, in an approximate way, but remaining hard
for spammers to spoof. The algorithm is as follows:

    - 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:

    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

=head1 OPTIONS

=over 4

=item B<-D, --DONTupdatetimestamps>

No timestamps processing is done. Alias for B<--noTimestamps>.

=item B<-e, --expireOlderThan NUMBER>

Expire entries older than NUMBER of days.

=item B<-f, --firstTimes>

Use this for the first run to avoid reading timestamps.

=item B<-h, --help>

Display short help.

=item B<-n, --noTimestamps>

No timestamps processing.

=item B<-p, --prune NUMBER>

Clean out infrequently-used AWL entries. The I<NUMBER> can be used to
select the threshold at which entries are kept or deleted. Value 1
means that entries seen once are deleted.

=item B<-q, --quiet>

Be quiet.

=item B<-r, --remove EMAIL>

Remove EMAIL from database.

=item B<-s, --showUpdates>

Output entries updated or added or removed, in addition to the
summary.

=item B<-v, --verbose>

Display more information. Note that this may display lot of
information from the database.

=back

=head1 EXAMPLES

To see valid senders:

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

To see top spammers:

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

To display single record:

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

To remove of I<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.

To 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: Note: 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

=head1 ENVIRONMENT

None.

=head1 FILES

=over 4

=item $HOME/.spamassassin

The default working directory of program where I<dbfile> etc. are
expected.

If I<dbfile> is not given the C<$HOME/.spamassassin/auto-whitelist> is
used. See also option B<auto_whitelist_path> in Spamassasin Perl module
I<Mail::SpamAssassin::Plugin::AWL> which typically points to
C</var/spool/spamassassin/auto-whitelist>.

=back

=head1 SEE ALSO

spamassassin(1)
Mail::SpamAssassin::Plugin::AWL(3p)

=head1 STANDARDS

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

=head1 AVAILABILITY

See STANDARDS for 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

=head1 AUTHORS

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 license, visit
<http://www.gnu.org/copyleft/gpl.html>.

=cut
