NAME

Net::Sharktools - Use Wireshark's packet inspection capabilities in Perl

SYNOPSIS

use Net::Sharktools qw(perlshark_read);

my $frames = perlshark_read(
    filename => 'capture1.pcap',
    fieldnames => [qw( 
        frame.number 
        ip.version
        tcp.seq
        udp.dstport
        frame.len
    )],
    dfilter => 'ip.version eq 4'
    # optional decode_as
);

or

use Net::Sharktools qw(perlshark_read_xs);

my $frames = perlshark_read_xs(
    'capture1.pcap',
    [qw( 
        frame.number 
        ip.version
        tcp.seq
        udp.dstport
        frame.len
    )],
    'ip.version eq 4'
    # optional decode_as
);

DESCRIPTION

Net::Sharktools is an adaptation of the Python interface provided with the Sharktools package which is a "small set of tools that allow use of Wireshark's deep packet inspection capabilities in interpreted programming languages."

Sharktools can be obtained obtained Armen Babikyan's web site at http://www.mit.edu/~armenb/sharktools/. To use Net::Sharktools, you must first build the Sharktools C library successfully as described in the README for the Sharktools package (the version of this file bundled with Sharktools v.0.1.5 is included in this module for your reference).

Net::Sharktools is almost a direct translation of the Python interface pyshark included with Sharktools.

BUILD and INSTALLATION

Sharktools is closely coupled with the internals of Wireshark. Before attempting to build Net::Sharktools, you should ensure that you are able to build and run the Python module pyshark distributed with Sharktools. Note that you should use python2 to test pyshark.

The build process for Sharktools requires you to install Wireshark and also have the full source tree for Wireshark accessible. You will need the same to build Sharktools as well.

Currently, the Makefile.PL for Net::Sharktools makes no attempt to automatically deduce the locations for your WireShark and Sharktools distributions. You will need to provide that information.

You can do that by specifying command line options when you generate the Makefile:

perl Makefile.PL --PREFIX=/install/path \
    --sharktools-src /home/user/sharktools-0.1.5/src \
    --wireshark-src /home/user/shark/wireshark-1.4.3 \
    [ --lib-path /additional/library/paths ] \
    [ --inc-path /additional/include/paths ]

--inc-path and --lib-path are array valued options, so they can be specified multiple times on the command line.

You should definitely specify those (in addition to the Sharktools and Wireshark source directories) if you encounter any difficulties related to locating glib headers and/or glib and Wireshark libraries on your system.

I used Devel::CheckLib to perform a sanity check prior to WriteMakefile using a select few headers and libraries. If the checks fail, no Makefile will be generated. Ensure that you have the requisite libraries installed, make sure you have built Sharktools according to its instructions prior to attempting to build Net::Sharktools, and specified the correct paths when invoking Makefile.PL.

Once a Makefile is generated, you can do:

make
make test
make install

EXPORT

The module does not export any functions by default. You can request either perlshark_read which accepts arguments in a hash ref or as a flattened hash or perlshark_read_xs which expects positional arguments.

perlshark_read

You can either pass the arguments to this function in a hashref or as a flattened hash. The function does some argument checking and passes the arguments in the correct order to perlshark_read_xs which uses positional arguments.

The arguments are:

filename

The name of the capture file to be analyzed.

fieldnames

The names of the fields to be extracted.

dfilter

Filter expressions to apply.

decode_as

From Sharktools README:

Wireshark's packet dissection engine uses a combination of heuristics and convention to determine what dissector to use for a particular packet. For example, IP packets with TCP port 80 are, by default, parsed as HTTP packets. If you wish to have TCP port 800 packets parsed as HTTP packets, you need to tell the Wireshark engine your explicit intent.

Wireshark adds a "decode as" feature in its GUI that allows for users to specify this mapping (Analyze Menu -> Decode As...). Sharktools attempts to provide a basic interface to this feature as well. By adding a 4th (optional) argument to both the matshark and pyshark commands, a user can achieve the desired effect. For example, the following "decode as" string will parse TCP port 60000 packets as HTTP packets: 'tcp.port==60000,http

perlshark_read_xs

This is the XS routine. It expects 3 or 4 positional arguments.

perlshark_read_xs(
    $filename, 
    [qw( field1 ... fieldn )],
    $dfilter,
    $decode_as, # optional
);

SEE ALSO

Sharktools http://www.mit.edu/~armenb/sharktools/ and Wireshark http://www.wireshark.org.

ACKNOWLEDGEMENTS

The XS code is a straightforward translation of the Python interface provided in pyshark.c

AUTHOR

A. Sinan Unur, <nanis@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2011 by The Perl Review, LLC

This work was sponsored by brian d foy and The Perl Review.

This module is free software. You can redistribute it and/or modify it under the terms of GNU General Public License, version 2. See http://www.gnu.org/licenses/gpl-2.0.html

cpanm Net::Sharktools

perl -MCPAN -e shell
install Net::Sharktools