use Cflow;
Cflow::verbose(1); Cflow::find(\&wanted, <*.flows*>);
sub wanted { ... }
or:
Cflow::find(\&wanted, \&perfile, <*.flows*>);
sub perfile { my $fname = shift; ... }
It was originally conceived and written for use by FlowScan:
http://net.doit.wisc.edu/~plonka/FlowScan/
http://www.splintered.net/sw/flow-tools/
http://www.caida.org/tools/measurement/cflowd/ http://net.doit.wisc.edu/~plonka/cflowd/
http://www.nmops.org/
wanted()
function once per flow record. If the
file name argument passed to find()
is specified as ``-'',
flows will be read from standard input.
The wanted()
function does whatever you write it to do. For
instance, it could simply print interesting flows or it might maintain
byte, packet, and flow counters which could be written to a database after
the find subroutine completes.
Within your wanted()
function, tests on the ``current'' flow
can be performed using the following variables:
strftime(3)
format:
%Y/%m/%d %H:%M:%S
Undefined if the current flow is not an ICMP flow.
Undefined if the current flow is not an ICMP flow.
The value is a the type-specific ICMP code, if any, followed by the ICMP type. E.g.
ECHO HOST_UNREACH
Undefined if the current flow is not an ICMP flow.
This will be zero unless used with flow-tools.
This will be zero unless used with flow-tools.
PUSH|SYN|FIN|ACK
Undefined if the current flow is not a TCP flow.
This is useful when the ``wanted'' subroutine wants to write the flow to another FILEHANDLE. E.g.:
syswrite(FILEHANDLE, $Cflow::raw, length $Cflow::raw)
This is useful when the ``wanted'' subroutine wants to write a modified flow to another FILEHANDLE. E.g.:
$srcaddr = my_encode($srcaddr); $dstaddr = my_encode($dstaddr); syswrite(FILEHANDLE, $Cflow::reraw, length $Cflow::raw)
These flow variables are packed into $Cflow::reraw:
$Cflow::index, $Cflow::exporter, $Cflow::srcaddr, $Cflow::dstaddr, $Cflow::input_if, $Cflow::output_if, $Cflow::srcport, $Cflow::dstport, $Cflow::pkts, $Cflow::bytes, $Cflow::nexthop, $Cflow::startime, $Cflow::endtime, $Cflow::protocol, $Cflow::tos, $Cflow::src_as, $Cflow::dst_as, $Cflow::src_mask, $Cflow::dst_mask, $Cflow::tcp_flags, $Cflow::engine_type, $Cflow::engine_id
perfile()
function can be passed
to Cflow::find as the argument following the reference to the
wanted()
function. This perfile()
function will
be called once for each flow file. The argument to the
perfile()
function will be name of the flow file which is
about to be processed. The purpose of the perfile()
function
is to allow you to periodically report the progress of Cflow::find() and to
provide an opportunity to periodically reclaim storage used by data objects
that may have been allocated or maintained by the wanted()
function. For instance, when counting the number of active hosts IP
addresses in each time-stamped flow file, perfile()
can reset
the counter to zero and clear the search tree or hash used to remember
those IP addresses.
Since Cflow is an Exporter, you can request that all those scalar flow variables be exported (so that you need not use the ``Cflow::'' prefix):
use Cflow qw(:flowvars);
Also, you can request that the symbolic names for the TCP flags, ICMP types, and/or ICMP codes be exported:
use Cflow qw(:tcpflags :icmptypes :icmpcodes);
The tcpflags are:
$TH_FIN $TH_SYN $TH_RST $TH_PUSH $TH_ACK $TH_URG
The icmptypes are:
$ICMP_ECHOREPLY $ICMP_DEST_UNREACH $ICMP_SOURCE_QUENCH $ICMP_REDIRECT $ICMP_ECHO $ICMP_TIME_EXCEEDED $ICMP_PARAMETERPROB $ICMP_TIMESTAMP $ICMP_TIMESTAMPREPLY $ICMP_INFO_REQUEST $ICMP_INFO_REPLY $ICMP_ADDRESS $ICMP_ADDRESSREPLY
The icmpcodes are:
$ICMP_NET_UNREACH $ICMP_HOST_UNREACH $ICMP_PROT_UNREACH $ICMP_PORT_UNREACH $ICMP_FRAG_NEEDED $ICMP_SR_FAILED $ICMP_NET_UNKNOWN $ICMP_HOST_UNKNOWN $ICMP_HOST_ISOLATED $ICMP_NET_ANO $ICMP_HOST_ANO $ICMP_NET_UNR_TOS $ICMP_HOST_UNR_TOS $ICMP_PKT_FILTERED $ICMP_PREC_VIOLATION $ICMP_PREC_CUTOFF $ICMP_UNREACH $ICMP_REDIR_NET $ICMP_REDIR_HOST $ICMP_REDIR_NETTOS $ICMP_REDIR_HOSTTOS $ICMP_EXC_TTL $ICMP_EXC_FRAGTIME
Please note that the names above are not necessarily exactly the same as the names of the flags, types, and codes as set in the values of the aforemented $Cflow::TCPFlags and $Cflow::ICMPTypeCode flow variables.
Lastly, as is usually the case for modules, the subroutine names can be imported, and a minimum version of Cflow can be specified:
use Cflow qw(:flowvars find verbose 1.031);
Cflow::find() returns a ``hit-ratio''. This hit-ratio is a string formatted
similarly to that of the value of a perl hash when taken in a scalar
context. This hit-ratio indicates ((# of ``wanted'' flows) / (# of scanned
flows)). A flow is considered to have been ``wanted'' if your
wanted()
function returns non-zero.
Cflow::verbose() takes a single scalar boolean argument which indicates whether or not you wish warning messages to be generated to STDERR when ``problems'' occur. Verbose mode is set by default.
use Cflow qw(:flowvars find);
my $udp = getprotobyname('udp'); verbose(0); find(\&wanted, @ARGV? @ARGV : <*.flows*>);
sub wanted { return if ($srcport < 1024 || $dstport < 1024); return unless (($srcport == 31337 || $dstport == 31337) && $udp == $protocol);
printf("%s %15.15s.%-5hu %15.15s.%-5hu %2hu %10u %10u\n", $localtime, $srcip, $srcport, $dstip, $dstport, $protocol, $pkts, $bytes) }
Here's an example which demonstrates a technique which can be used to pass
arbitrary arguments to your wanted function by passing a reference to an
anonymous subroutine as the wanted()
function argument to
Cflow::find():
sub wanted { my @params = @_; # ... }
Cflow::find(sub { wanted(@params) }, @files);
When built with support for flow-tools and attempting to read a cflowd format raw flow file from standard input, you'll get the error:
open "-": No such file or directory
For the time being, the workaround is to write the content to a file and read it from directly from there rather than from standard input. (This happens because we can't close and re-open file descriptor zero after determining that the content was not in flow-tools format.)
When built with support for flow-tools and using verbose mode, Cflow::find will generate warnings if you process a cflowd format raw flow file. This happens because it will first attempt to open the file as a flow-tools format raw flow file (which will produce a warning message), and then revert to handling it as cflowd format raw flow file.
The $Cflow::raw flow variable contains the flow record in cflowd format,
even if it was read from a raw flow file produced by flow-tools. Because
cflowd discards the fractional portion of the flow start and end time, only
the whole seconds portion of these times will be retained. (That is, the
raw record in $Cflow::raw does not contain the $start_msecs
and $end_msecs.)
When used with cflowd, Cflow::find() will generate warnings if the flow data file is ``invalid'' as far as its concerned. To avoid this, you must be using Cisco version 5 flow-export and configure cflowd so that it saves all flow-export data. This is the default behavior when cflowd produces time-stamped raw flow files after being patched as described here:
http://net.doit.wisc.edu/~plonka/cflowd/
Copyright (C) 1998-2001 Dave Plonka. 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; either version 2 of the License, or (at your option) any later version.
This is so that revision 1.10 (which is version 1.010), for example, will test greater than revision 1.2 (which is version 1.002) when you want to require a minimum version of this module.
perl(1),
Socket, Net::Netmask, Net::Patricia.