NAME
SpamCannibal - scripts
sc_BLcheck.pl
This script checks each IP address found in the archive database against the list of DNSBL black list servers in its configuration file. IP addresses that have a matching DNSBL response are added to the tarpit database and a corresponding record is made in the blcontrib database to indicate the reason for addition and the black list server responsible. The entry may come in part from the TXT record returned by the DNSBL and/or from the default values in the config file.
Syntax: ./sc_BLcheck.pl path/to/config.file
or
./sc_BLcheck.pl -d path/to/config.file
./sc_BLcheck.pl -v path/to/config.file
The -d switch allows you to see what the
script will do without any db updates
taking place. The -v switch will print
the scripts actions to the screen.
-v -v does it more verbosely.
The -d switch implies a single -v.sc_BLpreen.pl
This script checks each IP address found in the blcontrib file for continued blacklisting by the original DNSBL server. If the DNSBL no longer blacklists an address or if the DNSBL is unreachable for a predetermined, configurable timeout set in the config file for each DNSBL, then the IP address is removed from SpamCannibal's database.
Syntax: ./sc_BLpreen.pl path/to/config.file
or
./sc_BLpreen.pl -d path/to/config.file
./sc_BLpreen.pl -v path/to/config.file
The -d switch allows you to see what the
script will do without any db updates
taking place. The -v switch will print
the scripts actions to the screen.
-v -v does it more verbosely.
The -d switch implies a single -v.sc_admin.pl
This script provides low level access to the SpamCannibal databases for fixing things or modifying things that can't be done using the admin interfaces. Belt and suspenders!
Syntax: sc_admin.pl db_name (action) [dot.quad.ip.addr] [stuff]
(or) [stuff]
[.]
sc_admin.pl db_name get dot.quad.ip.addr
sc_admin.pl db_name insert dot.quad.ip.addr stuff...
sc_admin.pl db_name delete dot.quad.ip.addr
sc_admin.pl db_name zap key (unconstrained delete)
sc_admin.pl db_name view
sc_admin.pl db_name clear
and
where db_name is one of
tarpit, archive, blcontrib, or evidence
for "tarpit" and "archive" there are no arguments
for "insert" except dot.quad.ip.addr,
for "blcontrib" the arguments are (in order):
addr => resp, err, remrsp, time, zone
dot.quad.ip.addr
127.0.0.3 # response code from our DNSBL
"error string... from remote DNSBL or our default"
127.0.0.x # remote response accepted from remote DNSBL
1059422395 # time record expires (since epoch) or "0"
remote.dnsbl.zone
for "evidence" the arguments are
dot.quad.ip.addr followed by STDIN of
mail headers +
message terminated on the last line by a
.sc_initdb.pl
This script initializes the SpamCannibal environment and database files; and sets the permissions on the directories and files.
There's no usage syntax, it is run once after installation. And needs to be run again after a database recovery. Running it repeatedly won't hurt anything.
sc_mailfilter.pl
This script parses a received message that contains a set of spam headers and message body.
i.e.
-----------------
| real headers |
-----------------
blank line
-----------------
| spam headers |
-----------------
blank line
-----------------
| spam body |
-----------------The spam headers, blank line, body can optionally (recommend) be encrypted with PGP armor to prevent unauthorized access to the spam client input.
Syntax: ./sc_mailfilter.pl path/to/config.file
or
./sc_mailfilter.pl -d path/to config.file
./sc_mailfilter.pl -v path/to/config.file
The -v switch sends debug error messages to
the REPORT target email address (if present)
The -d switch returns the information that would
be added to the tarpit and evidence databases.
Nothing is added to the database files.Typically this is invoked by placing a .forward file in the spamcannibal user directory containing the following:
"|/usr/local/spamcannibal/scripts/sc_mailfilter.pl \
-v /usr/local/spamcannibal/config/sc_mailfilter.conf"sc_abuse.pl
This script parses a spam message in the format delivered to the spam moderator by sc_mailfilter.pl to determine the target domain to which to which it will then send an abuse report.
Syntax: ./sc_abuse.pl path/to/config.file
or
./sc_abuse.pl -d path/to/config.file
./sc_abuse.pl -v path/to/config.file
The -d switch causes the normal output to
be sent to the REPORT target email address
rather than to the target abuse address
The -v switch sends debug error messages to
the REPORT target email address (if present)
This script sends it's "message" to abuse@domain.name of
the first remote MTA found in the headers of the "message".
The script decodes the last character in the To: field of
it's own received headers to determine the length of the
domain to append to "abuse@" to determine the target address.
i.e. for some.spam.domain.com
To: localabuse 2 domain fields 'abuse@domain.com'
To: localabuse1 2 domain fields 'abuse@domain.com'
To: localabuse2 2 domain fields 'abuse@domain.com'
To: localabuse3 3 domain fields 'abuse@spam.domain.com'
To: localabuse4 4 domain fields 'abuse@some.spam.domain.com'Typically this is invoked by placing a .forward file in the sc_abuse user directory containing the following:
"|/usr/local/spamcannibal/scripts/sc_mailfilter.pl \
-v /usr/local/spamcannibal/config/sc_mailfilter.conf"The sc_abuse user should be created in GROUP "spam"
sc_cleanup.pl
This script cleans spurious records from the database.
For example: A spam message arrives and the sc_BLcheck.pl script is fired off by cron. sc_BLcheck.pl finds the address on a remote DNSBL and adds a record to the tarpit. A few minutes later you read your mail, find the spam and send it off to sc_mailfilter. These two action result in a record in the tarpit as well as both the contrib and evidence databases. Only one tracking record is necessary in contrib or evidence so there is an extra record. Similarly if you "play" around with the sc_admin.pl tools and leave extra records here and there, sc_cleanup.pl will remove them.
Syntax: ./sc_cleanup.pl -q
or
./sc_cleanup.pl -d
./sc_cleanup.pl -v
The -q switch is for normal, quiet operation.
The -d switch allows you to see what the
script will do without any db updates
taking place. The -v switch will print
the scripts actions to the screen.
The -d switch implies a -v.sc_recoverdb.pl
This scripts verifies and/or recovers and writes a new DB file. You must move/copy the new DB file over the old one.
Syntax: ./sc_recoverdb.pl [-v] [-p path] [-t] db_file
-d debug, print trace info
-p optional non-standard path
(default /var/run/dbtarpit)
-t db_file has text mode data
(needed only for non-standard
file names not in siteconfig)
-v optional verify only switch
(do not write db_file.new)
All DB jobs must be stopped to run recovery
on a DB file. NOT applicable to 'verify mode'.
Verify example
./sc_recoverdb.pl -v evidence
verifying 157229 records...
bad record 5907 Successful return: 0
bad record 5908 Successful return: 0
verified 157229 records
New DB file example
./sc_recoverdb.pl evidence
checking 157229 records...
bad record 5907 Successful return: 0
bad record 5908 Successful return: 0
evidence 157229 -> evidence.new 157227sc_remote.pl
This script is the alias for a suid wrapper (user spam) and provides secure access to a remote host spamcannibal databases for the web admin interface via ssh or other suitable transport for administrative activities. The command line interface is the same as sc_session.pl.
sc_session.pl
This script is the alias for a suid wrapper (user spam) and provides secure access to the local host spamcannibal databases for the web admin interface.
Syntax: sc_session.pl command [arg1] [arg2] ...
sc_session.pl admin on | off (command line only)
sc_session.pl newsess user password
sc_session.pl updpass session_id expire user newpass oldpass
sc_session.pl chksess session_id expire (relative)
sc_session.pl rmvsess session_id
sc_session.pl insBL session_id expire dot.quad.ip.addr stuff...
sc_session.pl insEVD session_id expire dot.quad.ip.addr stuff...
sc_session.pl delete session_id expire dot.quad.ip.addr
admin returns "OK status"
allow admin addition/deletion of users
newsess returns "OK session_id"
updpass returns OK or (error text)
blank passwords deletes user (not self)
chksess returns OK or (error text)
rmvsess returns OK or (error text)
insBL returns OK or (error text)
insert blacklist contrib
the arguments are (in order):
addr => resp, err, remrsp, time, zone
dot.quad.ip.addr =>
127.0.0.3 # response code from our DNSBL
"error string... from remote DNSBL or our default"
127.0.0.x # remote response accepted from remote DNSBL
1059422395 # time record expires (since epoch) or "0"
remote.dnsbl.zone
insEVD returns OK or (error text)
insert evidence, the arguments are:
dot.quad.ip.addr followed by STDIN of
mail headers +
message terminated on the last line by a single
.
delete returns OK or (error text)
deletes dot.quad.ip.addr in all databasessc_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.
US 12345
CN 7543
KR 1234
... and so on...