3. Getting started

3.1. Running Haka

haka is primarily intended to be used as a daemon. This daemon will usually use a configuration file given on the command line using the -c option.

The following command will launch haka from the command line using an example configuration file:

$ cd <haka_install_path>/share/haka/sample/gettingstarted
$ sudo haka -c gettingstarted.conf

3.2. Sample configuration

The content of the file gettingstarted.conf is detailed below :

# Select the haka script file
configuration = "gettingstarted.lua"

# Select the capture method: nfqueue or pcap
module = "packet/nfqueue"

# Select the interfaces to listen to
interfaces = "eth0"

# Set log level
level = "warn,tcp_connection=error,ipv4=debug"

# Select the log module
module = "log/syslog"

# Select the alert module
module = "alert/syslog"

This configuration file instructs haka to capture packets from interface eth0 using nfqueue and to filter them based on the Lua policy script gettingstarted.lua

3.3. First Haka policy file

The content of the file gettingstarted.lua is detailed below :

-- load the ipv4 dissector to be able to read the fields of ipv4 packets
local ipv4 = require("protocol/ipv4")

-- load the tcp dissectors (statefull and stateless)
-- this is needed to be able to track tcp connections
-- and to get access to tcp packet fields
local tcp = require("protocol/tcp")
local tcp_connection = require("protocol/tcp_connection")

-- security rule to discard packets with bad tcp checksums
    hook = tcp.events.receive_packet, -- hook on new tcp packets capture
    eval = function (pkt)
        -- check for bad ip checksum
        if not pkt:verify_checksum() then
            -- raise an alert
                description = "Bad TCP checksum",
            -- and drop the packet
            -- alternatively, set the correct checksum

-- securty rule to add a log entry on http connections to a web server
    hook = tcp_connection.events.new_connection, --hook on new tcp connections.
    eval = function (flow, tcp)
        local web_server = ipv4.addr("")
        if tcp.ip.dst == web_server and tcp.dstport == 80 then
            haka.log.debug("Traffic on HTTP port from %s", tcp.ip.src)

This script starts by loading the required protocol dissectors - namely the ipv4 and tcp modules - then specifies two security rules. The first rule is evaluated whenever a new tcp packet is received. It allows to drop packets with invalid checksums. The second rule is triggered each time a new tcp connection is established. Its only purpose is to add a log entry if the packet is addressed to a specific ip address and port.

3.4. Going further

Other documented examples are available to illustrate all features of Haka. Those samples are installed in <haka_install_path>/share/haka/sample and the corresponding documentation can be found at Tutorials.