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 [email protected]
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;
}
----------------------------------