Welcome to honeybrid.

honeybrid is free software. Please see the file COPYING for details.
For documentation, please see the files in the doc subdirectory.
For building and installation instructions please see the INSTALL file.

This readme file contains the following sections:
 QUICK INSTALL  to dive in right away
 OVERVIEW:      to understand what honeybrid can do
 EXAMPLE:       to illustrate how to deploy honeybrid
 DEPENDENCIES:  to list software and libraries required to build and use honeybrid
 SCRIPT AND CONFIGURATION FILE: to explain starting script and default configuration file
 DOCUMENTATION: where to find documentation for honeybrid
 KNOWN ISSUES:  to read before submitting a bug report
 CONTACT: 	    who to contact for help or bug report
 DEVELOPMENT: 	to explain how to add a new module to honeybrid


QUICK INSTALL

 ./build.sh
 sudo make install
 sudo mkdir /etc/honeybrid
 sudo mkdir /var/log/honeybrid
 sudo cp honeybrid.conf /etc/honeybrid/
 sudo cp honeybrid.sh /etc/init.d/

After successful compilation and install, edit /etc/honeybrid/honeybrid.conf to suit your needs, and start honeybrid with the command:
 sudo /etc/init.d/honeybrid.sh start

You can then bind honeybrid to your network and honeypots IP addresses with the command:
 sudo /etc/init.d/honeybrid.sh add <lih_ip> <lih_mac> <hih_ip> <ext_if> <int_if>
where:
 lih_ip  = Low interaction honeypot IP address
 lih_mac = Low interaction honeypot MAC addess
 hih_ip  = High interaction honeypot IP
 ext_if  = External interface (where Internet traffic will be received)
 int_if  = Internal interface (where honeynet traffic will be received)


OVERVIEW

Thank you for your interest in honeybrid!
The goals of honeybrid are:
 1) to facilitate the deployment and administration of large honeynet
 2) to combine low and high interaction honeypot to provide a highly scalable honeypot framework.
The second goal is achieved through a redirection mechanism that can transparently change the 
destination of a network session (TCP or UDP). Thus, uninteresting traffic can be handled by a 
front-end of low interaction honeypots or discarded right away, while interesting attacks can be 
forwarded to a back-end of high interaction honeypots for further analysis.

Honeybrid is a program that runs on a gateway between the farm of honeypots and the Internet.
Honeybrid has two main components:
 - a Decision Engine that analyzes incoming packets from Internet and that decide which connection should
   be accepted and potentially redirected, as well as when the redirection should occur,
 - a Redirection Engine that handles the network session to change dynamically and transparently the 
   destination IP.

For more information about how to install and use honeybrid, please refer to the detailed documentation
available in the ./doc folder or online on http://honeybrid.sf.net


EXAMPLE

