NAME

Net::Ncap - Perl extension for the ncap(3) network data capture library.

SYNOPSIS

  use Net::Ncap;
  use Net::DNS::Packet;
  use FileHandle;

  # output file
  my $fh = FileHandle->new('swag.ncap', '>');

  # create ncap object
  my $nc = Net::Ncap->new;

  # add a filter specification
  $ncap->filter('dns');

  # add a network interface for live listening
  $ncap->add_if(shift || 'eth0');

  # define the callback
  sub cb {
    my $m = shift;

    # save to ncap file
    $ncap->write($m, $fh);

    # example of parsing packet
    my $pkt = Net::DNS::Packet->new($m->payload_ref) || return;
    my $q = ($pkt->question)[0];
    my @answers = $pkt->answer;
    print join(',',
      $m->sec,   $m->nsec,
      $m->sip,   $m->dip,
      $m->sport, $m->dport,
      $q->qtype, $q->qname,
      @answers ? join(' -- ', map { $_->string } @answers) : ()
    ), "\n";
  }

  # collect the data
  $nc->collect(\&cb);

DESCRIPTION

Net::Ncap is a Perl binding to the ncap(3) network data capture library. The ncap documentation describes itself thusly:

      The ncap library is a high level interface for network
      data capture. The source of network data can be either
      live traffic or files containing previously captured or
      generated data. Files can be in ncap format or in pcap(3)
      format, and can be either normal binary files or network
      sockets.

CONSTRUCTOR

new([maxmsg])

Creates a new Net::Ncap object. Methods are dispatched to their corresponding functions provided by the ncap library.

The optional parameter maxmsg determines the maximum size of an ncap payload that the library is willing to process (default 70000).

METHODS

The following methods, for the most part, directly correspond to the functions provided by the ncap library. See ncap(3) for more details on what these functions do.

add_if($name, [$bpf], [$promisc], [$vlans])

Adds a network interface as a data source. The name of the interface is required (e.g. 'eth0'). A BPF program can be provided as a string with the bpf parameter (unless an NCAP filter has been provided via the filter() method). promisc determines whether or not the interface is opened in promiscuous mode (default 0). An optional array refererence to VLANs may also be provided for filtering based on tagged 802.1Q frames.

drop_if($name)

Removes the given network interface from the collection pool.

add_nf($file, [$label])

Adds the given NCAP file as a data source. If file is a reference, it is assumed to be an open file handle and is used directly. Otherwise it is assumed to be a file name and is opened for reading. An optional label can be provided for this source; by default the label is either the filename or file number, depending on what was provided in file.

drop_nf($file)

Removes the given NCAP file as a data source. The provided file can either be the file name, handle, or label (if one was provided).

add_pf($file, [$label])

Adds the given PCAP file as a data source. file can either be a file name or a file handle. Otherwise identical to add_nf(), including accepting an optional label.

drop_pf($file)

Removes the given PCAP file as a data source. The provided file can either be the file name, handle, or label (if one was provided).

add_dg($socket)

Adds the given socket handle as a data source.

drop_dg($socket)

Removes the given socket handle as a data source.

filter($filter)

Installs an NCAP filter described by the given string. If any BPFs (berkely packet filters) have been installed, this will fail.

collect($callback, [%opts])

Collect data from the collection pool, invoking the subroutine referenced by callback for each matching ncap message. There are several named options available:

polling

Controls whether collection happens continuously (the default) or once.

sigwrap

Disabled by default. Controls whether signal handlers are installed for SIGHUP, SIGINT, and SIGTERM prior to passing control to the collection loop. Perl only sees these events when it is in context (i.e. during the callback). Until then they are queued by default, until perl can handle them. If you are polling on an interface that is not very busy, or if your filters only occasionally pass an interesting message, it might be a while before perl gets a chance to handle signals. With this option enabled, the program is interruptable. Whatever signal handlers were in place prior to invoking collect are restored once complete.

timeout

Disabled by default. Specifies a time window for which your callback will be invoked, regardless of whether any messages have matched your filters. In such a case, the message provided to the callback will be undef. Enabling timeout automatically enables sigwrap as described above.

timeout_cb

Specifies an optional alternate callback reference for timeout induced callbacks, rather than sending undef to the primary callback.

stop()

Halts the collection loop. There might be a few stray callbacks before the loop actually exits, depending on the granularity configured into the ncap library.

write($fh, [$msg])

Writes the given ncap message to the provided file handle in the ncap portable binary format. If no message is provided, a proper file header is written instead.

send($socket, [$msg, $flags])

Writes the given ncap message to the provided socket handle in the ncap portable binary format. If no Net::Ncap::ncap_msg object is provided, an NCAP file header is written instead. <em>flags<em> are an integer representation of any flags as would be provided to the send(2) function from the socket library (default MSG_DONTROUTE).

CALLBACK

callback($msg)

The callback function is handed a single parameter, a reference to a message object. See below for more information. If collection was invoked with either sigwrap or timeout enabled, the callback might be invoked with undef, depending on whether timeout_cb was provided.

The callback can abort the collection loop by invoking the stop() method on the Net::Ncap object.

MESSAGE OBJECTS

The callback receives references to Net::Ncap::ncap_msg objects. The following accessors, for the most part, correspond to the the information available from the structs comprising an ncap message. See ncap(3) for more information on the low level format.

label()

The label associated with this data source. By default this will be the file name or interface name, unless an alternate label was associated with the source.

src_packed()

The source IP address in packed (network byte order) form. (i.e. either either a ip_addr or ip6_addr struct).

dst_packed()

The destination IP address in packed (network byte order) form.

src()

Returns an array reference containing the components of the source IP address. For IPv4 these represent the four 32 bit quads, for IPv6 these represent the eight 16-bit components.

dst()

Returns an array reference containing the components of the destination IP address, as above.

sip()

The source IP address as a string. For IPv4 this is dotted-quad, for IPv6 this is colon-hexadecimal.

dip()

The destination IP address as a string, as above.

sport()

The source port of the datagram. (undef for icmp)

dport()

The destination port of the datagram. (undef for icmp)

sec()

The seconds component of the datagram timestamp.

nsec()

The nanoseconds component of the datagram timestamp.

nproto()

The numeric network protocol type (IP or IPV6)

tproto()

The numeric transport protocol type (UDP, TCP, or ICMP)

nname()

The network protocol name

tname()

The transport protocol name

payload()

The binary (network format) record (for example, the DNS record)

payload_ref()

A scalar reference to the payload string.

user1()

User defined value

user2()

User defined value

type()

The ICMP type of the datagram. (undef for udp/tcp)

code()

The ICMP code of the datagram. (undef for udp/tcp)

offset()

The TCP offset of the datagram. (undef for icmp/udp)

flags()

The TCP flags of the datagram. (undef for icmp/udp)

SEE ALSO

ncap(3), pcap(3), Net::Pcap

The Net::Ncap project page: http://tools.netsa.cert.org/wiki/display/tt/Net-Ncap

The ncap library can be downloaded from: ftp://ftp.isc.org/isc/ncap/

The pcap library can be downloaded from: http://www.tcpdump.org/

AUTHOR

Matthew Sisk, <sisk@cert.org>

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Carnegie Mellon University

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, as published by the Free Software Foundation, under the terms pursuant to Version 2, June 1991.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.