honeytrap.mwcollect.org

Compiling

Compiling honeytrap is pretty straight forward. The configure shell script included in the source distribution must be told to compile one of the connection monitors into the program. This is done via the --with-stream-mon=[type] option where [type] is one of the following:

nfq	On recent Linux systems one should use the netfilter_queue-based stream monitor. Packets get delivered to honeytrap by invoking an iptables rule like iptables -A INPUT -i eth0 -p tcp --syn -m state --state NEW -j NFQUEUE.
ipq	This enables the libipq-based connection monitoring on Linux systems. Use a rule like iptables -A INPUT -i eth0 -p tcp --syn -m state --state NEW -j QUEUE to make iptables deliver incoming connection requests to honeytrap
pcap	The libpcap-based connection monitor is available for every system that is pcap compatible. It uses a sniffer to detect incoming connection requests.

Please note that you have to choose one of the above options, otherwise configure would stop. Additionally, you can enable the Electric Fence malloc debugger by passing the --with-efence option to the script (does not work on Xen). An example call would be

./configure --with-efence --with-stream-mon=pcap

To compile honeytrap, simply do a make in the source directory after configure completed without errors. You can install required files in proper locations by doing a make install.

Configuration

A typical config file

The main configuration file honeytrap.conf is normally located in /etc/honeytrap. You can split up your configuration into multiple files and include them into the main file. A typical honeytrap configuration (version 1.0.0 or later) looks like this:

logfile         	= "/var/log/honeytrap.log"
pidfile         	= "/var/run/honeytrap.pid"
response_dir    	= "/etc/honeytrap/responses"

portconf_default	= "normal"
mce_private_ips		= "yes"

read_limit		= "20971520"

user			= "nobody"
group			= "nogroup"

If you want to load plugins to automatically process recorded attacks, you must tell honeytrap where to find them. A plugin can have specific configuration options as well.

plugin_dir		= "/etc/honeytrap/plugins"

plugin-ftpDownload = ""
plugin-tftpDownload = ""
plugin-vncDownload = ""
plugin-b64Decode = ""

plugin-httpDownload = {
        http_program = "/usr/bin/wget"
        http_options = "-q"
        download_dir = "/var/spool/honeytrap/downloads/"
}

plugin-SaveFile = {
        attacks_dir     = "/opt/honeytrap/attacks"
        downloads_dir   = "/opt/honeytrap/downloads"
}

plugin-ClamAV = {
        temp_dir        = "/tmp"
        clamdb_path     = "/var/lib/clamav"
}

plugin-SpamSum = {
        md5sum_sigfile  = "/opt/honeytrap/md5sum.sigs"
        spamsum_sigfile = "/opt/honeytrap/spamsum.sigs"
}

Including other files comes in handy when using many explicit mode configurations for specific ports. To include the file ports.conf, just add

include = "/etc/honeytrap/ports.conf"

The ports.conf file could look like this:

portconf = {
	/* ignore these ports */
	ignore = {
		protocol	= "tcp"
		port		= ["25", "1433"]
	}

	/* process ports in normal mode */
	normal = {
		protocol	= ["tcp", "udp"]
		port		= ["53"]
	}

	/* mirror ports back to the initiator */
	mirror = {
		protocol	= ["tcp"]
		port		= ["23"]
	}

	/* proxy ports to a target */
	proxy = {
		proxy-http = {
			protocol	= ["tcp"]
			port		= ["80", "8080"]

			target_host	= "127.0.0.1"
			target_protocol	= "tcp"
			target_port	= "8080"
		}
		proxy-tftp = {
			protocol	= ["udp"]
			port		= ["69"]

			target_host	= "tftp.localhost"
			target_protocol	= "udp"
			target_port	= "69"
		}
	}
}

Running it

Start the program by simply calling honeytrap from the command line (assumed that your $PATH variable contains the path to the honeytrap binary). Refer to the man page for a list of available command line options. After initializing itself, honeytrap is ready for catching attacks. The following command triggers a re-initialization, including loading additional plugins and new default responses:

kill -HUP `cat /var/run/honeytrap.pid`

Problems

If you encounter problems, you should first try the latest svn code, it may already contain a fix. If the problem is also in the bleeding-edge code, please help improving the software and send a report to Tillmann Werner.