1
2NGREP(8)                         User Manuals                         NGREP(8)
3
4
5

NAME

7       ngrep - network grep
8
9

SYNOPSIS

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
15

DESCRIPTION

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
25
26

OPTIONS

28       -h     Display help/usage information.
29
30
31       -N     Show  sub-protocol number along with single-character identifier
32              (useful when observing raw or unknown protocols).
33
34
35       -X     Treat the match expression as a  hexadecimal  string.   See  the
36              explanation of match expression below.
37
38
39       -V     Display version information.
40
41
42       -i     Ignore case for the regex expression.
43
44
45       -w     Match the regex expression as a word.
46
47
48       -q     Be quiet; don't output any information other than packet headers
49              and their payloads (if relevant).
50
51
52       -p     Don't put the interface into promiscuous mode.
53
54
55       -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
60
61       -v     Invert the match; only display packets that don't match.
62
63
64       -x     Dump packet contents as hexadecimal as well as ASCII.
65
66
67       -l     Make stdout line buffered.
68
69
70       -D     When reading pcap_dump files, replay them at their recorded time
71              intervals (mimic realtime).
72
73
74       -t     Print a timestamp in  the  form  of  YYYY/MM/DD  HH:MM:SS.UUUUUU
75              everytime a packet is matched.
76
77
78       -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
82
83       -R     Do not try to drop privileges to the DROPPRIVS_USER.
84
85              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
92              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
101
102       -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
108
109       -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
115
116       -P char
117              Specify  an alternate character to signify non-printable charac‐
118              ters when displayed.  The default is ``.''.
119
120
121       -K num Kill matching TCP connections (like tcpkill).  The numeric argu‐
122              ment controls how many RST segments are sent.
123
124
125       -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
137
138       -s snaplen
139              Set the bpf caplen to snaplen (default 65536).
140
141
142       -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
147
148       -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
153
154       -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
158
159       -n num Match only num packets total, then exit.
160
161
162       -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
165
166       -A num Dump num packets of trailing context after matching a packet.
167
168
169        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
177
178        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
184       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
188       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
193       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
201       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
208       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
212       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
219       Allowable primitives are:
220
221
222       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
226
227       src host host
228              True if the IP source field of the packet is host.
229
230
231       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
238
239
240       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
245       ether src ehost
246              True if the ethernet source address is ehost.
247
248       ether host ehost
249              True if either the ethernet source  or  destination  address  is
250              ehost.
251
252
253       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
263
264       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
269
270       src net net
271              True if the IP source address of the packet has a network number
272              of net.
273
274
275       net net
276              True  if  either  the  IP  source  or destination address of the
277              packet has a network number of net.
278
279
280       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
284
285       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
289
290       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
300
301       src port port
302              True if the packet has a source port value of port.
303
304
305       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
312
313       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
318
319       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
324
325       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
332
333       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
338
339       ip multicast
340              True if the packet is an IP multicast packet.
341
342
343       ip     Abbreviation for:
344                   ether proto ip
345
346       tcp, udp, icmp
347              Abbreviations for:
348                   ip proto p
349              where p is one of the above protocols.
350
351       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
367              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
376       Primitives may be combined using:
377
378              A  parenthesized  group of primitives and operators (parentheses
379              are special to the Shell and must be escaped).
380
381              Negation (`!' or `not').
382
383              Concatenation (`&&' or `and').
384
385              Alternation (`||' or `or').
386
387       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
391       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
399       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
405

DIAGNOSTICS

407       Errors from ngrep, libpcap, and the GNU regex library are all output to
408       stderr.
409
410

EXIT STATUS

412       The ngrep utility exits with one of the following values:
413
414            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
419

AUTHOR

421       Written by Jordan Ritter <jpr5@darkridge.com>.
422
423

REPORTING BUGS

425       Please report bugs to the ngrep's GitHub Issue Tracker, located at
426
427           http://github.com/jpr5/ngrep/issues
428
429       Non-bug, non-feature-request general feedback should  be  sent  to  the
430       author directly by email.
431
432

NOTES

434       ALL YOUR BASE ARE BELONG TO US.
435
436
437
438*nux                            September 2017                        NGREP(8)
Impressum