This case was approved in today's PSARC meeting. Brian Utterback wrote: > I am sponsoring the following fast-track for Martina Tomisova. This case > proposes to integrate the ngrep open-source utility into the SFW > consolidation. > A patch binding is requested. > > Template Version: @(#)sac_nextcase %I% %G% SMI > This information is Copyright 2008 Sun Microsystems > 1. Introduction > 1.1. Project/Component Working Name: > Integrate ngrep into Solaris > 1.2. Name of Document Author/Supplier: > Author: Martina Tomisova > 1.3 Date of This Document: > 04 September, 2008 > 4. Technical Description > Proposal: > > Integrate ngrep into Solaris. > > Detail: > > ngrep is a tool for ?grepping? specific information in network > packets. 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 > or hexadecimal expressions to match against data payloads of > packets. It currently recognizes IPv4, TCP, UDP, ICMPv4, IGMP > and Raw across Ethernet, PPP, SLIP, FDDI, Token Ring and null > interfaces, and understands BPF filter logic in the same fashion > as more common packet sniffing tools, such as tcpdump and snoop. > The current version of ngrep is 1.45 at the time of this case. > > > > Exported Interfaces: > > SUNWngrep Uncommitted Package name > /usr/sbin/ngrep Committed Executable location > ngrep Uncommitted Commandline syntax > > Imported Interfaces: > > SUNWlibpcap Libraries (libpcap.so) > > Security: > > RBAC - Anyone who has a role which contains the Network > Management privileges can execute the ngrep as a root. (no SUID > bit for all, just line added to /etc/security/exec_attr as for > other sniffing tools like snoop). > > There was an '-R' option that prevents ngrep from dropping the > root privileges after it starts the capturing. It could be > dangerous (one never knows what will be received from the > network). This option has been removed. > > References: > > [1] http://ngrep.sourceforge.net/ > Author(s) of ngrep: Jordan Ritter <jpr5 at darkridge.com> > [2] 6721123 - Integrate ngrep into Solaris. > > List of new files: > usr/sbin/ngrep > usr/share/man/man1m/ngrep.1m > > 6. Resources and Schedule > 6.4. Steering Committee requested information > 6.4.1. Consolidation C-team Name: > on > 6.5. ARC review type: FastTrack > 6.6. ARC Exposure: open > > Proposes man page: > > User Manuals NGREP(1M) > > > > NAME > ngrep - network grep > > > SYNOPSIS > ngrep <-hNXViwqpevxlDtTRM> <-IO pcap_dump > < -n num > < -d > dev > < -A num > < -s snaplen > < -S limitlen > < -W > normal|byline|single|none > < -c cols > < -P char > < -F > file > < match expression > < bpf filter > > > > 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 expres- > sions 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 tcpdump(1M) and snoop(1). > > 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 after started > catching of packets. > > > > OPTIONS > -h Display help/usage information. > > > -N Show sub-protocol number along with single-character > identifier (useful when observing raw or unknown proto- > cols). > > > -X Treat the match expression as a hexadecimal string. > See the explanation of match expression below. > > > -V Display version information. > > > -i Ignore case for the regex expression. > > > -w Match the regex expression as a word. > > > > > *nux Last change: November 2006 1 > > > > > > > User Manuals NGREP(1M) > > > > -q Be quiet; don't output any information other than > packet headers and their payloads (if relevant). > > > -p Don't put the interface into promiscuous mode. > > > -e Show empty packets. Normally empty packets are dis- > carded because they have no payload to search. If > specified, empty packets will be shown, regardless of > the specified regex expression. > > > -v Invert the match; only display packets that don't > match. > > > -x Dump packet contents as hexadecimal as well as ASCII. > > > -l Make stdout line buffered. > > > -D When reading pcap_dump files, replay them at their > recorded time intervals (mimic realtime). > > > -t Print a timestamp in the form of YYYY/MM/DD > HH:MM:SS.UUUUUU everytime a packet is matched. > > > -T Print a timestamp in the form of +S.UUUUUU, indicating > the delta between packet matches. > > > > > > > -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). > > > -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 over- > ride any bpf filter specified on the command-line. > > > > *nux Last change: November 2006 2 > > > > > > > User Manuals NGREP(1M) > > > > -P char > Specify an alternate character to signify non-printable > characters when displayed. The default is ``.''. > > > -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. The ``none'' mode doesn't > wrap under any circumstance (entire payload is > displayed on one line). The ``single'' mode is concep- > tually 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''. > > > -s snaplen > Set the bpf caplen to snaplen (default 65536). > > > -S limitlen > Set the upper limit on the size of packets that ngrep > will look at. Useful for looking at only the first N > bytes of packets without changing the BPF snaplen. > > > -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. > > > -O pcap_dump > Output matched packets to a pcap-compatible dump file. > This feature does not interfere with normal output to > stdout. > > > -n num > Match only num packets total, then exit. > > > -d dev > By default ngrep will select a default interface to > listen on. Use this option to force ngrep to listen on > interface dev. > > > > > > *nux Last change: November 2006 3 > > > > > > > User Manuals NGREP(1M) > > > > -A num > Dump num packets of trailing context after matching a > packet. > > > -W normal|byline|none > Alter the method by which ngrep displays packet pay- > load. ``normal'' mode represents the standard > behaviour, ``byline'' instructs ngrep to respect embed- > ded linefeeds (useful for observing HTTP transactions, > for instance), and ``none'' results in the payload on > one single line (useful for scripted processing of > ngrep output). > > > -c cols > Ignore the detected terminal width and force the column > width to the specified size. > > > -P char > Change the non-printable character from the default > ``.'' to the character specified. > > > match expression > A match expression is either an extended regular > expression, or if the -X option is specified, a string > signifying a hexadecimal value. An extended regular > expression follows the rules as implemented by the GNU > regex library. Hexadecimal expressions can optionally > be preceded by `0x'. E.g., `DEADBEEF', `0xDEADBEEF'. > > > bpf filter > Selects a filter that specifies what packets will be > dumped. If no bpf filter is given, all IP packets seen > on the selected interface will be dumped. Otherwise, > only packets for which bpf filter is `true' will be > dumped. > > The bpf filter consists of one or more primitives. Primi- > tives usually consist of an id (name or number) preceded by > one or more qualifiers. There are three different kinds of > qualifier: > > type qualifiers say what kind of thing the id name or number > refers to. Possible types are host, net and port. > E.g., `host blort', `net 1.2.3', `port 80'. If there > is no type qualifier, host is assumed. > > dir qualifiers specify a particular transfer direction to > > > > *nux Last change: November 2006 4 > > > > > > > User Manuals NGREP(1M) > > > > and/or from id. Possible directions are src, dst, src > or dst and src and dst. E.g., `src foo', `dst net > 1.2.3', `src or dst port ftp-data'. If there is no dir > qualifier, src or dst is assumed. For `null' link > layers (i.e. point to point protocols such as slip) the > inbound and outbound qualifiers can be used to specify > a desired direction. > > proto > qualifiers are restricted to ip-only protocols. Possi- > ble protos are: tcp , udp and 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)'. > > In addition to the above, there are some special `primitive' > keywords that don't follow the pattern: gateway, broadcast, > less, greater and arithmetic expressions. All of these are > described below. > > More complex filter expressions are built up by using the > words and, or and not to combine primitives. E.g., `host > blort and not port ftp and not port ftp-data'. To save typ- > ing, 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'. > dst net net > True if the IP destination address of the packet has a > network number of net. Net may be either a name from > /etc/networks or a network number (see networks(4) for > details). > > > src net net > True if the IP source address of the packet has a net- > work number of net. > > > net net > True if either the IP source or destination address of > the packet has a network number of net. > > > net net mask mask > True if the IP address matches net with the specific > netmask. May be qualified with src or dst. > > > net net/len > True if the IP address matches net a netmask len bits > wide. May be qualified with src or dst. > > > dst port port > > > > *nux Last change: November 2006 6 > > > > > > > User Manuals NGREP(1M) > > > > True if the packet is ip/tcp or ip/udp and has a desti- > nation port value of port. The port can be a number or > a name used in /etc/services (see tcp(4P) and 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., dst port 513 > will print both tcp/login traffic and udp/who traffic, > and port domain will print both tcp/domain and > udp/domain traffic). > > > src port port > True if the packet has a source port value of port. > > > port port > True if either the source or destination port of the > packet is port. Any of the above port expressions can > be prepended with the keywords, tcp or udp, as in: > > Allowable primitives are: > > > dst host host > True if the IP destination field of the packet is host, > which may be either an address or a name. > > > src host host > True if the IP source field of the packet is host. > > > host host > True if either the IP source or destination of the > packet is host. Any of the above host expressions can > be prepended with the keywords, ip, arp, or rarp as in: > ip host host > which is equivalent to: > > > > ether dst ehost > > > > *nux Last change: November 2006 5 > > > > > > > User Manuals NGREP(1M) > > > > True if the ethernet destination address is ehost. > Ehost may be either a name from /etc/ethers or a number > (see ethers(3N) for numeric format). > > ether src ehost > True if the ethernet source address is ehost. > > ether host ehost > True if either the ethernet source or destination > address is ehost. > > > gateway host > True if the packet used host as a gateway. I.e., the > ethernet source or destination address was host but > neither the IP source nor the IP destination was host. > Host must be a name and must be found in both > /etc/hosts and /etc/ethers. (An equivalent expression > is > ether host ehost and not host host > which can be used with either names or numbers for host > / ehost.) > > > tcp src port port > which matches only tcp packets whose source port is > port. > > > less length > True if the packet has a length less than or equal to > length. This is equivalent to: > len <= length. > > > greater length > True if the packet has a length greater than or equal > to length. This is equivalent to: > len >= length. > > > ip proto protocol > True if the packet is an ip packet (see ip(4P)) of pro- > tocol type protocol. Protocol can be a number or one > of the names tcp, udp or icmp. Note that the identif- > iers tcp and udp are also keywords and must be escaped > via backslash (\), which is \\ in the C-shell. > > > ip broadcast > 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 multicast > True if the packet is an IP multicast packet. > > > > *nux Last change: November 2006 7 > > > > > > > User Manuals NGREP(1M) > > > > ip Abbreviation for: > ether proto ip > > tcp, udp, icmp > Abbreviations for: > ip proto p > where p is one of the above protocols. > > expr relop expr > True if the relation holds, where relop is one of >, <, > >=, <=, =, !=, and expr is an arithmetic expression > composed of integer constants (expressed in standard C > syntax), the normal binary operators [+, -, *, /, &, > |], a length operator, and special packet data acces- > sors. To access data inside the packet, use the fol- > lowing syntax: > proto [ expr : size ] > Proto is one of ip, tcp, udp or icmp, and indicates the > protocol layer for the index operation. The byte > offset, relative to the indicated protocol layer, is > given by expr. Size 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 len, gives > the length of the packet. > > For example, `ether[0] & 1 != 0' catches all multicast > traffic. The expression `ip[0] & 0xf != 5' catches all > IP packets with options. The expression `ip[6:2] & > 0x1fff = 0' catches only unfragmented datagrams and > frag zero of fragmented datagrams. This check is > implicitly applied to the tcp and udp index operations. > For instance, tcp[0] always means the first byte of the > TCP header, and never means the first byte of an inter- > vening fragment. > > Primitives may be combined using: > > A parenthesized group of primitives and operators > (parentheses are special to the Shell and must be > escaped). > > Negation (`!' or `not'). > > Concatenation (`&&' or `and'). > > Alternation (`||' or `or'). > > Negation has highest precedence. Alternation and concatena- > tion have equal precedence and associate left to right. > Note that explicit and tokens, not juxtaposition, are now > required for concatenation. > > > > *nux Last change: November 2006 8 > > > > > > > User Manuals NGREP(1M) > > > > If an identifier is given without a keyword, the most recent > keyword is assumed. For example, > not host vs and ace > is short for > not host vs and host ace > which should not be confused with > not ( host vs or ace ) > > Expression arguments can be passed to ngrep as either a sin- > > If an identifier is given without a keyword, the most recent > keyword is assumed. For example, > not host vs and ace > is short for > not host vs and host ace > which should not be confused with > not ( host vs or ace ) > > Expression arguments can be passed to ngrep as either a sin- > gle 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. > > > DIAGNOSTICS > Errors from ngrep, libpcap, and the GNU regex library are > all output to stderr. > > > AUTHOR > Written by Jordan Ritter <jpr5 at darkridge.com>. > > > REPORTING BUGS > Please report bugs to the ngrep's Sourceforge Bug Tracker, > located at > > http://sourceforge.net/projects/ngrep/ > > Non-bug, non-feature-request general feedback should be sent > to the author directly by email. > > > NOTES > ALL YOUR BASE ARE BELONG TO US. > > ATTRIBUTES > See attributes(5) for descriptions of the following attri- > butes: > > box; cbp-1 | cbp-1 l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE = > Availability SUNWngrep = Interface Stability Uncommitted > > NOTES > Source for ngrep is available on http://opensolaris.org. > > > > > > > > > *nux Last change: November 2006 9
-- blu There are two rules in life: Rule 1- Don't tell people everything you know ---------------------------------------------------------------------- Brian Utterback - Solaris RPE, Sun Microsystems, Inc. Ph:877-259-7345, Em:brian.utterback-at-ess-you-enn-dot-kom
