NAME
SYNOPSIS
FUNCTIONS
METHODS
DESCRIPTION
DEPENDENCIES
EXPORT
EXPORT_OK
COPYRIGHT
AUTHOR
SEE ALSO

NAME

Mail::SpamCannibal::ScriptSupport - A collection of script helpers

SYNOPSIS

  use Mail::SpamCannibal::ScriptSupport qw(
        DO
        doINCLUDE
        SerialEntry
        TarpitEntry
        DNSBL_Entry
        id
        question
        revIP
        query
        dns_udpsend
        dns_udpresp
        dns_ans
        dns_ns
        dns_ptr
        rlook_send
        rlook_rcv
        zone_def
        valid127
        validIP
        zap_one
        zap_pair
        job_died
        dbjob_chk
        dbjob_kill
        dbjob_recover
        unpack_contrib
        lookupIP
        list2NetAddr
        matchNetAddr
        BLcheck
        checkclct
        dumpIPs
        BLpreen
        mailcheck
        abuse_host
        is_GENERIC
        block4zonedump
  );

FUNCTIONS

  $rv = DO($file,$nowarnings);
  $rv = doINCLUDE($file,$nowarnings);
  $packedIPaddr = SerialEntry()
  $packedIPaddr = TarpitEntry();
  $packedIPaddr = DNSBL_Entry();
  $unique = id($seed);
  $querybuf = question($name,$type);
  $rev = revIP($ip);
  $response = query(\$buffer,$timeout);
  $socket = dns_udpsend(\$buffer,$timeout);
  $response = dns_udpresp($socket,$timeout);
  ($aptr,$tptr,$auth_zone) = dns_ans(\$buffer);
  $nsptr = dns_ns(\$buffer);
  $hostname = dns_ptr(\$buffer);
  @hosts = dns_ptr(\$buffer);
  $socket = rlook_send($IP,$timeout);
  $hostname = rlook_rcv($socket,$timeout);
  ($expire,$error,$dnresp,$timeout)=zone_def($zone,\%dnsbl);
  $dotquad = valid127($dotquad);
  $dotquad = validIP($dotquad);
  $rv = job_died(\%jobstatus,$directory);
  $rv = dbjob_chk(\%default_config);
  dbjob_kill(\%default_config,$graceperiod);
  dbjob_recover(\%default_config);
  ($respip,$err,$blrsp,$exp,$zon)=unpack_contrib($record);
  ($which,$text)=lookupIP(\%config,$dotquadIP,$sockpath,$is_network);
  $rv=list2NetAddr(\@inlist,\@NAobject);
  $rv = matchNetAddr($ip,\@NAobject);
  $rv = BLcheck(\%DNSBL,\%default);
  $hashref = checkclct($DNSBL);
  $rv = dumpIPs($DNSBL, $allipsHASHptr);
  $rv = BLpreen(\%DNSBL,\%default);
  @err=mailcheck($fh,\%MAILFILTER,\%DNSBL,\%default,\@NAignor,\$spamsource)
  $rv=zap_one($tool,$netaddr,$db,$verbose,$comment);
  zap_pair($tool,$netaddr,$pri,$sec,$debug,$verbose,$comment);
  $rv = is_GENERIC($conf->{GENERIC},@hostnames);
  block4zonedump($environment);

METHODS

  $object = new Mail::Spamcannibal::ScriptSupport;
  $rv = $object->dns2rblz($line);
  $firstline = $object->rbldns_combined($type);
  $textline = $object->rbldns_compress($textline);
  $lastline = $object->rbldnst_done();
  $lastline = $object->rbldns_done();
  $last_combined = rbldns_address();

DESCRIPTION

Mail::SpamCannibal::ScriptSupport provides a collection of support utilities for sc_BLcheck, sc_BLpreen, sc_mailfilter, sc_admin, sc_session, and cannibal.cgi.

$rv = DO($file,$nowarnings);
Imported from File::SafeDO for legacy applications.
This is a fancy 'do file'. It first checks that the file exists and is readable, then does a 'do file' to pull the variables and subroutines into the current name space.
```
  input:        file/path/name
  returns:      last value in file
            or  undef on error
            prints warning
```
$rv = doINCLUDE($file,$nowarnings);
Imported from File::SafeDO for legacy applications.
Similar to above but supports INCLUDE keys.

