Writting LUA script 'User Manual' with ROBODoc

I've wrote a script using LUA for wireshark.
Now I need to document it, so I won't forget what I wrote when I'll come back to the code, 2-6 months later.

After a short research I've found this very nice documentation tool:

ROBODoc 4.99.40 User Manual

and here is an example config file (you'll need it later) I wrote (modified from this source: http://qe-forge.org/cgi-bin/cvstrac/q-e/fileview?f=espresso/GUI/Guib/doc/robodoc.rc&v=1.3)...

options:
    --src ../
    --doc ./api/printable/TBD-api
    --internal
    --html
    --singledoc
    --sections
    --toc
    --tabsize 4
    --index
    --nopre
    --documenttitle "TBD --  To Be Defined."
    --sectionnameonly
    --syntaxcolors_enable quotes,line_comments,block_comments,keywords,non_alpha

accept files:
 *.lua

ignore files:
 .svn
 doc

headertypes:
 e "Enums"    robo_sections

ignore items:

item order:
    FUNCTION
    SYNOPSIS
    INPUTS
    RETURN VALUE
source items:
    SYNOPSIS
    
header markers:
    --****
remark markers:
    --
end markers:
    --****
    
remark begin markers:
    --
remark end markers:
    --

keywords:
 and       
 break     
 do        
 else      
 elseif
 end       
 false     
 for       
 function  
 if
 in        
 local     
 nil       
 not       
 or
 repeat    
 return    
 then      
 true      
 until     
 while

source line comments:
       --
   

GUIDE: Create your own free, cross platform binary log file with a viewer, with ease.

Hi, it can be done, and within days. Let's start...

Introduction
Did your boss just came to your office and asked you to dump stuff from the application to sniff what's going on in component #42?

Later on he'll might come and ask statistics, that it should support UNIX/Window/MAC/... , filtering, simple graphs, flow graph ...

Here are some pictures of these features in action:

I've wrote a tutorial to create a very simple (starter) sniffer. 

You can read more here... http://shloemi.blogspot.com/2011/05/guide-creating-your-own-fast-wireshark.html

GUIDE: LUA unit testing and TDD

I've just uncovered this subject, here is my insights:

Fast start

1. Open LUA
2. Start a new test file (let's call it 'my_code.tests.lua').
3. Edit 'my_code.tests.lua' (example template below)

--- my_code.tests.lua Code --------------------------------------------

-- Some super function to test
function my_super_function( arg1, arg2 ) return arg1 + arg2 end

-- Unit testing starts
require('luaunit')

TestMyStuff = {} --class
    function TestMyStuff:testWithNumbers()
        a = 1
        b = 2
        result = my_super_function( a, b )
        assertEquals( type(result), 'number' )
        assertEquals( result, 3 )
    end

    function TestMyStuff:testWithRealNumbers()
        a = 1.1
        b = 2.2
        result = my_super_function( a, b )
        assertEquals( type(result), 'number' )
        -- I would like the result to be always rounded to an integer
        -- but it won't work with my simple implementation
        -- thus, the test will fail
        assertEquals( result, 3 )
    end

-- class TestMyStuff

luaUnit:run()

--- Code End -----------------------------------------------------------------------

Execute the test code.
Add your tests and assumption checking.
Fix what's broken.

Understand more

• http://phil.freehackers.org/programs/luaunit/
• http://lua-users.org/wiki/UnitTesting

LUA tutorial / newbie, nob getting started and advanced links.

NOB? here you go:

Fast start

• Download 'LUA For Windows' - A batteries included Lua installation on Windows.
• http://code.google.com/p/luaforwindows/downloads/list
• Write code in an online interpreter
• http://www.lua.org/cgi-bin/demo

Know your LUA

• http://en.wikipedia.org/wiki/Lua_(programming_language)

Reference cards

• Lua 5.1 Reference Manual
• http://www.tdistler.com/media/docs/luarefv51.pdf
• http://lua-users.org/wiki/
• http://www.lua.org/manual/5.1/

A bit more advanced stuff

• Dynamic invocation
• http://stackoverflow.com/questions/1791234/lua-call-function-from-a-string-with-function-name
• http://en.wikipedia.org/wiki/Eval#Lua
• BitwiseOperators
• http://lua-users.org/wiki/BitwiseOperators
• Recommended - http://bitop.luajit.org/
• Notes - Problems with unsigned numbers detected!

Integrating LUA with Eclipse

• http://lunareclipse.sourceforge.net/
• Download - http://sourceforge.net/projects/lunareclipse/

Hope this helps.

GUIDE: Creating your own fast Wireshark plugin / dissector using LUA.

After hitting my head agains the keyboard to create my own LUA protocol, I've desided that none shall suffer anymore.

Some background to understand stuff

• Wireshark reads PCAP file format for captured files.
• Wireshark can be extended using C code or, for fast development you can use LUA code (I'll explain later...).

• PCAP File Format

• Development/LibpcapFileFormat - The Wireshark Wiki
• Know your Wireshark
• http://www.wireshark.org/docs/

Creating LUA based plugin / dissector

1. Download and install Wireshark.
2. Create LUA dissector (let's save it as 'trivial.lua')

-- trivial protocol example
-- declare our protocol
trivial_proto = Proto("trivial","Trivial Protocol")
-- create a function to dissect it
function trivial_proto.dissector(buffer,pinfo,tree)
    pinfo.cols.protocol = "TRIVIAL"
    local subtree = tree:add(trivial_proto,buffer(),"Trivial Protocol Data")
    subtree:add(buffer(0,2),"The first two bytes: " .. buffer(0,2):uint())
    subtree = subtree:add(buffer(2,2),"The next two bytes")
    subtree:add(buffer(2,1),"The 3rd byte: " .. buffer(2,1):uint())
    subtree:add(buffer(3,1),"The 4th byte: " .. buffer(3,1):uint())
end
-- load the udp.port table
udp_table = DissectorTable.get("udp.port")
-- register our protocol to handle udp port 7777
udp_table:add(7777,trivial_proto)

1. Edit  ...\Wireshark\init.lua file as follows
1. disable_lua = false
2. At the end of the file: dofile("trivial.lua") 
1. You can read more here - http://simplestcodings.com/2011/01/09/how-to-use-lua-to-create-wireshark-dissector/
2. Open Wireshark
1. Menu >> Edit >> Preferences >> Protocols >> DLT_USER >> Edit >> New:
1. DLT: User 0 (147)
2. Payload protocol: MyProtocolName
3. Header size 0
4. Trailer size: 0
5. Press OK
3. Create PCAP dumps for analyze.
1. Using HEX-Editor (see below for nice hex-editor recomendations).
2. If you can - ask the protocol team to provide their dumps. 
4. Open the PCAP dump for editing (binary mode).
1. Change the dump's 'Global Header' section / 'data link type' (network) to 147 (LINKTYPE_USER0)
1. Read more here - http://www.tcpdump.org/linktypes.html
2. save it.
5. Load the dump to Wireshark for analyses.
6. Start changing the trivial.lua code to parse your protocol.

Hope this will bring you to a working point fast. In the process read related stuff to understand more, you can upgrade this solution to create better and better protocol sniffer using Wireshark.

• Related reference stuff
• http://simplestcodings.com/2011/01/09/how-to-use-lua-to-create-wireshark-dissector/
• http://delog.wordpress.com/2010/09/27/create-a-wireshark-dissector-in-lua/
• http://lua-users.org/wiki/TutorialDirectory
• http://wiki.wireshark.org/Lua
• http://wiki.wireshark.org/Lua/Dissectors
• http://wiki.wireshark.org/Lua/Examples

More nice stuff that can help

• You can use 'Hex Workshop' to simulate your protocol binary streams more easily (using it's feature Structure Editing).
• http://www.hexworkshop.com/screen_shots.html
• Wireshark tools
• http://wiki.wireshark.org/Tools
• bit-twist: Network Traffic Generator 
• http://www.blindhog.net/bit-twist-network-traffic-generator-and-editor-2/
• http://bittwist.sourceforge.net/