The last time Hackerfall tried to access this page, it returned a not found error. A cached version of the page is below, or click here to continue anyway

capdiss - Capture File Dissector



2015-06-29 — Version 0.2.1 released.

2015-06-26 — Version 0.2.0 released.

2015-06-18 — Version 0.1.0 released.


Capture file dissector with embedded Lua interpreter. With this tool an analyst has access to powerful scripting environment that can be used for endless variety of tasks, starting from simple packet inspection to building sophisticated data-driven programs. The usage of the tool is loosely based on principles of awk.

This software is free software licensed under MIT License.


From the source

  1. Download the source code.
  2. Extract the content of the archive.
  3. Change current directory to extracted directory.
  4. Run make install with root privileges.



Basic usage consists of providing a capture file <FILE> and at least one Lua script, provided either as a file with parameter -f or as a direct source code with option -e. The options can be used multiple times and in combinations.

Usage: capdiss <OPTIONS> <FILE>

 -e, --source='PROGTEXT'    load Lua script source code
 -f, --file=PROGFILE        load Lua script file
 -t, --filter='FILTERTEXT'  apply packet filter
 -v, --version              show version information
 -h, --help                 show usage information (this text)

Since version 0.2.0, capdiss supports Berkeley Packet Filters (BPF) which can help you filter out unwanted frames before being passed to a user script. BPF has relatively simple syntax and you can cover most of the cases on this level without programming the rules in your scripts. This reference page is a good start.

Live capture is not supported directly although you can simulate the behaviour replacing a name of capture file with -, this tells capdiss to read data from standard input. Then using tcpdump you can pipe the content to capdiss like so.

tcpdump -w - | capdiss -f script.lua -


To interact with a user script, capdiss looks for a definition of methods Capdiss.begin, Capdiss.each and Capdiss.finish. If any of these methods are found, they are executed.

As the name suggests, Capdiss.begin is executed first, before any frame is retrieved from the capture file. The method Capdiss.finish is executed last, after all the frames were retrieved from the capture file. The method Capdiss.each is executed in between these two methods for each frame retrieved from the capture file, and unlike the previous methods, it takes two parameters. First parameter is used to pass a timestamp of the frame when it was captured, second parameter is used to pass a frame data.

Example 1: Counting Frames

Following user script counts and enumerates all the frames inside of a capture file. Every frame is printed out along with its timestamp.

-- Capdiss script counting frames.
Capdiss = {}

local i

function Capdiss.begin ()
	-- Not much to do here, just initialize the counter variable
	i = 0
	print ("Begin parsing...")

function Capdiss.each (ts, frame)
	i = i + 1

	print (ts .. " :: pkt no. " .. i)

function Capdiss.finish ()
	print ("Done parsing ... " .. i .. " packets processed.")

Example 2: Dissecting Ethernet and IP headers

A packet dissection is alfa and omega for capdiss and for these purposes there are dissectors available, which you can use in your scripts. Please refer to this README for more information on dissectors, and how to use them. The example below uses Ethernet and IP dissectors to extract source and destination MAC addresses and their corresponding IP addresses in each frame.

-- Capdiss script parsing Eth and IP headers.
require "protocol/Eth"
require "protocol/Ip"

Capdiss = {}

function Capdiss.each (ts, frame)
	local eth = Eth.parse (frame)
	local ip = Ip.parse (frame:sub (eth.len ()))

	print (ts .. ": " .. ip.saddr .. " (" .. eth.src .. ") => " .. ip.daddr .. " (" .. eth.dst ..  ")")

User scripts

As a part of the capdiss project we are maintaining a repository of user scripts contributed to by the capdiss users. If you have a script that others may find useful, feel free to submit it as a pull request on github. If you have opted out from using github, you can contribute to the repository by sending an email to address [email protected] with the script in the attachment along with licensing information.

Scripts with obscure or non-free license will be rejected. Same goes for unlicensed heaps of code. If you are contributing by email, do not forget to include your name, otherwise Anonymous name will be assumed.


Latest changes and all version releases are always available in capdiss's git repository.

Continue reading on