See: the File::SafeDO manpage
$packedIPaddr = SerialEntry();
Returns the packed internet address equivalent to inet_aton('127.0.0.0'). Make sure and use the parens at the end of the function.
$packedIPaddr = TarpitEntry();
Returns the packed internet address equivalent to inet_aton('127.0.0.2'). Make sure and use the parens at the end of the function.
$packedIPaddr = DNSBL_Entry();
Returns the packed internet address equivalent to inet_aton('127.0.0.3'). Make sure and use the parens at the end of the function.
($expire,$error,$dnresp,$timeout)=zone_def($zone,\%dnsbl);
Parse the zone information and return either the default values or the overides from the config file.
```
  Defaults:
        $expire = '7d'  # in seconds
        $error  = 'Blacklisted by: $zone'
        $dnresp = inet_aton('127.0.0.3')
        $timeout  undef
```
NOTE: if the respone code found in the config file is not in the 127./8 block or is less than 127.0.0.3, $dnresp will be set to the default value.
$dotquad = valid127($dotquad);
This function checks an IP address in dot quad notation to see if it is in the range 127.0.0.3 to 127.255.255.255. It returns 127.0.0.3 if the IP address is outside that range.
```
  input:        dot quad ip address
  returns:      input or 127.0.0.3
```
$dotquad = validIP($dotquad);
This function inspects an IP address and returns it if is valid.
```
  input:        dot quad address
  returns:      dot quad address or undef
```
$rv=zap_one($tool,$netaddr,$db,$verbose,$comment);
Helper function to remove a record from one database. It conditionally removes the record from $db. No removal is performed if $debug is true, it is just ``commented''. Action or proposed action is commented if $debug or $verbose is true. $comment is appended to the standard ``remove'' message if $comment exists.
```
  input:        $tool,    # ref to Tools
                $netaddr, # IP to remove
                $db,      # database name
                $debug,   # mode
                $verbose, # report intensity
                $comment,
```
```
  output:       1 on removal, 0 if no record removed
```
zap_pair($tool,$netaddr,$pri,$sec,$debug,$verbose,$comment);
Helper function for BLpreen. It conditionally removes the records for $netaddr from databases $pri and $sec. No removal is performed if $debug is true, it is just ``commented''. Action or proposed action is commented if $debug or $verbose is true. $comment is appended to the standard ``remove'' message if $comment exists.
```
  input:        $tool,    # ref to Tools
                $netaddr, # IP to remove
                $pri,     # database name
                $sec,     # database name
                $debug,   # mode
                $verbose, # report intensity
                $comment,
```
```
  output:       false on success, or
                an error message
```
& $rv = job_died(\%jobstatus,$directory);
This function checks for pid files in the $directory. The absolute pid file path is inserted into %jobstatus with a value of it's pid. Tasks that are not running return a pid value of zero (0).
```
  input:        pointer to job status hash,
                pid file directory
  returns:      true if a task is not running
                else false
```
$rv = dbjob_chk(\%default_config);
This function checks if data base tasks have exited abnormally. If an abnormal exit is detected, the file blockedBYwatcher containing the watcher pid is created in the environment directory and the function return false, otherwise it returns true.
```
  input:        pointer to db configuration,
  returns:      true if all known tasks are running
                or exited normally, else returns false
```
dbjob_kill(\%default_config,$graceperiod);
This function kills all db tasks that have registered PID files in the environment directory. These jobs are shutdown, first with a SIG TERM and if they do not respond withing the grace period, a SIG KILL.
```
  input:        pointer to db configuration,
                task shutdown grace period
  returns:      nothing
```
dbjob_recover(\%default_config);
This function destroys and reinstantiates the database environment. The file blockedBYwatcher is removed from the environment directory if it is present.
All DB tasks should be terminated prior to calling this function.

DO NOT call this job for a DB environment that has not been initialized.
```
 usage: if(dbjob_chk(\%default_config) {
          dbjob_kill(\%default_config,$graceperiod);
          dbjob_recover(\%default_config);
        ... restart db jobs
        }
```
```
  input:        pointer to db configuration,
  returns:      nothing
```
($respip,$err,$blrsp,$exp,$zon)=unpack_contrib($record);
Unpack a 'blcontrib' record.
```
  input:        record from 'blcontrib' database
  output:       netaddr - our response code,
                our error message,
                netaddr - remote response code,
                expire
                dnsbl zone
```
This undoes pack(``a4 x A* x a4 x N x A*'',@_);
($which,$text)=lookupIP(\%config,$dotquadIP,$sockpath,$is_network);
This function checks the SpamCannibal databases for the presence of an IP address and returns a text string describing why the IP address is in the SpamCannibal data base or a descriptive not found message.
```
  input: (localhost)
                \%database config,
                dotquad IP address,
                /path/to/fifo,
                0,
         (or remote host)
                \%database config,
                dotquad IP address,
                hostname:port,
                timeout seconds
```
```
  returns:      which database,
                text string
```
```
        which = 0 for evidence
                1 for blcontrib
```
NOTE: the database config hash is the same as returned by Mail::SpamCannibal::SiteConfig

