honeybrid

honeybrid copied to clipboard

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

./autogen.sh ./configure make 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; }