
	          Installation and configuration notes for

	     Kai's SpamShield <tm> - Your last line of defense.

Current Version: 1.40
Date: 97/09/22

Initial release: Version: 1.10 Date: 97/07/14
(C)1997 - Kai '666' Schlichting - kai@9inch.org

SpamShield <tm> is a great program to defend your host from spammers
abusing your Un*x Sendmail-based SMTP servers to unload their illegal warez
upon the Internet, but primarily all over YOUR DISKSPACE, over YOUR NETWORK
LINKS, with YOUR CPUTIME : This unauthorized and illegal use of your
computing resources cannot be tolerated , and this is what this tool
helps to stop just when it starts up.

***** New Since V1.30 :
- added logging of hosts that are spamming, are listed in dontblock, 
  but not listed in blockignore: this would create a mail/reporting
  storm (stateless condition). We now log them as "NOT BLOCKED" in the
  blocked log. Thanks to John Eng for running into & reporting this.
- We now also log a time() stamp to the blocked log, second column, in
  preparation of automatic removal of routes in one of the next
  versions.
- More detailed reporting via mail (number of nrcpts).
- dontblock and blockignore file ship containing "127.0.0.1" by default now.
  You should definitely enter the IP addresses of local mail servers
  into one or another, too.

***** New since V1.10 :
- fixed 2 important bugs that impacted operations - please upgrade to V1.30,
  if you already run V1.10 ! Read the comments at the beginning of the
  program for details.
- people (especially Linux users) have suggested to use the -reject or
  -blackhole switches in the "route add" statement to avoid TCP SYN floods
  blocking the smtp port. While no spam programs are known to impatiently
  hammer any host with connection attempts, the -reject flag is now used
  by default to avoid this possibility. Please read your local man page for
  the "route" command and customize the system call in the "actspam"
  subroutine ! This is especially true for all non-BSDI systems, none of
  which are currently in the test cycle (I am working on supporting
  Redhat Linux 4.0 officially).
- this is a maintenance release that introduces no new functionality, just
  bug fixes. A new version is being developed, which will include:
  - auto-removal of blocked routes after spam has subsided
  - more counter-attack options, as these seem to be highly successful
  - better code, less external programs used (and less cpu time)
  - support for qmail logs
  - better support for other systems, auto-configuration
- none of the config options or variables have changed since V1.10 , just
  configure the same options (including possible changes to the "route"
  statement or other changes you incorporated) from your existing version
  into the new version, copy spamshield.pl into your /usr/local/spamcontrol/
  directory, make sure it's  permissions are set to at least mode 700, and
  you are done with the upgrade.

THANKS:
- Thanks to the Spammer community for all the beta testing by attacking
  abest.com's mailhost in obvious retaliation against me for writing this
  program: what hurts you makes you stronger, I guess. Being axed off
  a server in 30-90 seconds and having to re-connect must make for an
  interesting night, as opposed to a boring tight sleep at night, knowing
  noone is gonna impede the spam flow for the  entire night !
  I for one, have slept well for the last 2 months.
- Thanks go out to the white trash strippers from Maryland who kept
  spamming from PSI's dialups in Baltimore until I fixed one of these bugs.
  Thanks for keeping it up until I had it fixed! PSI, on the other side,
  shall lick my big dick,  as they still haven't terminated access to these
  dialup criminals, more than 11 days later. Needless to say there was much
  nuke'age observed....
- Thanks to all the people out there who actually use this program ! I am
  kinda shocked about the 1000++ downloads in the first two months of
  its release, really [and my mail box is swelling with enthusiastic fan
  mail - hey, where all the death threats and insults :) ? ].
*****

Requirements:

- Un*x based, written and tested on BSDI 3.0, 2.1, 2.01, but will work 
  with any basic unix-like system with slight reconfiguration.