Text error return messages: message, meaning

invalid IP address, says it all not found in system database, not in tarpit db remote data record missing, found in contrib no text no remote data record found, says it all
$rv=list2NetAddr(\@inlist,\@NAobject);
Imported from Net::DNSBL::Utilities for legacy applications
Build of NetAddr object structure from a list of IPv4 addresses or address ranges. This object is passed to matchNetAddr to check if a given IP address is contained in the list.
```
  input:        array reference pointer
                to a list of addresses
```
```
  i.e.          11.22.33.44
                11.22.33.0/24
                11.22.33.0/255.255.255.0
                11.22.33.20-11.22.33.46
                11.22.33.20 - 11.22.33.46
```
```
  output:       Number of objects created
                or undef on error
```
The NAobject array is filled with NetAddr::IP::Lite object references.
$rv = matchNetAddr($ip,\@NAobject);
Imported from Net::DNSBL::Utilities for legacy applications
Check if an IP address appears in a list of NetAddr objects.
```
  input:        dot quad IP address,
                reference to NetAddr objects
  output:       true if match else false
```
$rv = BLcheck(\%DNSBL,\%default);
This function checks the each IP address found in the 'archive' database {SPMCNBL_DB_ARCHIVE} against the list of DNSBLs found in the ``sc_addspam.conf'' configuration file. IP addresses which match the acceptance criteria are added to the 'tarpit' database {SPMCNBL_DB_TARPIT} and a corresponding entry is made in the 'blcontrib' database {SPMCNBL_DB_CONTRIB} giving the reason for the addition.
```
  input:        config file hash ref,
                db config hash ref
  output:       false on success, or
                an error message
```
See: config/sc_BlackList.conf.sample for a detailed description of each element in the configuration file. See: scripts/sc_BLcheck.pl for usage and configuration information for the db config hash reference.

This routine will return if it catches a SIGTERM. The longest it will wait is the timeout for a DNS query.
$hashref = checkclct($DNSBL);
Return undef or a hashref for collecting IP's.
```
  input:        config file hash ref
  output:       IP collection hash ref
```
Used by BLcheck
$rv = dumpIPs($DNSBL, $allipsHASHptr);
Dump the %allips hash in a Data::Dumper compatible format to the file pointed to by 'ALLIPS' in config.
```
  input:        config pointer,
                pointer to ALLIPS hash
  returns:      false on success or error message
```
Used by BLcheck
$rv = BLpreen(\%DNSBL,\%default);
This function validates each IP address found in the 'blcontrib' database {SPMCNBL_DB_CONTRIB} for presence of its original dnsbl zone entry in the configuration file and that the remote dnsbl still has an acceptable 'A' record. IP addresses which fail either of these criteria or for which the remote dnsbl does not respond for the 'expire' interval (see sc_addspam.conf) are removed from the 'tarpit' database {SPMCNBL_DB_TARPIT} as well as the 'blcontrib' database {SPMCNBL_DB_CONTRIB}. 'contrib' items found in the 'evidence' are unconditionally discarded instead of being checked.
```
  input:        config file hash ref,
                db config hash ref
  output:       false on success, or
                an error message
```
See: config/sc_BlackList.conf.sample for a detailed description of each element in the configuration file. See: scripts/sc_BLpreen.pl for usage and configuration information for the db config hash reference.