Netfilter's functions are used to redirect traffic to honeybrid. It is important to correctly add
the queueing rules using iptables for honeybrid to receive the traffic it needs.
For example, in an architecture like:
							       ___________________
       	 __________                ___________		      / Low Int. Honeypot \ 
	/          \              / honeybrid \	      ,-----> |     10.0.0.2      |
	| attacker | <----------> |eth0   eth1| <-----|	      \___________________/
	\__________/              \___________/	      |	       ___________________
	                                              |	      / High Int. Honeypot\
	                                              `-----> |     10.0.0.3      |
							      \___________________/

The following rules will queue the traffic from the attacker to the low int. honeypot (honeyd) and from honeyd to the attacker, as well
as from the high interaction honeypot to honeybrid:
 iptables -A FORWARD -p tcp -i eth1 -s 10.0.0.2 -j QUEUE -m comment --comment 'honeybrid: packets from honeyd (LIH)'
 iptables -A FORWARD -p tcp -i eth0 -d 10.0.0.2 -j QUEUE -m comment --comment 'honeybrid: packets to honeyd (LIH)'
 iptables -A FORWARD -p tcp -i eth1 -s 10.0.0.3 -j QUEUE -m comment --comment 'honeybrid: packets from honeypot (HIH)'

Don't forget to active the routing mode:
 echo 1 > /proc/sys/net/ipv4/ip_forward


DEPENDENCIES

Honeybrid is dependent on the following public domain packages:
	gcc
	make
	binutils
	pkg-config
	openssl
	libnetfilter-conntrack-dev
	libnetfilter-conntrack1	(must be >= version 1.0.0)
	libnetfilter-queue-dev
	libnetfilter-queue1	(must be >= version 1.0.0)
	libnfnetlink-dev
	libnfnetlink0
	libglib2.0-0 (must be >= 2.14 to have support for regexp)
	libglib2.0-dev
	libc6-dev
	linux-libc-dev
	libpcap0.8
	libpcap0.8-dev
	libssl-dev
	libev
	libdumbnet

For Debian Lenny, running the following command will take care of all the dependencies:
	% sudo apt-get install make binutils gcc libnetfilter-conntrack-dev libnetfilter-conntrack1 libnetfilter-queue-dev libnetfilter-queue1 libnfnetlink-dev libnfnetlink0 pkg-config libc6-dev libglib2.0-0 libglib2.0-dev linux-libc-dev libpcap0.8-dev libpcap0.8 openssl libssl-dev libev-dev libdumpnet-dev

Latest version of libnetfilter_queue and libnetfilter_conntrack are available at:
	http://www.netfilter.org/projects/libnetfilter_queue/downloads.html
	http://www.netfilter.org/projects/libnetfilter_conntrack/downloads.html


SCRIPT AND CONFIGURATION FILE

   * honeybrid.conf
	honeybrid will not run without a configuration file, given in argument after the flag "-c".
	It is recommended to edit this file and then copy it into "/etc/honeybrid/honeybrid.conf"
	Include all parameters for honeybrid as well as definition of 
	detection modules and honeynet targets.

   * honeybrid.sh		
	The Start/Stop script
	Should be installed in "/etc/init.d/honeybrid.sh"
	Also includes "add" and "del" option to automatically add IP addresses
	to the iptables queue


DOCUMENTATION

Documentation for honeybrid is available:
 - online on http://honeybrid.sf.net
 - in the README and INSTALL files
 - in the folder "doc" is the developer documentation generated using doxygen
 - in the comments of the default configuration files


KNOWN ISSUES

TCP timestamps can become inconsistent between the honeypots and the replay mechanism, causing packets to get rejected.
A quick fix is to disable them on the honeypots through the command:
 echo net.ipv4.tcp_timestamps = 0 >> /etc/sysctl.conf

On Red Hat, libdumbnet is called libdnet. You can replace occurrences of "dumbnet" by "dnet" in the following files to be able to compile:
 src/Makefile.am:AM_LDFLAGS = -lnetfilter_queue -lpcap -lev -ldumbnet `pkg-config --libs gthread-2.0 glib-2.0` -lcrypto
 src/Makefile.in:AM_LDFLAGS = -lnetfilter_queue -lpcap -lev -ldumbnet `pkg-config --libs gthread-2.0 glib-2.0` -lcrypto
 src/rules.c:#include <dumbnet.h>
 src/rules.y:#include <dumbnet.h>
 src/syntax.c:#include <dumbnet.h>
 src/syntax.l:#include <dumbnet.h>
 src/tables.c:#include <dumbnet.h>
 src/types.h:#include <dumbnet.h>



CONTACT

Send problems, bug reports, questions and comments to robinb@umd.edu


DEVELOPMENT

Adding a new module in five steps -- Example with the module RANDOM:
 1. Create a file: mod_random.c, in which you can put the following functions:
	- int  init_mod_random() 	[** this is optional, only if you need some initialization **]
	- void mod_random(struct mod_args args)
    mod_random.c must also have the following includes:
	#include "tables.h"
	#include "modules.h"
	#include "netcode.h"
 2. Modify the Makefile to:
	- add mod_random.c to the target SRC
	- add the target "mod_random.o: log.h tables.h modules.h types.h"
 3. Add the following function declarations in modules.h:
	int init_mod_random();		[** this is optional, only if you need some initialization **]
	void mod_random(struct mod_args args);
 4. Add the following call in the function init_modules() in modules.c:
	init_mod_random();		[** this is optional, only if you need some initialization **]
 5. Add the following condition in the function get_module() in modules.c:
	else if(!strncmp(modname,"random",6))
                return mod_random;

Now that you completed these five steps, your module is defined and hooked to
the system. The last task is to get it do something! For this you just have
to fill the function mod_random() with instructions.
The args structure given in argument of mod_random() has two main variables:
 - args.pkt is a struct_pkt where you can extract args.pkt->conn to have
   access to the connection structure
 - args.node has two interesting variables: 
	args.node->arg is the argument configured for this module and this
	 connection in the rules of honeybrid
	args.node->result is an integer that must be updated at the end of
	 the processing in mod_random(), either with 0 (discard) or 1 (replay)

To illustrate how everything works together, here is the content of mod_random():
 --8<------------------------------
  void mod_random(struct mod_args args)
  {
	g_printerr("%s Module called\n", H(args.pkt->conn->id));

        unsigned int value = 0;
        unsigned int proba;
        int selector = 1;
        gchar *param;

        /*! getting the value provided as parameter */
        if (    (param = (char *)g_hash_table_lookup(args.node->arg, "value")) == NULL ) {
                /*! We can't decide */
                args.node->result = -1;
                g_printerr("%s Incorrect value parameter: %d\n", H(args.pkt->conn->id), value);
                return;
        } else {
                value = atoi(param);
        }

        if (value < selector) {
                /*! We can't decide */
                args.node->result = -1;
                g_printerr("%s Incorrect value parameter: %d\n", H(args.pkt->conn->id), value);
                return;
        }

        /*! deciding based on a probability of 1 out of "value": */
        proba = (int) (((double)value) * (rand() / (RAND_MAX + 1.0)));

        if (proba == selector) {
                /*! We accept this packet */
                args.node->result = 1;
                g_printerr("%s PACKET MATCH RULE for random(%d)\n", H(args.pkt->conn->id), value);
        } else {
                /*! We reject this packet */
                args.node->result = 0;
                g_printerr("%s PACKET DOES NOT MATCH RULE for random(%d)\n", H(args.pkt->conn->id), value);
        }
  }
 ----------------------------------

We can see from the code that mod_random() uses the argument "value". This means that when defining this 
module in the configuration of honeybrid, user should write the value parameter. Here is an example:
 --8<---(honeybrid.conf)-----------
 module "myrandom" {
        function = random;
        value = 20;
 }
 ----------------------------------

Another interesting parameter that can be defined is "backup". It is used by more complex modules that need
to save results to an external file periodically (and that can load previously recorded results when honeybrid
starts).
Here is an example of module definition for the "hash" module that uses such backup functionality:
 --8<---(honeybrid.conf)-----------
 module "myhash" {
        function = hash;
        backup = /etc/honeybrid/hash.tb;
 }
 ----------------------------------

When using the backup parameter, the following function should be called at the end of the module processing 
function:
 --8<------------------------------
 save_backup(backup, backup_file);
 ----------------------------------

Where backup is retrived through the "backup" parameter (it's a pointer to a GKeyFile), and backup_file is 
a string to give the path and filename of the external file where results should be saved. Here is an excerpt
from the source code of mod_hash.c that shows how to retrieve these two parameters:
 --8<------------------------------
        /*! get the backup file for this module */
        if ( NULL ==    (backup = (GKeyFile *)g_hash_table_lookup(args.node->arg, "backup"))) {
                /*! We can't decide */
                args.node->result = -1;
                g_printerr("%s mandatory argument 'backup' undefined!\n", H(args.pkt->conn->id));
                return;
        }
        /*! get the backup file path for this module */
        if ( NULL ==    (backup_file = (gchar *)g_hash_table_lookup(args.node->arg, "backup_file"))) {
                /*! We can't decide */
                args.node->result = -1;
                g_printerr("%s error, backup file path missing\n", H(args.pkt->conn->id));
                return;
        }
 ----------------------------------