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