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 :

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

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

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

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

# 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. 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
haka.rule{
    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
            haka.alert{
                description = "Bad TCP checksum",
            }
            -- and drop the packet
            pkt:drop()
            -- alternatively, set the correct checksum
            --[[
            pkt:compute_checksum()
            --]]
        end
    end
}

-- securty rule to add a log entry on http connections to a web server
haka.rule{
    hook = tcp_connection.events.new_connection, --hook on new tcp connections.
    eval = function (flow, tcp)
        local web_server = ipv4.addr("192.168.20.1")
        if tcp.ip.dst == web_server and tcp.dstport == 80 then
            haka.log.debug("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 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.