Honeybrid: Hybrid Honeypot Framework

General parameters

# The configuration of honeybrid is divided into three sections:
# - main:   where the main parameters of honeybrid are defined
# - module: where individual modules to process packets are defined and given a name
# - target: where individual targets are defined, to link modules with a traffic filter
#           expression
# It is important to have modules defined before targets!

## main configuration:
# Where the parameters of honeybrid are defined
config {
    ## output mode
    # 1 = syslog
    # 2 = stdout (do not daemonize)
    # 3 = log files
    # 4 = MySQL
        output = 3;

    ## pid directory
        exec_directory = /var/run/;

    ## log file directory
        log_directory = /var/log/honeybrid/;

    ## enable automatic hourly log rotation (applies only for connection logs, not for debug logs)
        log_rotation = 0;

    ## connection log file (log_directory defines the path)
        log_file = honeybrid.log;

    ## CSV log file format
        #log_format=csv;

    ## MySQL server parameters for logging
        #mysql_host = localhost;
        #mysql_user = my_user;
        #mysql_password = my_password;
        #mysql_db = my_db;
        #mysql_port = 3306;

    ## enable debug logfile?
        debug = 0;
    ## debug log file (detailed internal process, log_directory defines the path)
    #    debug_file = honeybrid.debug;

    ## Number of seconds after which network sessions are expired
        expiration_delay = 120;

    ## 'yes' to send reset to external host when there is an issue, 'no' to remain silent
        reset_ext = no;

    ## Dionaea XMPP listener parameters
        #xmpp_listener = /opt/honeybrid/xmpp_listener;
        #xmpp_fifo = /opt/honeybrid/xmpp.pipe;
        #xmpp_user = honeybrid;
        #xmpp_server = prosody-server;
        #xmpp_password = my_password;
        #xmpp_channel = my_channel;
        #xmpp_domain = my.domain;
        #xmpp_debug = /opt/honeybrid/xmpp.debug;
        #xmpp_db = /opt/honeybrid/xmpp.db;
}

# Each section 'module' requires a name (between quotes)
# and a parameter 'function' that defines the type of module that will be used to process packets
# Other parameters are required depending on the type of function used
# 
module "random" {
	function = random;
	# The module random needs a single parameter 'value'. 
	# A value of 10 means that 1 out of 10 packets will be randomly accepted
	value = 10;
}

module "hash" {
        function = hash;
	# The module hash needs a single parameter 'backup', 
	# to know where it should save the database of payload hashes
        backup = /etc/honeybrid/hash.db;
}

module "counter" {
        function = counter;
	# The module counter needs a single parameter 'counter', 
	# that defines after how many packets should it returns 'accept'
        counter = 2;
}

module "control" {
        function = control;
	# The module control needs 3 parameters:
	# 'backup' to define where the database of controlled IP addresses should be saved
        backup = /etc/honeybrid/control.db;
	# 'expiration' to know after how many seconds should IP be removed from the database
        expiration = 600;
	# 'max_packet', to give the maximum number of accepted packets sent during 'expiration' before	
	# rejecting packets.
        max_packet = 1000;
}

module "source" {
        function = source;
	# The module source needs 2 parameters:
	# 'backup' to define where the database of know IP addresses should be saved
        backup = /etc/honeybrid/source.db;
	# 'expiration' to know after how many seconds should IP be removed from the database
	expiration = 600;
}

Target definition

# Each section 'target' requires 4 parameters:
#  'filter'   (mandatory) to define the type of traffic covered by this target (using the tcpdump syntax)
#  'frontend' (mandatory) to define a rule to accept traffic (using a boolean equation of modules)
#  'backend'  (optional)  to define a rule to redirect traffic (using a boolean equation of modules)
#  'control'  (optional)  to define a rule to control outgoing traffic iniated by honeypots (using a boolean equation of modules)
# The frontend and backend parameters also requires the IP address of the honeypot in charge of the frontend or backend respectively.
# The tcpdump filter and the boolean equations require quotes.

target {
        filter "dst host 192.168.0.10 and port 80";
        frontend 192.168.0.10 "source or random";
        backend 192.168.0.11 "hash";
        control "control";
}

Here is an example of honeynet deployed using Honeybrid to collect web attacks targeting the service tcp/80. The specifications for this experiment are:

• 3 Linux machines available:
  • a low interaction honeypot (10.0.0.2) running Honeyd (with a script configured to emulate Apache),
  • a high interaction honeypot (10.0.0.3) running Apache,
  • a gateway running Honeybrid
