1NGREP(8) User Manuals NGREP(8)
3
7 ngrep - network grep
8
11 ngrep <-hNXViwqpevxlDtTRM> <-IO pcap_dump > < -n num > < -d dev > < -A
12 num > < -s snaplen > < -S limitlen > < -W normal|byline|single|none > <
13 -c cols > < -P char > < -F file > < match expression > < bpf filter >
14
17 ngrep strives to provide most of GNU grep's common features, applying
18 them to the network layer. ngrep is a pcap-aware tool that will allow
19 you to specify extended regular expressions to match against data pay‐
20 loads of packets. It currently recognizes TCP, UDP and ICMP across
21 Ethernet, PPP, SLIP, FDDI and null interfaces, and understands bpf fil‐
22 ter logic in the same fashion as more common packet sniffing tools,
23 such as tcpdump(8) and snoop(1).
24
28 -h Display help/usage information.
29 -N Show sub-protocol number along with single-character identifier
32 (useful when observing raw or unknown protocols).
33 -X Treat the match expression as a hexadecimal string. See the
36 explanation of match expression below.
37 -V Display version information.
40 -i Ignore case for the regex expression.
43 -w Match the regex expression as a word.
46 -q Be quiet; don't output any information other than packet headers
49 and their payloads (if relevant).
50 -p Don't put the interface into promiscuous mode.
53 -e Show empty packets. Normally empty packets are discarded
56 because they have no payload to search. If specified, empty
57 packets will be shown, regardless of the specified regex expres‐
58 sion.
59 -v Invert the match; only display packets that don't match.
62 -x Dump packet contents as hexadecimal as well as ASCII.
65 -l Make stdout line buffered.
68 -D When reading pcap_dump files, replay them at their recorded time
71 intervals (mimic realtime).
72 -t Print a timestamp in the form of YYYY/MM/DD HH:MM:SS.UUUUUU
75 everytime a packet is matched.
76 -T Print a timestamp in the form of +S.UUUUUU, indicating the delta
79 between packet matches. Specify a second time to indicate the
80 delta since the first packet match.
81 -R Do not try to drop privileges to the DROPPRIVS_USER.
84 ngrep makes no effort to validate input from live or offline
86 sources as it is focused more on performance and handling large
87 amounts of data than protocol correctness, which is most often a
88 fair assumption to make. However, sometimes it matters and thus
89 as a rule ngrep will try to be defensive and drop any root priv‐
90 ileges it might have.
91 There exist scenarios where this behaviour can become an obsta‐
93 cle, so this option is provided to end-users who want to disable
94 this feature, but must do so with an understanding of the risks.
95 Packets can be randomly malformed or even specifically designed
96 to overflow sniffers and take control of them, and revoking root
97 privileges is currently the only risk mitigation ngrep employs
98 against such an attack. Use this option and turn it off at your
99 own risk.
100 -c cols
103 Explicitly set the console width to ``cols''. Note that this is
104 the console width, and not the full width of what ngrep prints
105 out as payloads; depending on the output mode ngrep may print
106 less than ``cols'' bytes per line (indentation).
107 -F file
110 Read in the bpf filter from the specified filename. This is a
111 compatibility option for users familiar with tcpdump. Please
112 note that specifying ``-F'' will override any bpf filter speci‐
113 fied on the command-line.
114 -P char
117 Specify an alternate character to signify non-printable charac‐
118 ters when displayed. The default is ``.''.
119 -K num Kill matching TCP connections (like tcpkill). The numeric argu‐
122 ment controls how many RST segments are sent.
123 -W normal|byline|single|none
126 Specify an alternate manner for displaying packets, when not in
127 hexadecimal mode. The ``byline'' mode honors embedded line‐
128 feeds, wrapping text only when a linefeed is encountered (useful
129 for observing HTTP transactions, for instance). The ``none''
130 mode doesn't wrap under any circumstance (entire payload is dis‐
131 played on one line). The ``single'' mode is conceptually the
132 same as ``none'', except that everything including IP and
133 source/destination header information is all on one line.
134 ``normal'' is the default mode and is only included for com‐
135 pleteness. This option is incompatible with ``-x''.
136 -s snaplen
139 Set the bpf caplen to snaplen (default 65536).
140 -S limitlen
143 Set the upper limit on the size of packets that ngrep will look
144 at. Useful for looking at only the first N bytes of packets
145 without changing the BPF snaplen.
146 -I pcap_dump
149 Input file pcap_dump into ngrep. Works with any pcap-compatible
150 dump file format. This option is useful for searching for a
151 wide range of different patterns over the same packet stream.
152 -O pcap_dump
155 Output matched packets to a pcap-compatible dump file. This
156 feature does not interfere with normal output to stdout.
157 -n num Match only num packets total, then exit.
160 -d dev By default ngrep will select a default interface to listen on.
163 Use this option to force ngrep to listen on interface dev.
164 -A num Dump num packets of trailing context after matching a packet.
167 match expression
170 A match expression is either an extended regular expression, or
171 if the -X option is specified, a string signifying a hexadecimal
172 value. An extended regular expression follows the rules as
173 implemented by the GNU regex library. Hexadecimal expressions
174 can optionally be preceded by `0x'. E.g., `DEADBEEF', `0xDEAD‐
175 BEEF'.
176 bpf filter
179 Selects a filter that specifies what packets will be dumped. If
180 no bpf filter is given, all IP packets seen on the selected
181 interface will be dumped. Otherwise, only packets for which bpf
182 filter is `true' will be dumped.
183 The bpf filter consists of one or more primitives. Primitives usually
185 consist of an id (name or number) preceded by one or more qualifiers.
186 There are three different kinds of qualifier:
187 type qualifiers say what kind of thing the id name or number refers
189 to. Possible types are host, net and port. E.g., `host blort',
190 `net 1.2.3', `port 80'. If there is no type qualifier, host is
191 assumed.
192 dir qualifiers specify a particular transfer direction to and/or
194 from id. Possible directions are src, dst, src or dst and src
195 and dst. E.g., `src foo', `dst net 1.2.3', `src or dst port
196 ftp-data'. If there is no dir qualifier, src or dst is assumed.
197 For `null' link layers (i.e. point to point protocols such as
198 slip) the inbound and outbound qualifiers can be used to specify
199 a desired direction.
200 proto qualifiers are restricted to ip-only protocols. Possible protos
202 are: tcp , udp and icmp. e.g., `udp src foo' or `tcp port 21'.
203 If there is no proto qualifier, all protocols consistent with
204 the type are assumed. E.g., `src foo' means `ip and ((tcp or
205 udp) src foo)', `net bar' means `ip and (net bar)', and `port
206 53' means `ip and ((tcp or udp) port 53)'.
207 In addition to the above, there are some special `primitive' keywords
209 that don't follow the pattern: gateway, broadcast, less, greater and
210 arithmetic expressions. All of these are described below.
211 More complex filter expressions are built up by using the words and, or
213 and not to combine primitives. E.g., `host blort and not port ftp and
214 not port ftp-data'. To save typing, identical qualifier lists can be
215 omitted. E.g., `tcp dst port ftp or ftp-data or domain' is exactly the
216 same as `tcp dst port ftp or tcp dst port ftp-data or tcp dst port
217 domain'.
218 Allowable primitives are:
220 dst host host
223 True if the IP destination field of the packet is host, which
224 may be either an address or a name.
225 src host host
228 True if the IP source field of the packet is host.
229 host host
232 True if either the IP source or destination of the packet is
233 host. Any of the above host expressions can be prepended with
234 the keywords, ip, arp, or rarp as in:
235 ip host host
236 which is equivalent to:
237 ether dst ehost
241 True if the ethernet destination address is ehost. Ehost may be
242 either a name from /etc/ethers or a number (see ethers(3N) for
243 numeric format).
244 ether src ehost
246 True if the ethernet source address is ehost.
247 ether host ehost
249 True if either the ethernet source or destination address is
250 ehost.
251 gateway host
254 True if the packet used host as a gateway. I.e., the ethernet
255 source or destination address was host but neither the IP source
256 nor the IP destination was host. Host must be a name and must
257 be found in both /etc/hosts and /etc/ethers. (An equivalent
258 expression is
259 ether host ehost and not host host
260 which can be used with either names or numbers for host /
261 ehost.)
262 dst net net
265 True if the IP destination address of the packet has a network
266 number of net. Net may be either a name from /etc/networks or a
267 network number (see networks(4) for details).
268 src net net
271 True if the IP source address of the packet has a network number
272 of net.
273 net net
276 True if either the IP source or destination address of the
277 packet has a network number of net.
278 net net mask mask
281 True if the IP address matches net with the specific netmask.
282 May be qualified with src or dst.
283 net net/len
286 True if the IP address matches net a netmask len bits wide. May
287 be qualified with src or dst.
288 dst port port
291 True if the packet is ip/tcp or ip/udp and has a destination
292 port value of port. The port can be a number or a name used in
293 /etc/services (see tcp(4P) and udp(4P)). If a name is used,
294 both the port number and protocol are checked. If a number or
295 ambiguous name is used, only the port number is checked (e.g.,
296 dst port 513 will print both tcp/login traffic and udp/who traf‐
297 fic, and port domain will print both tcp/domain and udp/domain
298 traffic).
299 src port port
302 True if the packet has a source port value of port.
303 port port
306 True if either the source or destination port of the packet is
307 port. Any of the above port expressions can be prepended with
308 the keywords, tcp or udp, as in:
309 tcp src port port
310 which matches only tcp packets whose source port is port.
311 less length
314 True if the packet has a length less than or equal to length.
315 This is equivalent to:
316 len <= length.
317 greater length
320 True if the packet has a length greater than or equal to length.
321 This is equivalent to:
322 len >= length.
323 ip proto protocol
326 True if the packet is an ip packet (see ip(4P)) of protocol type
327 protocol. Protocol can be a number or one of the names tcp, udp
328 or icmp. Note that the identifiers tcp and udp are also key‐
329 words and must be escaped via backslash (\), which is \\ in the
330 C-shell.
331 ip broadcast
334 True if the packet is an IP broadcast packet. It checks for
335 both the all-zeroes and all-ones broadcast conventions, and
336 looks up the local subnet mask.
337 ip multicast
340 True if the packet is an IP multicast packet.
341 ip Abbreviation for:
344 ether proto ip
345 tcp, udp, icmp
347 Abbreviations for:
348 ip proto p
349 where p is one of the above protocols.
350 expr relop expr
352 True if the relation holds, where relop is one of >, <, >=, <=,
353 =, !=, and expr is an arithmetic expression composed of integer
354 constants (expressed in standard C syntax), the normal binary
355 operators [+, -, *, /, &, |], a length operator, and special
356 packet data accessors. To access data inside the packet, use
357 the following syntax:
358 proto [ expr : size ]
359 Proto is one of ip, tcp, udp or icmp, and indicates the protocol
360 layer for the index operation. The byte offset, relative to the
361 indicated protocol layer, is given by expr. Size is optional
362 and indicates the number of bytes in the field of interest; it
363 can be either one, two, or four, and defaults to one. The
364 length operator, indicated by the keyword len, gives the length
365 of the packet.
366 For example, `ether[0] & 1 != 0' catches all multicast traffic.
368 The expression `ip[0] & 0xf != 5' catches all IP packets with
369 options. The expression `ip[6:2] & 0x1fff = 0' catches only
370 unfragmented datagrams and frag zero of fragmented datagrams.
371 This check is implicitly applied to the tcp and udp index opera‐
372 tions. For instance, tcp[0] always means the first byte of the
373 TCP header, and never means the first byte of an intervening
374 fragment.
375 Primitives may be combined using:
377 A parenthesized group of primitives and operators (parentheses
379 are special to the Shell and must be escaped).
380 Negation (`!' or `not').
382 Concatenation (`&&' or `and').
384 Alternation (`||' or `or').
386 Negation has highest precedence. Alternation and concatenation have
388 equal precedence and associate left to right. Note that explicit and
389 tokens, not juxtaposition, are now required for concatenation.
390 If an identifier is given without a keyword, the most recent keyword is
392 assumed. For example,
393 not host vs and ace
394 is short for
395 not host vs and host ace
396 which should not be confused with
397 not ( host vs or ace )
398 Expression arguments can be passed to ngrep as either a single argument
400 or as multiple arguments, whichever is more convenient. Generally, if
401 the expression contains Shell metacharacters, it is easier to pass it
402 as a single, quoted argument. Multiple arguments are concatenated with
403 spaces before being parsed.
404
407 Errors from ngrep, libpcap, and the GNU regex library are all output to
408 stderr.
409
412 The ngrep utility exits with one of the following values:
413 0 One or more frames were matched.
415 1 No frames were matched.
416 2 An error occurred.
417 3+ Hell is freezing over, run!
418
421 Written by Jordan Ritter <jpr5@darkridge.com>.
422
425 Please report bugs to the ngrep's GitHub Issue Tracker, located at
426 http://github.com/jpr5/ngrep/issues
428 Non-bug, non-feature-request general feedback should be sent to the
430 author directly by email.
431
434 ALL YOUR BASE ARE BELONG TO US.
435*nux September 2017 NGREP(8)