ongrep

A cleaned up fork of ngrep for OpenBSD
git clone git://git.sgregoratto.me/ongrep
Log | Files | Refs | README | LICENSE

commit 42c380529ab622e3cbb2a63062ae230e7d70c42b
parent 96280273f5288d9d908a4e72fdaefe9f39535ac0
Author: Stephen Gregoratto <dev@sgregoratto.me>
Date:   Wed, 17 Jun 2020 14:59:04 +1000

Rewrite manpage in mdoc(7), remove bpf explanation

Since adequate explanations of bpf filter syntax can be found in both
tcpdump(5) and pcap-filter(5), we'll just link to them and let the user
sort it out. Because of this, remove the copyright for the filter
explanation.

Diffstat:
Mngrep.8 | 762+++++++++++++++++++++++++++-----------------------------------------------------
1 file changed, 254 insertions(+), 508 deletions(-)

diff --git a/ngrep.8 b/ngrep.8 @@ -1,516 +1,262 @@ -.\" All content, except portions of the bpf filter explanation, are: -.\" -.\" Copyright (c) 2017 Jordan Ritter <jpr5@darkridge.com> -.\" Copyright (c) 2020 Stephen Gregoratto <dev@sgregoratto.me> -.\" +.\" Copyright (c) 2017 Jordan Ritter <jpr5@darkridge.com> +.\" Copyright (c) 2020 Stephen Gregoratto <dev@sgregoratto.me> .\" Please refer to the LICENSE file for more information. - -.TH NGREP 8 "September 2017" *nux "User Manuals" - -.SH NAME - -ngrep \- network grep - -.SH SYNOPSIS - -.B ngrep <-hNXViwqpevxlDtTRM> <-IO -.I pcap_dump -.B > < -n -.I num -.B > < -d -.I dev -.B > < -A -.I num -.B > < -s -.I snaplen -.B > < -S -.I limitlen -.B > < -W -.I normal|byline|single|none -.B > < -c -.I cols -.B > < -P -.I char -.B > < -F -.I file -.B > < -.I match expression -.B > < -.I bpf filter -.B > - -.SH DESCRIPTION - -ngrep strives to provide most of GNU grep's common features, applying -them to the network layer. ngrep is a pcap-aware tool that will allow -you to specify extended regular expressions to match against data -payloads of packets. It currently recognizes TCP, UDP and ICMP across -Ethernet, PPP, SLIP, FDDI and null interfaces, and understands bpf -filter logic in the same fashion as more common packet sniffing tools, -such as -.BR tcpdump (8) +.Dd June 17, 2020 +.Dt NGREP 8 +.Os +.Sh NAME +.Nm ngrep +.Nd network packet search +.Sh SYNOPSIS +.Nm +.Op Fl DeilMNpqtTvwxX +.Op Fl A Ar num +.Op Fl c Ar cols +.Op Fl d Ar dev +.Op Fl F Ar file +.Op Fl I Ar pcap_dump +.Op Fl n Ar num +.Op Fl O Ar pcap_dump +.Op Fl P Ar char +.Op Fl S Ar limitlen +.Op Fl s Ar snaplen +.Op Fl W Cm normal | byline | single | none +.Op Ar expression +.Op Ar filter +.Sh DESCRIPTION +The +.Nm +utility prints out packets on a network interface that both match +.Ar expression and -.BR snoop (1). - - -.SH OPTIONS -.IP -h -Display help/usage information. - -.IP -N +.Ar filter . +You must have read-write access to +.Pa /dev/bpf . +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl A Ar num +Dump +.Ar num +packets of trailing context after matching a packet. +.It Fl c Ar cols +Explicitly set the console width to +.Ar cols . +Note that this is the console width, and not the full width of what +.Nm +prints out as payloads; depending on the output mode +.Nm +may print less than +.Ar cols +bytes per line for indentation. +.It Fl D +When reading pcap dump files, replay them at their recorded time +intervals (mimic realtime). +.It Fl d Ar dev +Listen on interface +.Ar dev . +If unspecified, +.Nm +will listen on the default system interface. +.It Fl e +Show empty packets. +Normally empty packets are discarded because they have no payload to search. +If specified, empty packets will be shown, +regardless of +.Ar expression . +.It Fl F Ar file +Read in the bpf filter from +.Ar file . +This is a compatibility option for users familiar with +.Xr tcpdump 8 . +Overrides the +.Ar filter +argument. +.It Fl i +Ignore case in +.Ar expression . +.It Fl I Ar pcap_dump +Input file +.Ar pcap_dump +into +.Nm . +Works with any pcap-compatible dump file format. +.It Fl l +Force output to be line buffered. +.It Fl M +Make +.Ar expression +match single lines. +.It Fl N Show sub-protocol number along with single-character identifier (useful when observing raw or unknown protocols). - -.IP -X -Treat the match expression as a hexadecimal string. See the -explanation of \fImatch expression\fP below. - -.IP -V -Display version information. - -.IP -i -Ignore case for the regex expression. - -.IP -w -Match the regex expression as a word. - -.IP -q -Be quiet; don't output any information other than packet headers and -their payloads (if relevant). - -.IP -p +.It Fl n Ar num +Match only +.Ar num +packets total, then exit. +.It Fl O Ar pcap_dump +Write matched packets to +.Ar pcap_dump +in a pcap-compatible dump format. +This feature does not interfere with normal output to standard output. +.It Fl p Don't put the interface into promiscuous mode. - -.IP -e -Show empty packets. Normally empty packets are discarded because they -have no payload to search. If specified, empty packets will be shown, -regardless of the specified regex expression. - -.IP -v -Invert the match; only display packets that don't match. - -.IP -x -Dump packet contents as hexadecimal as well as ASCII. - -.IP -l -Make stdout line buffered. - -.IP -D -When reading pcap_dump files, replay them at their recorded time -intervals (mimic realtime). - -.IP -t -Print a timestamp in the form of YYYY/MM/DD HH:MM:SS.UUUUUU everytime -a packet is matched. - -.IP -T -Print a timestamp in the form of +S.UUUUUU, indicating the delta -between packet matches. Specify a second time to indicate the delta -since the first packet match. - -.IP -R -Do not try to drop privileges to the DROPPRIVS_USER. - -ngrep makes no effort to validate input from live or offline sources -as it is focused more on performance and handling large amounts of -data than protocol correctness, which is most often a fair assumption -to make. However, sometimes it matters and thus as a rule ngrep will -try to be defensive and drop any root privileges it might have. - -There exist scenarios where this behaviour can become an obstacle, so -this option is provided to end-users who want to disable this feature, -but must do so with an understanding of the risks. Packets can be -randomly malformed or even specifically designed to overflow sniffers -and take control of them, and revoking root privileges is currently -the only risk mitigation ngrep employs against such an attack. Use -this option and turn it off at your own risk. - -.IP "-c cols" -Explicitly set the console width to ``cols''. Note that this is the -console width, and not the full width of what ngrep prints out as -payloads; depending on the output mode ngrep may print less than -``cols'' bytes per line (indentation). - -.IP "-F file" -Read in the bpf filter from the specified filename. This is a -compatibility option for users familiar with tcpdump. Please note -that specifying ``-F'' will override any bpf filter specified on the -command-line. - -.IP "-P char" -Specify an alternate character to signify non-printable characters -when displayed. The default is ``.''. - -.IP "-K num" -Kill matching TCP connections (like tcpkill). The numeric argument -controls how many RST segments are sent. - -.IP "-W normal|byline|single|none" -Specify an alternate manner for displaying packets, when not in -hexadecimal mode. The ``byline'' mode honors embedded linefeeds, -wrapping text only when a linefeed is encountered (useful for observing -HTTP transactions, for instance). The ``none'' mode doesn't wrap under -any circumstance (entire payload is displayed on one line). The -``single'' mode is conceptually the same as ``none'', except that -everything including IP and source/destination header information is all -on one line. ``normal'' is the default mode and is only included for -completeness. This option is incompatible with ``-x''. - -.IP "-s snaplen" -Set the bpf caplen to snaplen (default 65536). - -.IP "-S limitlen" -Set the upper limit on the size of packets that ngrep will look at. +.It Fl P Ar char +Use +.Ar char +to signify non-printable characters when displayed. +The default is a dot +.Pq Ql \&. . +.It Fl q +Don't output any information other than packet headers and +their payloads (if relevant). +.It Fl S Ar limitlen +Set the upper limit on the size of packets that +.Nm +will look at to +.Ar limitlen . Useful for looking at only the first N bytes of packets without changing the BPF snaplen. - -.IP "-I pcap_dump" -Input file pcap_dump into ngrep. Works with any pcap-compatible dump -file format. This option is useful for searching for a wide range of -different patterns over the same packet stream. - -.IP "-O pcap_dump" -Output matched packets to a pcap-compatible dump file. This feature -does not interfere with normal output to stdout. - -.IP "-n num" -Match only -.I \fInum\fP -packets total, then exit. - -.IP "-d dev" -By default ngrep will select a default interface to listen on. Use -this option to force ngrep to listen on interface \fIdev\fP. - -.IP "-A num" -Dump \fInum\fP packets of trailing context after matching a packet. - -.IP "\fI match expression\fP" -A match expression is either an extended regular expression, or if the -\fI-X\fP option is specified, a string signifying a hexadecimal value. -An extended regular expression follows the rules as implemented by the -.B GNU regex -.BR library . -Hexadecimal expressions can optionally be preceded by `0x'. E.g., -`DEADBEEF', `0xDEADBEEF'. - -.IP "\fI bpf filter\fP" -Selects a filter that specifies what packets will be dumped. If no -\fIbpf filter\fP is given, all IP packets seen on the selected -interface will be dumped. Otherwise, only packets for which \fIbpf -filter\fP is `true' will be dumped. -.LP -The \fIbpf filter\fP consists of one or more -.I primitives. -Primitives usually consist of an -.I id -(name or number) preceded by one or more qualifiers. There are three -different kinds of qualifier: -.IP \fItype\fP -qualifiers say what kind of thing the id name or number refers to. -Possible types are -.BR host , -.B net -and -.BR port . -E.g., `host blort', `net 1.2.3', `port 80'. If there is no type -qualifier, -.B host -is assumed. -.IP \fIdir\fP -qualifiers specify a particular transfer direction to and/or from -.I id. -Possible directions are -.BR src , -.BR dst , -.B "src or dst" -and -.B "src and" -.BR dst . -E.g., `src foo', `dst net 1.2.3', `src or dst port ftp-data'. If -there is no dir qualifier, -.B "src or dst" -is assumed. -For `null' link layers (i.e. point to point protocols such as slip) the -.B inbound -and -.B outbound -qualifiers can be used to specify a desired direction. -.IP \fIproto\fP -qualifiers are restricted to ip-only protocols. Possible protos are: -.B tcp , -.B udp -and -.BR icmp . -e.g., `udp src foo' or `tcp port 21'. If there is no proto qualifier, -all protocols consistent with the type are assumed. E.g., `src foo' -means `ip and ((tcp or udp) src foo)', `net bar' means `ip and (net -bar)', and `port 53' means `ip and ((tcp or udp) port 53)'. -.LP -In addition to the above, there are some special `primitive' keywords -that don't follow the pattern: -.BR gateway , -.BR broadcast , -.BR less , -.B greater -and arithmetic expressions. All of these are described below. -.LP -More complex filter expressions are built up by using the words -.BR and , -.B or -and -.B not -to combine primitives. E.g., `host blort and not port ftp and not -port ftp-data'. To save typing, identical qualifier lists can be -omitted. E.g., `tcp dst port ftp or ftp-data or domain' is exactly -the same as `tcp dst port ftp or tcp dst port ftp-data or tcp dst port -domain'. -.LP -Allowable primitives are: - -.IP "\fBdst host \fIhost\fR" -True if the IP destination field of the packet is \fIhost\fP, -which may be either an address or a name. - -.IP "\fBsrc host \fIhost\fR" -True if the IP source field of the packet is \fIhost\fP. - -.IP "\fBhost \fIhost\fP" -True if either the IP source or destination of the packet is \fIhost\fP. -Any of the above host expressions can be prepended with the keywords, -\fBip\fP, \fBarp\fP, or \fBrarp\fP as in: -.in +.5i -.nf -\fBip host \fIhost\fR -.fi -.in -.5i -which is equivalent to: -.in +.5i - - -.IP "\fBether dst \fIehost\fP" -True if the ethernet destination address is \fIehost\fP. \fIEhost\fP -may be either a name from /etc/ethers or a number (see -.IR ethers (3N) -for numeric format). -.IP "\fBether src \fIehost\fP" -True if the ethernet source address is \fIehost\fP. -.IP "\fBether host \fIehost\fP" -True if either the ethernet source or destination address is \fIehost\fP. - -.IP "\fBgateway\fP \fIhost\fP" -True if the packet used \fIhost\fP as a gateway. I.e., the ethernet -source or destination address was \fIhost\fP but neither the IP source -nor the IP destination was \fIhost\fP. \fIHost\fP must be a name and -must be found in both /etc/hosts and /etc/ethers. (An equivalent -expression is -.in +.5i -.nf -\fBether host \fIehost \fBand not host \fIhost\fR -.fi -.in -.5i -which can be used with either names or numbers for \fIhost / ehost\fP.) - -.IP "\fBdst net \fInet\fR" -True if the IP destination address of the packet has a network -number of \fInet\fP. \fINet\fP may be either a name from /etc/networks -or a network number (see \fInetworks(4)\fP for details). - -.IP "\fBsrc net \fInet\fR" -True if the IP source address of the packet has a network -number of \fInet\fP. - -.IP "\fBnet \fInet\fR" -True if either the IP source or destination address of the packet has a network -number of \fInet\fP. - -.IP "\fBnet \fInet\fR \fBmask \fImask\fR" -True if the IP address matches \fInet\fR with the specific netmask. -May be qualified with \fBsrc\fR or \fBdst\fR. - -.IP "\fBnet \fInet\fR/\fIlen\fR" -True if the IP address matches \fInet\fR a netmask \fIlen\fR bits wide. -May be qualified with \fBsrc\fR or \fBdst\fR. - -.IP "\fBdst port \fIport\fR" -True if the packet is ip/tcp or ip/udp and has a -destination port value of \fIport\fP. -The \fIport\fP can be a number or a name used in /etc/services (see -.IR tcp (4P) +.It Fl s Ar snaplen +Set the bpf caplen to +.Ar snaplen . +Defaults to 65536. +.It Fl t +Print a timestamp in the form of +.Ql YYYY/MM/DD HH:MM:SS.UUUUUU +every time a packet is matched. +.It Fl T +Print a timestamp in the form of +.Ql +S.UUUUUU , +indicating the delta between packet matches. +Specify a second time to indicate the delta since the first packet +match. +.It Fl v +Display packets that +.Em do not +match +.Ar expression . +.It Fl w +Match +.Ar expression +as a word. +.It Fl W Cm normal | byline | single | none +Specify an alternate manner for displaying packets. +The +.Cm byline +mode honors embedded linefeeds, +wrapping text only when a linefeed is encountered. +The +.Cm none +mode doesn't wrap under any circumstance, +with the entire payload displayed on one line. +The +.Cm single +mode is conceptually the same as +.Cm none , +except that everything including IP and source/destination header +information is all on one line. +.Cm normal +is the default mode and is only included for completeness. +.Pp +This option is incompatible with +.Fl x . +.It Fl x +Dump packet contents in canonical hex+ASCII form, +similar to the same form in +.Xr hexdump 1 . +.It Fl X +Treat the match expression as a hexadecimal string. +.El +.Pp +.Ar expression +is either a PCRE pattern as specfied in +.Xr pcrepattern 3 , +or a hexadecimal string if +.Fl X +is specified. +Hexadecimal strings can optionally be preceded by +.Ql 0x . +.Pp +.Ar filter +selects which packets will be matched. +If no +.Ar filter +is given, +all IP packets seen on the selected interface will be matched. +Otherwise, only packets satisfying +.Ar filter +will be matched. +The syntax for +.Ar filter +can be found in +.Xr pcap-filter 5 and -.IR udp (4P)). -If a name is used, both the port -number and protocol are checked. If a number or ambiguous name is used, -only the port number is checked (e.g., \fBdst port 513\fR will print both -tcp/login traffic and udp/who traffic, and \fBport domain\fR will print -both tcp/domain and udp/domain traffic). - -.IP "\fBsrc port \fIport\fR" -True if the packet has a source port value of \fIport\fP. - -.IP "\fBport \fIport\fR" -True if either the source or destination port of the packet is \fIport\fP. -Any of the above port expressions can be prepended with the keywords, -\fBtcp\fP or \fBudp\fP, as in: -.in +.5i -.nf -\fBtcp src port \fIport\fR -.fi -.in -.5i -which matches only tcp packets whose source port is \fIport\fP. - -.IP "\fBless \fIlength\fR" -True if the packet has a length less than or equal to \fIlength\fP. -This is equivalent to: -.in +.5i -.nf -\fBlen <= \fIlength\fP. -.fi -.in -.5i - -.IP "\fBgreater \fIlength\fR" -True if the packet has a length greater than or equal to \fIlength\fP. -This is equivalent to: -.in +.5i -.nf -\fBlen >= \fIlength\fP. -.fi -.in -.5i - -.IP "\fBip proto \fIprotocol\fR" -True if the packet is an ip packet (see -.IR ip (4P)) -of protocol type \fIprotocol\fP. \fIProtocol\fP can be a number or -one of the names \fItcp\fP, \fIudp\fP or \fIicmp\fP. Note that the -identifiers \fItcp\fP and \fIudp\fP are also keywords and must be -escaped via backslash (\\), which is \\\\ in the C-shell. - -.IP "\fBip broadcast\fR" -True if the packet is an IP broadcast packet. It checks for both -the all-zeroes and all-ones broadcast conventions, and looks up -the local subnet mask. - -.IP "\fBip multicast\fR" -True if the packet is an IP multicast packet. - -.IP "\fBip\fR" -Abbreviation for: -.in +.5i -.nf -\fBether proto ip\fR -.fi -.IP "\fBtcp\fR, \fBudp\fR, \fBicmp\fR" -Abbreviations for: -.in +.5i -.nf -\fBip proto \fIp\fR -.fi -.in -.5i -where \fIp\fR is one of the above protocols. -.IP "\fIexpr relop expr\fR" -True if the relation holds, where \fIrelop\fR is one of >, <, >=, <=, =, !=, -and \fIexpr\fR is an arithmetic expression composed of integer constants -(expressed in standard C syntax), the normal binary operators -[+, -, *, /, &, |], a length operator, and special packet data accessors. -To access -data inside the packet, use the following syntax: -.in +.5i -.nf -\fIproto\fB [ \fIexpr\fB : \fIsize\fB ]\fR -.fi -.in -.5i -\fIProto\fR is one of \fBip, tcp, udp \fRor \fBicmp\fR, and -indicates the protocol layer for the index operation. The byte -offset, relative to the indicated protocol layer, is given by -\fIexpr\fR. \fISize\fR is optional and indicates the number of bytes -in the field of interest; it can be either one, two, or four, and -defaults to one. The length operator, indicated by the keyword -\fBlen\fP, gives the length of the packet. - -For example, `\fBether[0] & 1 != 0\fP' catches all multicast traffic. -The expression `\fBip[0] & 0xf != 5\fP' -catches all IP packets with options. The expression -`\fBip[6:2] & 0x1fff = 0\fP' -catches only unfragmented datagrams and frag zero of fragmented datagrams. -This check is implicitly applied to the \fBtcp\fP and \fBudp\fP -index operations. -For instance, \fBtcp[0]\fP always means the first -byte of the TCP \fIheader\fP, and never means the first byte of an -intervening fragment. -.LP -Primitives may be combined using: -.IP -A parenthesized group of primitives and operators -(parentheses are special to the Shell and must be escaped). -.IP -Negation (`\fB!\fP' or `\fBnot\fP'). -.IP -Concatenation (`\fB&&\fP' or `\fBand\fP'). -.IP -Alternation (`\fB||\fP' or `\fBor\fP'). -.LP -Negation has highest precedence. -Alternation and concatenation have equal precedence and associate -left to right. Note that explicit \fBand\fR tokens, not juxtaposition, -are now required for concatenation. -.LP -If an identifier is given without a keyword, the most recent keyword -is assumed. -For example, -.in +.5i -.nf -\fBnot host vs and ace\fR -.fi -.in -.5i -is short for -.in +.5i -.nf -\fBnot host vs and host ace\fR -.fi -.in -.5i -which should not be confused with -.in +.5i -.nf -\fBnot ( host vs or ace )\fR -.fi -.in -.5i -.LP -Expression arguments can be passed to ngrep as either a single -argument or as multiple arguments, whichever is more convenient. -Generally, if the expression contains Shell metacharacters, it is -easier to pass it as a single, quoted argument. Multiple arguments -are concatenated with spaces before being parsed. - -.SH DIAGNOSTICS - -Errors from -.B ngrep, libpcap, -and the -.B GNU regex library -are all output to stderr. - -.SH EXIT STATUS - -The ngrep utility exits with one of the following values: - - 0 One or more frames were matched. - 1 No frames were matched. - 2 An error occurred. - 3+ Hell is freezing over, run! - -.SH AUTHOR - -Written by Jordan Ritter <jpr5@darkridge.com>. - -.SH REPORTING BUGS - -Please report bugs to the ngrep's GitHub Issue Tracker, located at - - http://github.com/jpr5/ngrep/issues - -Non-bug, non-feature-request general feedback should be sent to the author -directly by email. - -.SH NOTES - -ALL YOUR BASE ARE BELONG TO US. +.Xr tcpdump 8 . +.Sh EXIT STATUS +The +.Nm +utility exits with one of the following values: +.Bl -tag -width Ds +.It 0 +One or more frames were matched. +.It 1 +No frames were matched. +.It 2 +An error occurred. +.El +.Sh EXAMPLES +Print all syslog messages that contain the word +.Dq error +in them. +.Pp +.Dl # ngrep 'error' port syslog +.Pp +Print FTP packets that contain the words +.Dq user +or +.Dq pass , +case-insensitive. +.Pp +.Dl # ngrep -wi -d any 'user|pass' port 21 +.Pp +Print all HTTP packets and wrap on newlines: +.Pp +.Dl # ngrep -W byline port 80 +.Pp +Print HTTP data containing a specific hexadecimal value in hex+ASCII +form: +.Pp +.Dl # ngrep -xX '0xc5d5e5f55666768696a6b6c6d6e6' port 80 +.Sh SEE ALSO +.Xr grep 1 , +.Xr hexdump 1 , +.Xr pcrepattern 3 , +.Xr pcap-filter 5 , +.Xr tcpdump 8 +.Sh AUTHORS +.An -nosplit +The +.Nm +utility was written by +.An Jordan Ritter Aq Mt jpr5@darkridge.com , +and is maintained by +.An Stephen Gregoratto Aq Mt dev@sgregoratto.me . +.Sh CAVEATS +.Nm +can get confused about which arguments make up the +.Ar expression +or the +.Ar filter . +For example: +.Pp +.Dl # ngrep not port 80 +.Pp +Here +.Nm +will print all packets on port 80 containing the word +.Dq not , +instead of printing all packets that are not on port 80. +In cases like this, you will need to specify a blank match expression: +.Pp +.Dl # ngrep '' not port 80