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 command line option.

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

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

3.2. Sample configuration

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

[general]
# Select the haka script detailing the filtering rules
configuration = "gettingstarted.lua"

[packet]
# Select the capture method, nfqueue or pcap
module = "packet/nfqueue"

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

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

[alert]
# 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. Lua language

Haka uses the language Lua to define its policy files. It is a simple scripted language. If you are not familiar with it, you might find helpful to check the language manual and examples. You should find many informations on various website, but a good starting point is the official Lua page at http://www.lua.org/.

3.4. First Lua policy file

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

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

-- load the tcp disector, this is needed to be able to track connections
require("protocol/tcp")

-- rule to check packet for bad TCP checksums and reject them
haka.rule{
    hooks = { "tcp-up" }, -- hook on tcp packets, before any sub-protocol is parsed.
    eval = function (self, pkt)
        -- check for bad IP checksum
        if not pkt:verify_checksum() then
            -- raise an alert
            haka.alert{
                description = "Bad TCP checksum",
            }
            -- and drop the packet
            pkt:drop()
            -- alternatively, set the correct checksum
            --[[
            pkt:compute_checksum()
            --]]
        end
    end
}

-- rule to add a log entry on HTTP connections to a web server
haka.rule{
    hooks = { "tcp-connection-new" }, --hook on new TCP connections.
    eval = function (self, pkt)
        local tcp = pkt.tcp -- the packet, viewed as a TCP packed
        if tcp.ip.dst == ipv4.addr("192.168.20.1") and tcp.dstport == 80 then
            haka.log.debug("filter","Traffic on HTTP port from %s", tcp.ip.src)
        end
    end
}

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 captured (hook on tcp-up). It allows to drop packets with invalid checksums. The second rule is triggered each time a new tcp connection is established (hook on tcp-connection-new). Its only purpose is to add a log entry if the packet is addressed to a specific ip address and port.

3.5. 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 Writing Haka scripts.