NAME

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

SYNOPSIS

  use Mail::SpamCannibal::ScriptSupport qw(
	DO
	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
	BLpreen
	mailcheck
	abuse_host
  );

  $rv = DO($file);
  $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);
  $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);
  $rv = BLpreen(\%DNSBL,\%default);
  @err=mailcheck($fh,\%MAILFILTER,\%DNSBL,\%default,\@NAignor)
  $rv=zap_one($tool,$netaddr,$db,$verbose,$comment);
  zap_pair($tool,$netaddr,$pri,$sec,$debug,$verbose,$comment);

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);

Imported from Net::DNSBL::Utilities 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
```
$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,
		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 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 DNSBL's 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.
$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)

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,
  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,
  );
```

@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]
		};

DEPENDENCIES

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

EXPORT

none by default

EXPORT_OK

DO
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
BLpreen
mailcheck
abuse_host

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>

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)