• A /21 subnet available to collect traffic (2,048 IP addresses).

Configuration

To run such experiment, we would start by configuring the following target in honeybrid.conf:

target {
	filter "dst net 10.0.0.2 and proto tcp and port 80";
	frontend 10.0.0.2 "source or random";
	backend  10.0.0.3 "hash or counter";
	control "control";
}

We would then configure our five modules as described in the module section of the documentation of honeybrid.conf above.

The next step would be to configure the Netfilter firewall on the gateway so that Honeybrid can receive attack and honeypot traffic. This would be achieved using the following commands:

iptables -A PREROUTING -d 10.0.0.0/21 -j DNAT --to-destination 10.0.0.2 -m comment --comment "NAT rule for attack traffic to be sent to honeyd"
iptables -I FORWARD -d 10.0.0.2 -j QUEUE -m comment --comment "Incoming attack traffic"
iptables -I FORWARD -s 10.0.0.2 -j QUEUE -m comment --comment "Outgoing traffic from honeyd"
iptables -I FORWARD -s 10.0.0.3 -j QUEUE -m comment --comment "Outgoing traffic from high interaction honeypot"

The final step would be to start Honeybrid:

/etc/init.d/honeybrid start

Data collection

The attack data collection would be reported in the main log file of honeybrid, as well as in the module backup files.

The main log file of Honeybrid output one flow per line. The path for this log file is by default /var/log/honeybrid/honeybrid.log. Here is a sample output of this file:

2009-08-13 12:24:14.507182 1.069 TCP 75.54.75.79:3640 -> 10.0.0.2:80 1 76 INIT
2009-08-13 12:24:17.802673 0.000 UDP 190.24.167.119:65208 -> 10.0.0.2:53 1 55 DROPPED
2009-08-13 12:24:17.418888 0.000 UDP 190.72.164.176:17604 -> 10.0.0.2:53 1 57 DROPPED
2009-08-13 12:24:19.297894 1.181 TCP 80.26.77.71:2220 -> 10.0.0.2:80 6 264 FORWARD
2009-08-13 12:24:19.696378 1.388 TCP 201.92.102.117:2532 -> 10.0.0.2:80 6 264 FORWARD
2009-08-13 12:24:26.177629 0.000 UDP 189.71.12.30:1171 -> 10.0.0.2:53 1 59 DROPPED
2009-08-13 12:24:52.764639 4.047 UDP 93.96.65.14:52771 -> 10.0.0.2:3038 2 138 DROPPED
2009-08-13 12:24:54.829422 3.999 UDP 93.96.65.14:52774 -> 10.0.0.2:2097 2 134 DROPPED
2009-08-13 12:24:56.600800 3.044 TCP 201.8.253.38:60610 -> 10.0.0.2:80 2 156 INIT
2009-08-13 12:25:00.018360 0.000 UDP 64.244.103.70:43723 -> 10.0.0.2:53 1 116 DROPPED

1. timestamp: 2009-08-13 12:24:14.507182
2. duration in second: 1.069
3. protocol: TCP
4. source IP and source port: 75.54.75.79:3640
5. destination IP and destination port: 10.0.0.2:80
6. number of packets: 1
7. number of bytes: 76
8. status of the connection after being expired by timeout (default: 120 seconds of inactivity): INIT

1. INIT: initialization status applied to all new network flows,
2. DECISION: when the network flow reached the Decision Engine,
3. REPLAY: when Honeybrid decides to redirect the flow and starts the replay process,
4. FORWARD: when the replay process has been completed and packets are forwarded between the attacker and the backend,
5. PROXY: when there is no backend defined, but packets have been accepted so they are forwarded between the attacker and the frontend,
6. DROPPED: when the flow has been dropped by Honeybrid (based on the output of the decision modules),
7. CONTROL: when the flow has been iniated by a honeypot and is being controlled by the Control Engine.

Here is a sample output of the backup file for the hash module:

