• NAME
• SYNOPSIS
• DESCRIPTION
• DAEMONS
• SCRIPTS
• WEB APPLICATIONS
• OTHER MODULES IN THIS PACKAGE
• BUGS
• COPYRIGHT
• AUTHOR

NAME

Mail::SpamCannibal - A tool to stop SPAM

SYNOPSIS

none, this is a documentation shell

DESCRIPTION

Mail::SpamCannibal provides a collection of tools and utilities to help stop spam. This process comprises several steps and uses a combination of daemons, cron scripts and scripts activated by incoming mail.

DAEMONS

• dbtarpit
  A tarpit daemon that interfaces directly to Linux IPtables to monitor port 25 access and allow or deny (and tarpit) connections based on the information in the spamcannibal database. Additionally, dbtarpit logs the IP address of every connection host to its 'archive' database for later processing by sc_BLcheck.pl.

  See: IPTables::IPv4::DBTables

• dnsbls
  A blacklist DNS daemon that uses the spamcannibal databases as its information source.

  See: Mail::SpamCannibal::DNSBLserver

• bdbaccess
  A local and remote database access provider that services non-privileged tasks with information from the spamcannibal databases. This daemon can provide local service via a unix domain socket, or remote service. For remote service, the bdbaccess can be run as a standalone daemon or from inetd with tcp wrapper to restrict access.

  See: Mail::SpamCannibal::BDBaccess

SCRIPTS

• sc_BLcheck.pl
  This script is run periodically by CRON and checks the list of host IP addresses found in the spamcannibal 'archive' database. sc_BLcheck's config file contains a list of DNSBL servers against which these addresses are checked and if matched, the address is placed in the dbtarpit 'tarpit' database to deny connection. A record of the reason for denial based on the DNSBLS response is placed in the spamcannibal 'blcontrib' (blacklist contrib) database for use by the web interface and sc_BLpreen.pl.

  Also see sc_BlackList.conf.sample in the spamcannibal config directory.

• sc_BLpreen.pl
  This script is run periodically by CRON and checks the IP addresses found in the spamcannibal 'blcontrib' database. Each address is verified against the origination DNSBL and purged from the database after a configurable timeout if the DNSBL goes down or if the DNSBL no longer blacklists the address. Because this is a HIGH load task, checks are only performed on IP addresses that are found in the 'tarpit' database that have recently attempted contact. Recent is defined as sometime within the last 5 intervals (or one day, whichever is greater) for the sc_BLpreen.pl CRON task. 'tarpit' entries that are older than this are not checked for removal. NOTE that this is harmless. Any contact by a sending mail server will update the tarpit time tag resulting in a check being performed at the next CRON interval and the entry being removed if the IP address is no longer in the external DNSBL.

  Also see sc_BlackList.conf.sample in the spamcannibal config directory.

• sc_mailcheck.pl
  This script is a robot mail recipient set up in the spamcannibal user's .forward file. Secure mail with a message body containing the headers and spam content of a 'spam' message sent from your desktop is parsed to extract the origination MTA. The IP address of the MTA is added to the spamcannibal 'tarpit' database and the 'spam' content is added to the spamcannibal 'evidence' database for use by the web interface.

  Also see sc_mailfilter.conf.sample in the spamcannibal config directory

• sc_admin.pl
  This script provides the site administrator with direct access to the fields in the SpamCannibal databases for manual updates, deletes or other tasks that can not be performed with the administrative web tools or one of the other automatic scripts. In particular, sc_admin.pl is needed to modify or delete records in the 127.0.0.0/8 range. These addresses are used by SpamCannibal for bookeeping and dnsbl test addresses and are more or less ignored by all the scripts and tools except sc_admin.pl

• sc_initdb.pl
  This script initializes the SpamCannibal Berkeley DB environment and databases. It also sets the permissions on the SpamCannibal environment directory and database files.

  Run with the '-R' switch to recover the Berkeley DB environment. All other threads must be stopped prior to using this switch. See the document 'pods/recover.pod' or '/docs/recover.html' for more information.

• sc_recoverdb.pl
  This script verifies and/or recovers and writes a new DB file. You must move/copy the new DB file over the old one. An existing database file can be verified for integrity and/or a new one can be created from the old one to recover good records from a corrupted file. See the document 'pods/recover.pod' or '/docs/recover.html' for more information.

