Fork me on GitHub
security, tutorial, v0.1

Haka Debugger v0.1

Haka is featured with debugging capabilities allowing to inspect an existing Haka script file. With this mode activated (--luadebug option), a prompt will be displayed to the user inviting him to identify the faulty code.

The general syntax of the debugger is close to the syntax of gdb. For instance, the user can list the source code (l), set breakpoints (b), follow code execution (step (s), next (n), finish (f)) or dump the content of variables such as packet structure.

As you will notice, haka will generate an error if we run the following script. More precisely, Haka will complain about an unknown destport field.

require('protocol/ipv4')
require('protocol/tcp')

haka.rule{
    hooks = { 'tcp-up' },
    eval = function (self, pkt)
        if pkt.destport == 80 or pkt.srcport == 80 then
            haka.log("Filter", "Authorizing trafic on port 80")
        else
            haka.log("Filter", "Trafic not authorized on port %d", pkt.dstport)
            pkt:drop()
        end
    end
}

If we run again the above script with debugging facilities, Haka will break on the faulty source code and output a backtrace.

entering debugger: unknown field 'destport'
thread: 0
Backtrace
 =>0    [C]: in function '(null)'
  #1    [C]: in function '(null)'
  #2    [C]: in function '__index'
  #3    debug.lua:7: in function 'eval'
  #4    /opt/haka/share/haka/core/rule.bc:0: in the main chunk
  #5    /opt/haka/share/haka/core/rule.bc:0: in the main chunk
  #6    /opt/haka/share/haka/core/rule.bc:0: in the main chunk
  #7    [C]: in function 'xpcall'
  #8    /opt/haka/share/haka/core/rule.bc:0: in the main chunk
[C]
debug>

Here, we are interested in the third frame which is the one in the Lua script itself. We switch to that particular frame by entering the command frame 3. At this point, we can list the source code (list command) to get the exact line which caused the error (line 7).

debug>  frame 3
  #3    debug.lua:7: in function 'eval'
debug>  list
   2:  require('protocol/tcp')
   3: 
   4:  haka.rule{
   5:      hooks = { 'tcp-up' },
   6:      eval = function (self, pkt)
   7=>         if pkt.destport == 80 or pkt.srcport == 80 then
   8:              haka.log("Filter", "Authorizing trafic on port 80")
   9:          else
  10:              haka.log("Filter", "Trafic not authorized on port %d", pkt.dstport)
  11:              pkt:drop()
  12:          end
debug>

Then, if we dump the packet content (print pkt), we can see that we misspelled the dstport field. Once this typo is corrected, the script will run properly.

debug>  print pkt
  #1    userdata tcp {
checksum : 417
res : 0
next_dissector : "tcp-connection"
srcport : 37542
payload : userdata tcp_payload
ip : userdata ipv4 {
	...
}

flags : userdata tcp_flags {
	...
}

ack_seq : 0
seq : 38227050607
dstport : 80
hdr_len : 40
}
debug>

Note that we can get the list of available debugging commands by typing help.