[80]
d20f64acc6e70b6079845f2fe357732929550ae1=1      1249600127      0       2       7       GET /. 
bba48dc680c4c8307b417eab5d5c34c0e8cb8ca5=2      1249941662      1       2       46      GET /w00tw00t.at.ISC.SANS.DFind
67a7422786a0717dd3aa08c91468ae54812563e6=1      1249997593      0       2       157     GET / HTTP/1.0..Host
686992e5ab00430d7d5add1f64cbec39b681c353=1      1250000907      0       2       98      GET /IDS5web/bin/lang HTTP/1.1..User-Agent
ae28f258147bb6b4ea02e980c8aa8bb0f28f27fc=1      1250000907      0       2       93      GET /IDS5web/bin HTTP/1.1..User-Agent
739b5df5c2c38de0609faa3e6087a85a7ee33d3c=1      1250002021      0       2       180     GET HTTP/1.1 HTTP/1.1..Accept
06f26836f7cbd70f280286b2a254e90ebe0e6ec0=1      1250002024      0       2       201     GET /misc/mantis/login_page.php HTTP/1.1..Accept
4a071f1219b0ea8594ab59763f6c9a00b942cf04=1      1250002024      0       2       196     GET /mantis/login_page.php HTTP/1.1..Accept
dc7b235a91e26895aec6a8354197dba86a994020=1      1250002024      0       2       202     GET /tools/mantis/login_page.php HTTP/1.1..Accept
12f0345fa353b6b181c45896290cb38d74a80431=1      1250002024      0       2       204     GET /support/mantis/login_page.php HTTP/1.1..Accept
adefddcaf925e11f4b2c4f3db42063ef9bcc2d6b=1      1250002024      0       2       200     GET /php/mantis/login_page.php HTTP/1.1..Accept
3ec1ec08a0c94ffe4c24632c041b73edcdde845f=1      1250002024      0       2       202     GET /turbo/mantis/login_page.php HTTP/1.1..Accept
7c454a859b585745fbb8aa42da84f4bf64548d50=1      1250002024      0       2       198     GET /mantisbt/login_page.php HTTP/1.1..Accept

1. the payload hash: d20f64acc6e70b6079845f2fe357732929550ae1=1
2. the timestamp when this hash was first recorded: 1249600127
3. the duration in second during which this hash was sent by attackers: 0
4. the packet index in the flow during which this payload was collected: 2
5. the number of bytes of the payload: 7
6. the 64 first characters of ASCII representation of the payload: GET /.

The development of Honeybrid was initiated in 2007 by Robin Berthier as part of his PhD research. The main developer of Honeybrid in 2007 was Julien Vehent. Julien designed and implemented the architecture based on a Decision Engine and a Redirection Engine. In 2008, Thomas Coquelin took over the development of the project. Thomas consolidated the prototype of Honeybrid and built a robust redirection mechanism. In 2009, Honeybrid was sponsored by the Honeynet Project and the Google Summer of Code to be turned into an open source application. In 2012 Tamas K Lengyel expanded Honeybrid to support additional GRE tunnels and clone routing when used in conjuction with VMI-Honeymon as part of his PhD research at the University of Connecticut. Honeybrid was a central part of the research papers Virtual Machine Introspection in a Hybrid Honeypot Architecture and Towards Hybrid Honeynets via Virtual Machine Introspection and Cloning.

If you would like to join this project and contribute to Honeybrid, please contact the project administrators, as shown on the project summary page.

The decision engine of Honeybrid works with module. Here is an example based on the module mod_random() to illustrate how to implement a new module:

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 have the following include:
   • #include "modules.h"
2. Modify the Makefile.am to:
   • add mod_random.c to the target SRC
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 to the module enumeration at the top of modules.c:
   • MOD_RANDOM,
6. Add the following to the module definition array at the top of modules.c:
   • [MOD_RANDOM] = {.name = "random", .function = mod_random},

Now that you completed these 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():

void mod_random(struct mod_args *args)
{
    g_printerr("%s Module called\n", H(args->pkt->conn->id));

    unsigned int probe;
    uint32_t selector = 1;
    const uint32_t *value;

    /*! getting the value provided as parameter */
    if ((value = (const uint32_t *)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;
    }

    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": */
    probe = (int) (((double) *value) * (rand() / (RAND_MAX + 1.0)));

    if (probe == 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:

 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:

 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:

 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:

        /*! 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;
        }

Please note that the parameter "backup_file" is created automatically and should not be added in the configuration file of Honeybrid.

• Implement module mod_load() to accept incoming packets only if the honeynet is not saturated
• Implement module mod_sample(), similar to mod_random() but using a fixed counter to decide to accept packets
• Implement module mod_snort(), to use the real time output of snort to decide to accept or reject packets
• Restore support for automated PCAP saving of the redirected network traffic
• Export connection logs using Argus format or Netflow v9 format or IPFIX format
• Implemented multi-uplink support when using clone-routing.

Project Web Hosted by and last updated on 2013-05-16.