capdiss

Announcements

2016-08-28 — Version 0.3.1 released.

2016-08-26 — Version 0.3.0 released.

2015-06-29 — Version 0.2.1 released.

2015-06-26 — Version 0.2.0 released.

2015-06-18 — Version 0.1.0 released.

Description

Capdiss is a runtime environment for reading capture files (pcap, pcap-ng). It defines a simple event-driven API for Lua scripts. The aim of capdiss is to provide a comfortable environment for packet manipulation, where an analyst has to write less code, to do more, in a type-safe language. To achieve that, capdiss embeds powerful, yet minimalistic, scripting language Lua, and supports the native packet dissection framework Coroner.

Capdiss is a free software licensed under MIT License.

Usage

Usage: capdiss <options> <script-name> [args ...]

Options:
 -f, --file=<pcap-file>    read network frames from a file
 -F, --filter=<filter>     apply packet filter before reading from a file
 -v, --version             show version information
 -h, --help                show usage information

A common use consists of providing a file from which to read captured network frames, using option -f, --file, and one Lua script. Lua script can be provided either as a path to a file (i.e. ./luascripts/myscript.lua) or as a module name (i.e. mymodule).

$ capdiss -f tftp.pcap print

If a module name is passed, the name is resolved to a full-path using the Lua's built-in function require. Custom paths, where to look for a module, can be added to the list via environment variable LUA_PATH.

Packet filters

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 module. BPF has relatively simple syntax and you can cover most of the cases on this level without having to program the rules in your script. This reference page is a good start to get familiar with the syntax.

$ capdiss -f local_net-eth0.pcap -F "broadcast or ip host 192.168.1.69" print

Live capture

Live capture is not supported but you can simulate the behavior by replacing the name of a capture file with -, this tells capdiss to read data from standard input (stdin). Then you can use tcpdump to pipe data to capdiss.

$ tcpdump -w - | capdiss -f - print

Installation

GNU/Linux (Debian derivates)

# Install the software dependencies...
$ sudo apt-get install libpcap-dev liblua5.2-dev

# Download the source code...
$ wget https://codeward.org/software/capdiss/files/capdiss-0.3.1.tar.gz

# Extract content of the tarball...
$ tar xzf capdiss-0.3.1.tar.gz

# Change current working directory to newly extracted directory...
$ cd capdiss-0.3.1/

# Compile the source code...
$ make

# Install the compiled binary...
$ sudo make install

Windows

The source code is portable to Windows. It can be compiled using the MinGW suite. Just make sure the path to utilities make and mingw32-gcc is referenced in the %PATH% variable.

On Windows, Lua is linked statically to the executable. All the neccessary files are already in the source tree. Only dependency that needs to be installed are runtime files for WinPcap npcap [WinPcap is still a good choice if you are running XP's].

mingw32-make CC=mingw32-gcc -f Makefile.win

Please note, that this software HAS NOT been tested on Windows, apart from the compilation! Chances are, the software is full of odd bugs.

User modules

The official repository lists a selection of user modules. To install the modules, run the command:

$ sudo luarocks install capdiss-mods-all

To see which modules are bundled in:

$ capdiss modlist

To see information about a specific module:

$ capdiss modinfo modinfo

Download

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