2. Hellopacket¶

As a basic example to get up to speed with Haka this section will help you to learn how to create basic rules, access data from the packets and display logging information and security alerts.

2.1. Setting up my first Haka script¶

Haka configuration is done with script file. Haka scripts are mainly Lua files. To put a first step into Haka we are going to write a small script aiming to log every ip packet passing through Haka.

Let’s get started by opening your first script with your favorite editor:

Exercise

$ editor hellopacket.lua

2.1.1. Modules¶

Each Haka script must tells Haka which modules it will need. In Haka, dissectors are modules. As our goal is to log every ip packet we will need ip module.

local ipv4 = require('protocol/ipv4')

Lua allow modules to be set in a local variable. Every Haka module use this feature to avoid contaminating the global state. Haka provides only one keyword on the global state: haka. This is the starting point of every functionality provided by Haka.

2.1.2. Rules¶

Haka is event based. It will trigger event to let you verify some property and react if needed. You can declare these checks and reactions with Haka rules.

If we sum up, Haka rules are made of:

an event to hook to

a Lua function to check and react

We can declare our first rule by adding the following lines in our hellopacket.lua script:

haka.rule{
    hook = ipv4.events.receive_packet,
    eval = function (pkt)
        -- Do some check on pkt and react if necessary
    end
}

Each dissector will trigger its own events. The event you hook to determines the arguments passed to the eval function. You can find a full list of the available events and their arguments in the documentation.

2.1.3. Logs¶

Finally, Haka provides some log and alert facilities. As you might already have guess, you can find it under haka keyword. Now we can finish our first Haka script by adding the following line in the eval function inside the rule:

haka.log("Hello", "packet from %s to %s", pkt.src, pkt.dst)

Additionally you can throw an alert with haka.alert. For example the following code will throw an alert of low severity:

haka.alert{
    description = "A simple alert",
    severity = "low"
}

Note

The alerts are targeted to network administrators, they contain security information that could be reported in some kind of monitoring tool. You can check the alert description in the reference guide.

Exercise

Write your first haka rule using logging and alert facilities.

2.1.4. Running the script¶

Now that your first script is finished you might want to see it in action. You can simply use hakapcap to test it on a provided pcap file (hellopacket.pcap):

$ hakapcap hellopacket.lua hellopacket.pcap

2.1.5. Full script¶

For ease of simplicity you can download the full script here hellopacket.lua.

2.2. Optional: Interactive rule¶

Now you should have all the prerequisite to have some fun with Haka. But soon you will complain that it can be quite boring to go back and forth between your script and the documentation.

In order to ease the development steps of your script Haka provides a magic eval function named interactive_rule. If you use it, Haka will stop and you will see a prompt which allow to enter Lua commands.

Here is an example of an interactive rule:

local ipv4 = require('protocol/ipv4')

haka.rule{
    hook = ipv4.events.receive_packet,
    eval = haka.interactive_rule("my_interactive_rule_on_ip")
}

It is strongly recommended to use interactive rules on pcap. If you try to use it on real traffic and if you are not fast enough you will encounter lots of retransmit packets.

info  core: load module 'packet/pcap.ho', Pcap Module
info  core: load module 'alert/file.ho', File alert
info  core: setting packet mode to pass-through

info  core: loading rule file 'sample.lua'
info  core: initializing thread 0
info  dissector: register new dissector 'raw'
info  pcap:      opening file '/usr/share/haka/sample/smtp_dissector/smtp.pcap'
info  dissector: register new dissector 'ipv4'
info  core:       1 rule(s) on event 'ipv4:receive_packet'
info  core:       1 rule(s) registered

info  core:      starting single threaded processing

interactive rule:
inputs = table {
  1 : userdata ipv4 {
    checksum : 58353
    dst : userdata addr 192.168.20.1
    flags : userdata ipv4_flags
    frag_offset : 0
    hdr_len : 20
    id : 47214
    len : 60
    name : "ipv4"
    payload : userdata vbuffer
    proto : 6
    raw : userdata packet
    src : userdata addr 192.168.10.10
    tos : 0
    ttl : 63
    version : 4
  }
}

Hit ^D to end the interactive session
my_interactive_rule_on_ip>

Once you have your prompt you can simply use the inputs variable to see what kind of arguments is passed to your evaluation function.

my_interactive_rule_on_ip> inputs[1].ttl
  #1    64
my_interactive_rule_on_ip>

Note

You can use tab to auto-complete your commands