• sc_remote.pl
  This script provides remote access via sc_remotewrap for the web admin program sc_session.pl to a SpamCannibal installation on a remote host.

• sc_session.pl
  This script provides the web admin routines with privileged access via sc_sesswrap to the SpamCannibal database in a secured sandbox.

• sc_cleanup.pl
  This script examines the databases and removes records that do not have the appropriate corresponding matching records in sister database files.

  It should be run periodically to keep things tidy.

• sc_country_origin.pl
  This script prints a sorted list (by count) of countries of origin (by country code) and the number of IP addresses that appear in the 'tarpit' database.

Each of the above scripts has 'help'

  scriptname.pl -h

WEB APPLICATIONS

• cannibal.cgi
  This cgi script may be use directly as Perl cgi or in its alter ego, 'cannibal.plx' as a mod-perl enabled script to provide public access to the spamcannibal database. This allows the public to see if their IP address is in the spamcannibal database, do a WHOIS lookup on a particular IP address or contact the site administrator.

• admin.cgi
  (this is really ln -s cannibal.cgi admin.cgi)

  'admin.cgi' provides administrative functions to view, add and remove information to/from the spamcannibal database. It is highly recommend that this be run over a secure link with https as the password and token system is insecure otherwise. You can do it, but you've been warned.

  The administrator may add or remove other administrators and each administrator my manage his/her password. This feature can be disabled. The password systems uses passwords compatible with 'crypt' and htpasswd.

  Spamcannibal installs with a single adminstrative user 'admin' with a blank password.

• spam_report.cgi
  Interface to the optional LaBrea::Tarpit statistics reporting module. this web script provides a view of the current state and recent operations of the SpamCannibal tarpit daemon and is a recommended part of any installation.

OTHER MODULES IN THIS PACKAGE

• Mail::SpamCannibal::SiteConfig
  When called, returns a hash containing the site configuration information

• Mail::SpamCannibal::BDBclient
  Interface utilities for bdbaccess daemon

• Mail::SpamCannibal::GoodPrivacy
  Interface to PGP or openPGP (use by sc_mailfilter.pl)

• Mail::SpamCannibal::LaBreaDaemon
  An interface module to the routines and functions in LaBrea::Tarpit

• Mail::SpamCannibal::ParseMessage
  Utilities to extract headers, MTA's, and messages from text.

• Mail::SpamCannibal::Password
  Utilities to manage password encryption and decryption

• Mail::SpamCannibal::PidUtil
  Utility module to check if a job is running and to create and manage pid files.

• Mail::SpamCannibal::SMTPsend
  A module built on Perl Socket that can send mail. It does its own MX resolution and does not rely on the host MTA.

• Mail::SpamCannibal::ScriptSupport
  A collection of utilities use by the spamcannibal scripts and web cgi routines.

• Mail::SpamCannibal::Session
  Web service administrative session manager routines to provide security for administrative access to the spamcannibal database.

• Mail::SpamCannibal::WebService
  Utilities to support web services for cgi and mod-perl

• Mail::SpamCannibal::WhoisIP
  Utility module to lookup an IP address owner anywhere in the world

BUGS

  During perl Makefile.PL I have the following errors:

  WARNING: HTMLSCRIPTPODS is not a known parameter.
  WARNING: INST_HTMLLIBDIR is not a known parameter.
  WARNING: EXTRA_META is not a known parameter.
  WARNING: INSTALLHTMLSITELIBDIR is not a known parameter.
  WARNING: HTMLLIBPODS is not a known parameter.

  These warnings are normal for version ExtUtils-MakeMaker-6.44 
  (Feb 28, 2008) and later. Usually these can be safely ignored 
  since the missing "internals" only affect the expansion of 
  documents into SpamCannibal's web tree and the SpamCannibal 
  installer also has a built-in workaround to compensate for the 
  missing internals of the newer ExtUtils-MakeMaker.

COPYRIGHT

Copyright 2003 - 2009, Michael Robinton <michael@bizsystems.com>

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, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

AUTHOR

Michael Robinton <michael@bizsystems.com>