.\" $$Id$
.\" 
.\" Copyright (c) 2004 Jose Nazario <jose@monkey.org>
.\" 
.\" Covered under a 3-clause BSD license. All rights reserved.
.\"
.Dd 13 December, 2004
.Dt FLOWGREP 8
.Os
.Sh NAME
.Nm flowgrep
.Nd TCP stream/UDP/IP payload 'grep' utility
.Sh SYNOPSIS
.Nm
.Op Fl ikVvx
.Op Fl a Ar pattern
.Op Fl c Ar pattern
.Op Fl D Ar num
.Op Fl d Ar device
.Op Fl E Ar name
.Op Fl e Ar string
.Op Fl F Ar pattern_file
.Op Fl f Ar pattern_file
.Op Fl l Ar dir
.Op Fl r Ar filename
.Op Fl s Ar pattern
.Op Fl u Ar username
.Op Ar filter
.Sh DESCRIPTION
.Nm
is a small tool to look for arbitrary payload content in TCP streams
or UDP packets. This search parameter is described as a regular expression
using the format described in 
.Xr re_format 7 .
The 
.Fl s
flag indicates that the 
.Ar pattern 
should be looked for only in the server's data stream (sent from the server 
to the client). These patterns can also be loaded from the
.Ar pattern_file
specified using the 
.Fl F
flag, with each pattern separated by a newline. Newlines are not considered 
part of a pattern. The
.Fl c
flag indicates that the 
.Ar pattern 
should only match data sent by the client
to the server. These patterns can also be loaded from the 
.Ar pattern_file
specified using the
.Fl f
flag, with each line containing one pattern to match. These newlines are not
considered part of the pattern. The
.Fl a
flag indicates any matching stream should be matched. For UDP and IP payloads
these three flags are equivilent. Multiple expressions can be searched
for by successive calls to the appropriate 
.Fl a ,
.Fl c
or 
.Fl s
flag. 
.Pp
An optional
.Xr pcap 3
.Ar filter 
can be specified to limit what data to monitor. TCP, UDP, and IP
connections are evaluated. Fragments are reassembled according to their
parent connection.
.Pp
.Nm
drops privileges after initialization and runs as the user specified using
the 
.Fl u
flag or the user 'nobody' by default.
.Pp
If 
.Fl v
is specified, the match is inverted and non-matching flows are logged
or killed. The 
.Fl i
flag specifies a case insensitive search.
.Pp
Packets are captured on the first appropriate device unless the 
.Fl d
flag is specified, in which case 
.Ar device
is used to capture packets. The input can also be a filename if
.Fl r
is used. The 
.Ar filename
must be in 
.Xr pcap 3
format.
.Pp
If the
.Fl k
option is used, the matching TCP connection will be killed by 
.Nm .
This is done by sending TCP RST packets to the two participants. TCP
connections can be both stored and killed.
.Pp
If the 
.Fl l
option is given, matched flows will be logged relative to the
.Ar dir
argument. Matched flows or packets are stored in files as the complete 
payload or reassembled TCP stream payload. The filename is based on the stream
data and is logged as 'time-source-sport-dest-dport-proto', with time as 
a 32 bit integer for seconds since the UNIX epoch. For protocols other than
TCP or UDP, the protocol is listed as 'protoN' where 'N' is the protocol
number. See 
.Xr protocols 5
for more information about these numbers and name. If the
.Fl x
argument is given, these filenames will be written to 
.Xr stdout 4
in a format suitable for use with
.Xr xargs 1
(ie for processing the flows). Flows are written out to the filesystem
upon the connection closure.
.Pp
.Nm
can also use
.Xr libdistance 3
for fuzzy string matching. Several algorithms are supported, including
the Levenshtein algorithm, Damerau method, Hamming distance and the
Jaccard distance. One or more strings may be given using the 
.Fl e
flag. If the distance calculated using the algorithms is below the value
specified by
.Fl D
a match has occured. Note that this approach is slow and not well tested
at this time.
.Pp
The 
.Fl V
flag causes 
.Nm
to print the version information and exit.
.Sh EXAMPLES
To capture all mail traffic over SMTP and log it relative to the local 
directory:
.Bd -ragged -offset indent
.Nm
-i -c "^ *mail +from" -l . tcp port 25
.Ed
.Pp
To capture all non-mail traffic on TCP port 25 and log it into the
directory
.Ar suspicious :
.Bd -ragged -offset indent
.Nm
-i -a "^ *mail +from" -v -l suspicious tcp port 25
.Ed
.Pp
To turn flowgrep into a simple TCP flow recorder:
.Bd -ragged -offset indent
.Nm
-a "." -l flow tcp
.Ed
.Pp
To kill Blaster worm infection attempts:
.Bd -ragged -offset indent
.Nm
-i -c "^ *tftp -i \\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3} GET msblast.exe" -k tcp port 4444
.Ed
.Pp
To stop successful web surfing on your segment:
.Bd -ragged -offset indent
.Nm
-s "HTTP/1.1 200 OK" -k tcp port 80
.Ed
.Pp
To detect and stop SSH usage on non-SSH ports:
.Bd -ragged -offset indent
.Nm
-i -a "ssh-" -k tcp not port 22
.Ed
.Pp
To detect non-HTTP use of port 80:
.Bd -ragged -offset indent
.Nm
-i -c "^GET *.+HTTP/1.[01]" -c "^POST *.+HTTP/1.[01]"  -c "^PUT *.+HTTP/1.[01]" -l suspicious -v tcp port 80
.Ed
.Pp
Detect Viagra spam on TCP port 25:
.Bd -ragged -offset indent
.Nm
-E levenshtein -D 5 -e Viagra -l spammers tcp port 25
.Ed
.Sh SEE ALSO
.Xr pcap 3 ,
.Xr libdistance 3 ,
.Xr re_format 7 ,
.Xr tcpkill 8 ,
.Xr ngrep 8 ,
.Xr tcpflow 8
.Sh AUTHOR
Jose Nazario
.Pq jose@monkey.org
.Sh BUGS
Using 
.Nm
as a IPS to enforce policies against tunnelling (ie using TCP port 80 for
SSH access) can be easily fooled if the tunnel wrapper adds basic
protocol headers to the connections. Use 
.Nm
for this purpose with caution.