This routine will return if it catches a SIGTERM. The longest it will wait is the timeout interval for a DNS query.
@err=mailcheck($fh,\%MAILFILTER,\%DNSBL,\%default,\@NAignor,\$spamrcd)
This function extracts the sending mail server address, headers, and message content from an ``email message'' that may [optionally] be PGP encoded. If an IP address is successfully recovered, it is added to the 'tarpit' database {SPMCNBL_DB_TARPIT} and the headers and message are added to the 'evidence' database {SPMCNBL_DB_EVIDENCE}. See: config/sc_mailfilter.conf.sample for configuration and details on optional settings.
```
  input:        file handle,
                config hash ptr,
                dnsbl config hash ptr,
                default config hash ptr,
                net object ptr,
                [optional] spam info array pointer 
  output:       empty array on success,
                (verbosity, err msg) on failure
        where verbosity is false on success,
        1,2,3, etc.... on failure
```
```
  my %default = (
        dbhome  => $environment,
        dbfile  => [$tarpit],
        txtfile => [$evidence],
        DEBUG   => $DEBUG,
        LIMIT   => $CHAR_SAVE_LIMIT, # characters
        PGPLIM  => $CHAR_READ_LIMIT,
  );
```
```
  [optional] spam info array pointer
  $spamip = ['spam source name or ip','spam headers + message']
  This array will be filled by mail check if it is present
```
@err=abuse_host($fh,\%MAILFILTER,,\%localvars,\@NAignor)
This function extracts the abuse host name and IP address from the headers passed in as ``message text''
```
  input:        file handle,
                config hash ptr,
                dnsbl config hash ptr,
                $localvars->{dbhome => path to environment},
                net object ptr,
```
```
  output:       empty array on success,
                (verbosity, err msg) on failure
        where verbosity is false on success,
        1,2,3, etc.... on failure
```
```
                fills %$localvars{
                        SPAM    => read buffer so far,
                        shost   => spam host,
                        to      => abuse host
                        hostIP  => ip address
                        ab2     => [for debug]
                };
```
$rv = is_GENERIC($conf->{GENERIC},@hostnames)
Check if a list of hostnames are all generic
```
  input:        hash pointer to 'GENERIC',
                hostname list
  returns:      true is generic
                false is not
```
block4zonedump($environment);
Checks to see if a dnsbl zonedump is in progress and blocks until the zonedump is complete
```
  input:        $environment pointer
  returns:      nothing
```
$object = new Mail::Spamcannibal::ScriptSupport;
Returns a reference to a Mail::Spamcannibal::ScriptSupport object
$rv = $object->dns2rblz($line);
Converts DNS bind file lines created by dnsbls to the rbldns format.
```
  input:        DNS bind file line
  returns:      rbldns file line or ''
```
Note: if the DNS file was dumped in standard format, the returned rbldns lines will be in the standard format also. If the DNS file was created in promiscious mode, the rbldns lines will be in the enhanced format provided by:
```
        djbdns-1.05 rbldns patch
```
```
  found at:
```
```
        http://www.jms1.net/djbdns/rbldns-patch.html
```
$textline = $object->rbldns_compress($textline);
Compress ip4tset rbldnsd data file lines produced by dns2rblz above to ip4set data format.
```
  input:        ip4tset line
  returns:      ip4set line
```
$firstline = $object->rbldns_combined($type);
Write the first line of an rbldns combined dataset of type ip4set | ip4tset.
```
  input:        type, one of ip4set or ip4tset
  returns:      dataset statement for ip4set
            or  undef on error
```
$last_combined = rbldns_address();
Write the generic format address record(s) for the name server within this address. This should be the last record after the ip4set is generated using a starting header generated by rbldns_combined (above).
```
  input:        none
  returns:      dataset statement + address
```
$lastline = $object->rbldns_done();
Complete the last line of an ip4set dataset conversion.
```
  input:        none
  returns:      remainder of last line
                in the ip4set data file
```
$lastline = $object->rbldnst_done();
Complete the last line of an ip4tset dataset conversion.
```
  input:        none
  returns:      remainder of last line
                in the ip4tset data file
```

DEPENDENCIES

        NetAddr::IP::Lite
        Net::DNS::Codes
        Net::DNS::ToolKit
        Net::DNS::ToolKit::RR
        Mail::SpamCannibal::GoodPrivacy
        Mail::SpamCannibal::BDBclient

EXPORT

        none by default

EXPORT_OK

        DO
        doINCLUDE
        SerialEntry
        TarpitEntry
        DNSBL_Entry
        id
        question
        revIP   
        query   
        dns_ans 
        zone_def
        valid127
        validIP
        zap_one
        zap_pair
        job_died
        dbjob_chk
        dbjob_kill
        dbjob_recover
        unpack_contrib
        lookupIP
        list2NetAddr
        matchNetAddr
        BLcheck
        checkclct
        dumpIPs
        BLpreen
        mailcheck
        abuse_host
        is_GENERIC
        block4zonedump

COPYRIGHT

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>