NAME

Mail::SMTP::Honeypot -- Dummy mail server

SYNOPSIS

use Mail::SMTP::Honeypot;

run_honeypot($config)

DESCRIPTION

Mail::SMTP::Honeypot is a perl module that appears to provide all the functionality of a standard SMTP server except that when the targeted command state is detected (default DATA), it terminates the connection with a temporary failure and the response:

421 Service not available, closing transmission channel

The purpose of this module is to provide a spam sink on a tertiary MX host. The module daemon is run on an MX host with a very high priority number specified in it's DNS record. i.e.

some_mail_domain.com	IN MX 9999 lastmx.servicedomain.com.

Since many spammers target this mail server in the hope that its configuration and/or security is not as strong or well maintained as the primary mail host for a domain. In the off chance that a real message is sent to the server, the TEMPORARY failure code will simply make the sending host retry later -- probably with the lower priority numbered host. Meanwhile, the server target by the spam source has its resources consumed by honeypot.

Honeypot does not spawn children and holds only a small reference to each thread that it holds to a client, thus consuming minimal resources. It can produce logs useful in analyzing the spam traffic to your site. Using it with a detach in CONN mode is adequate for triggering a companion spam program such as Mail::SpamCannibal while consuming minimum host resources. At our site, we simply run honeypot on the same host as our secondary MX but on a different IP address.

Honeypot provides various levels of connection and transaction logging that can be set in the configuration.

A delay may be inserted between the receipt of each command and the response from the server daemon to slow down the sending client.

CONFIGURATION

Edit the rc.honeypot.pl file to change or set the following:

  my $config = {

  # specify the directory for the pid file for this daemon
  # [required]
  #
	piddir		=> '/var/run',

  # deny at command state, one of:
  #	CONN EHLO HELO MAIL RCPT DATA
  # defaults to DATA if not specified
  # [optional]
  #	deny		=> 'DATA',


  # specify the local domain name, defaults to local hostname.
  # this is probably not what you want if you use virtual IP's
  # and have a real mail client on the same host. so...
  # specify the host 'answerback name' here.
  # [optional]
  #
  #	hostname	=> 'my.host.name.com',

  # specify the IP address to bind the listening port
  # defaults to ALL interfaces (INADDR_ANY)
  # [optional]
  #
  #	ip_address	=> '1.2.3.4',

  # listen port -- default 25
  # this is useful for debugging purposes
  # [optional]
  #
  #	port		=> 25,

  ## NOTE: 	see Concurrent Daemon Operation in the
  ##		documentation for setup where another
  ##		mail daemon is running on the same host.
  
  # specify the response delay after connect or upon
  # receipt of an smtp command from the client
  #
  # NOTE:	if a response is not received
  #		from the client in this time
  #		period, the smptdeny daemon will
  #		issue a 421 response and disconnect
  # [optional] default 10 seconds
  #
  #	delay		=> 10,

  # syslog facility, one of:
  #	LOG_KERN LOG_USER LOG_MAIL LOG_DAEMON
  #	LOG_AUTH LOG_SYSLOG LOG_LPR LOG_NEWS
  #	LOG_UUCP LOG_CRON LOG_AUTHPRIV LOG_FTP
  #	LOG_LOCAL0 LOG_LOCAL1 LOG_LOCAL2 LOG_LOCAL3
  #	LOG_LOCAL4 LOG_LOCAL5 LOG_LOCAL6 LOG_LOCAL7
  #
  # You should not need to change this
  #
  #	log_facility	=> 'LOG_MAIL',

  # syslog log level or (none), one of:
  #	STDERR LOG_EMERG LOG_ALERT LOG_CRIT LOG_ERR
  #	LOG_WARNING LOG_NOTICE LOG_INFO LOG_DEBUG
  #
  # NOTE: 	the command line -d flag overrides
  #		this and sets the level to STDERR
  # [optional]
  #
	syslog		=> 'LOG_WARNING',

  # log verbosity
  #	0 connect only
  #	1 + To: & From:
  #	2 + bad commands
  #	3 + trace execution
  #	4 + deep trace with sub names
  # [optional]
  #
	verbose		=> 0,

  # DNS host, if you do not have a resolver
  # on your host or for debugging
  # default: as returned by your resolver for local dns
  # [optional]
  #	dnshost		=> 'use.default',

  # DNS port, useful for debugging
  # [optional] default 53
  #
  #	dnsport		=> 53,

  # timeout for DNS PTR queries
  # [optional] default: use 'delay' above
  #
  #	DNStimeout	=> 10,

  # maximum number of connected clients
  # [optional] default 100
  #
  #	maxthreads	=> 100,

  # maximum number of commands per client
  # [optional] default 100
  #
  #	maxcmds		=> 100,

  # disconnect the remote after this much time
  # [optional] default 300 seconds
  #
  #	disconnect	=> 300,

  };