- Works with Sendmail8 logfiles (sorry, no Qmail here, yet)
- needs Perl5 (Perl4 untested)
- Released under the GNU copyleft V.2 with the following limitations:
  You must report use of this program to me (kai@9inch.org, a simple note
  saying "I am XYZ, located in GHI and I use your program on platform ABC
  and it has killed 5 spammers in the first week of its use!" is enough).

  If you are a Fortune-1000 company , I'd appreciate a user fee of US$100 per
  machine towards further development of the program and any other cause I
  deem appropriate to stop spam on the Internet and retain email as a valuable
  tool for all, without users getting tired of email and shun "the system"
  just because of spam. Contact me for details, all taxes on the user fees
  are mine.
- Liability by the author: none. Locate and read the GNU copyleft document
  at <ftp://ftp.gnu.mit.edu/pub/gnu/COPYING-2.0>

Features:

+ Works safe and unattended from crontab, root access is not absolutely
  necessary, but limits functionality.
+ Configurable to a great degree
+ Comes in full Perl5 source for you to modify
+ released under GNU Copyleft V2 with rights for you to hack, modify and
  re-distribute versions as long as the original copyright notices stay
  were they are.
! designed for small/medium sized systems that handle a few 100's of domains
  on their systems, and cannot disable mail relaying for practical reasons,
  e.g.: too complicated maintenance of 'allowed' domains/MX's. If you
  don't relay, you might want to use SpamShield nevertheless to stop abuse
  by your OWN users
! greatly prevents not just spams, but also mail bombings, if those originate
  from a single, or a small number of sites.
+ will drive spammers nuts in their futile attempts to spam through your
  machine, as all they get might be a full minute of access to your smtp
  server before being shut down. Compare that to spammers sitting unnoticed
  on your server for hours, even days !
- Fast: can be run from crontab as often as once per minute, reducing
  the average lifetime of a spam to just under ONE MINUTE. Processes about
  1000 lines of logfiles per CPU second on a P133/BSDI system, using
  just 2 seconds of CPU per minute for an average configuration!

Options:

- can send email notification about spams to a list of mailboxes/pager-email
  gateways, special alerts about 'local' spams.
- can shut down spammers access to your entire mailserver in near-realtime
  as he is unloading his illegal spam ! ("Oops, I was just filling their
  disks, now I can't ping them. They must have crashed. Next...")
  This is accomplished by adding spammer's IP numbers to a blackhole host
  route on the local machine (usually requires program to run as root).
- can take automated retaliatory action against the spammer's machine before
  shutting down the route. Preconfigured is a call to an external program.
  Tested was: winnuke and ping-of-death, which are two highly successful
  methods to shut down Windows95 and NT3/4 machines, most of which are
  still susceptible. ("Darn, I was just filling their diskspace, and now my
  machine froze. FUCK. Must reboot....")

The way it works:

Kai's SpamShield is looking at the last <n> lines of the sendmail logfile,
and builds a list of how much mail was received from which machines (by
IP number) in the period covered by that log fragment.
If any particular machine sends more mail than a configured global threshold,
the assumption is that spam is received. The defaults for the log file
fragment and the number of mails per host that are allowed are for a rather
small system with only a few thousand mails per day. You might want to adjust
those limits (see further down). The general assumption (and I've seen
a number of spams to support those) is that spam abuse typically means
that up to several 100 emails PER MINUTE are received from a single source:
this is a tremendous 'signal to noise' ratio, given that even very
large systems, such as AOL's mail servers, don't deliver more than a few
100 mails to a small/medium-sized system PER DAY. For this reason, there are
configuration options to ignore 'spam-like' traffic from high-traffic
hosts that are deemed secure and non-relaying (AOL's servers don't relay,
for example) .

Install: 

Gunzip and Untar the tar file into the /usr/local/ directory, it will create\
a 'spamcontrol' directory with all it's files in it. It should be owned
and accessible by root only. 

If you don't know how to use gzip/tar based on the previous three lines,
you are NOT a knowledgable unix admin and should NOT perform this
installation, as the program has the potential (with improper configuration)
of shutting down network routes around your system to the point where it 
can't communicate on your network. And remember:
"Unix _IS_ user friendly... It's just selective about who its friends are."

Configuration:

Edit the spamshield.pl program :
- point to the proper location of your perl5 interpreter in the first line
- set $log to the location of your sendmail logfile: /var/log/maillog in
  most cases
- set $lastlines to the number of most recent log file lines you want the
  program to look at. Default is 1500, representing 4-8 hours of mail on
  a small system.
- set $spamthreshold to the number of emails that may be received from any
  single source IP within the number of lines configured above, before 
  considering the source to be a spamming host
- set $dontblock to a file that has a plain one-by-line list of IP hosts
  that are NEVER to be blocked. This includes for example your own IP
  number and that of the loopback interface (127.0.0.1). Warnings about
  spam from the hosts listed will still be mailed out !
- look at the $blockactive file to see what blocks are currently active.
  You should manually edit this file after a spam has been dealt with
  and you wish that the program forgets about having blocked this host.
- set $blockignore to a file that has a plain one-by-line list of IP hosts
  that Kai's SpamShield will NEVER complain about , never take any action
  about. This is usually all your OWN mailhosts, if they relay mail to
  each other in great numbers, and are usually hosts that run SpamShield
  themselves. This avoids that a spammer creates a storm of spam where
  your mail servers start ignoring each other. Also useful to define
  certain high-volume hosts that are never considered the source of
  spam (e.g.: AOL mail servers).
- set $securetmp to a directory (by default this is /usr/local/spamcontrol/)
  where temporary files can be created safely: e.g.: the directory is owned
  by the owner of this program, and noone else has permissions to write into
  it.
- set $blackhole to an unused IP number on your LOCAL ETHERNET (or you will
  get a bunch of errors of that destination being unreachable). This is
  the blackhole route that all traffic to undesired hosts is later redirected
  to. Take care not to use this IP number for ANYTHING.
  Leave undefined (comment out) to not do route changes/blocking.
- set $maintainer to contain a comma-separated list of email addresses that
  are to be notified of any spam activity. Note that @ must be escaped as
  \@ in perl.
  Leave undefined (comment out) to not send any mail to anyone.
- define the locations of the following programs on your system, defaults:

  $SENDMAIL="/usr/sbin/sendmail";
  $TAIL="/usr/bin/tail";
  $AWK="/usr/bin/awk";
  $GREP="/usr/bin/grep";
  $SORT="/usr/bin/sort";
  $CAT="/bin/cat";
  $DATE="/bin/date";
  $ROUTE="/sbin/route";
  $WINNUKE="/usr/local/spamcontrol/winnuke"; (optional, leave undefined to not
					      use retaliatory action)

  You should verify the location of each of these programs with the `which`
  (or `type`, in bash) command.

  This explicit definition of programs is desired in a program run by root,
  regardless of the secure path (as required by perl's taint mode) defined
  in the program.

Testing:

Run the program spamshield.pl as root (or as the desired user) by hand,
note any and all errors encountered and correct them (usually mis-defined
variables you set).

You should now have the following files in the /usr/local/spamcontrol/
directory:

blocked - current list of blocked sites, serves as log of past activity,
	  watch this whenever you get warning mail about spams in progress.
blockignore - list of IPs that are always ignored and never acted upon, this
	      usually consists at least of the sites in the 'dontblock' file
dontblock - list of IPs that are never blocked, but will cause spam alarms,
spamshield.pl - the program
ss-ipstats - easy to understand list of how many mails have been received
	     from which IP host (after program run)
ss-mailstats - total list of every maillog line condensed into three
	       space-separated parameters: IP number, number of recipients
	       in this batch, sender address used on From_ line. This makes
	       for easy grepping and sorting for other purposes (who sends
	       me how much mail ?)

If you get errors, you might want to play with the $DEBUG value in
the program: increasing it up to 9 reveals more and more detail about the
processing happening during program run.

Ultimately you want to insert a line like the following into root's crontab:

0,3,6,9,12,15,18,21,24,27,30,33,36,39,42,45,48,51,54,57 * * * * /usr/local/spamcontrol/spamshield.pl

This will run the program every 3 minutes, but there is really no reason
not to let it run every minute on a powerful server, and when looking at
no more than 3000 lines in the logfile. YMMV.

Running it every minute would look like this:
* * * * * /usr/local/spamcontrol/spamshield.pl

As you are weighing CPU time used vs. usefulness, you might want to
consider different run intervals during day/night: most spams see to
happen in the early morning hours, when noone is around to notice evil
things happening, hence running SpamShield every minute after regular
hours is a good thing <tm>.

And the number one true reason why I wrote this program and wish that it's
widely used: Spammers must die. I hope they put Kevin J Lippsitz [sic] on
the electric chair one day, as there is some criminals around who are posing
such a profound risk to the global network structure that life without
parole cannot be an option. Did I just start to rant about the US federal
government...

The end.