OPERATION

Launch the daemon with the command:

rc.honeypot.pl [-d] [start | stop | restart]

The '-d' flag, this overides the config settings and reports logging to STDERR

On some systems it may be necessary to wrap a shell script around rc.honeypot.pl if the path for perl is not in scope during boot.

#!/bin/sh
#
# shell script 'rc.honeypot'
#
/path/to/rc.honeypot.pl $*

A sample shell script is included in the distribution as rc.honeypot

NOTE: suggest you test your configuration as follows...

  Set:	verbose	=> 3,
	delay	=> 5,

  ./rc.honeypot -d start

Connect to the daemon from a host not on the same subnet and watch the output from daemon to verify proper operation.

Correct the configuration values and ENJOY!

Standalone Operation

For operation on a host where Mail::SMTP::Honeypot is the only SMTP daemon, the default configuration will work for most installations.

Concurrent Daemon Operation

To operate Mail::SMTP::Honeypot concurrently with another mail daemon on the same host you must do the following:

1) add a virtual IP address for the daemon to answer. The IP address in the rc.honeypot.pl config section should be left commented out so that the daemon will bind to INADDR_ANY.

In your startup sequence, execute the following: (example for Linux)

#/bin/sh
#
# Edit for your setup.
NETMASK="255.255.255.0"	# REPLACE with YOUR netmask!
NETWORK="5.6.7.0"		# REPLACE with YOUR network address!
BROADCAST="5.6.7.255"		# REPLACE with YOUR broadcast address
# assign a virtual IP address
IPADDR="5.6.7.8"

# assign ethernet device
DEVICE="eth0"			# REPLACE with your external device
LUN="0"

# Note:	the "real" IP address has no LUN
#		virtual IP's are assigned LUN's starting with '0'
#
# i.e.	host IP = 5.6.7.1	eth0
# virtIP	5.6.7.8		LUN 0	eth0:0
# virtIP	5.6.7.9		LUN 1	eth0:1

IFACE=${DEVICE}:${LUN}
/sbin/ifconfig ${IFACE} ${IPADDR} broadcast ${BROADCAST} netmask ${NETMASK}
/sbin/route add ${IPADDR} dev ${IFACE}
echo Configuring $IFACE as $IPADDR

2) run the honeypot daemon on an unused port.

Select a high port number that will not interfere with normail operation of the host SMTP daemon or other services on the host.

  i.e.	in the config section of rc.honeypot.pl

	port	=> 10025,

3) add packet filter rules to redirect queries.

This example is for IPTABLES on Linux. Similar rules would apply for other filter packages.

# allowed chain for TCP connections
iptables -N allowed
iptables -A allowed -p tcp --syn -j ACCEPT
iptables -A allowed -p tcp -m state --state ESTABLISHED,RELATED -j ACCEPT
iptables -A allowed -p tcp -j DROP

# drop all external packets target on honeypot daemon
iptables -t nat -A PREROUTING -p tcp -s 0/0 --dport 10025 -j DROP
iptables -t nat -A PREROUTING -p tcp -d 5.6.7.8 --dport 25 -j REDIRECT --to-port 10025
# alternate DNAT statement
# iptables -t nat -a PREROUTING -p tcp -d 5.6.7.8 --dport 25 -j DNAT --to 5.6.7.8:10025

## if you are running SpamCannibal, add this rule to capture IP's of connecting hosts
## iptables -A INPUT -p tcp -i eth0 --dport 10025 -j QUEUE

# allow the internal port to connect
iptables -A INPUT -p tcp -s 0/0 --dport 10025 -j allowed

EXPORTS

Only one function is exported by Honeypot.pm. This function is called in the rc.honeypot.pl.sample script to launch the honeypot daemon.

• run_honeypot($config); # with @ARGV

  Launch the honeypot daemon.

  input:	config hash
  returns:	nothing (exits)

COPYRIGHT

Copyright 2004 - 2014, 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 (except as noted otherwise in individuals sub modules) 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>

SEE ALSO

Mail::SpamCannibal on CPAN or spamcannibal.org

cpanm Mail::SMTP::Honeypot

perl -MCPAN -e shell
install Mail::SMTP::Honeypot