Integrate ngrep into Solaris [PSARC/2008/562 FastTrack timeout 09/11/2008]
Brian Utterback
brian.utterback at sun.com
Wed Sep 10 10:12:16 PDT 2008
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
More information about the opensolaris-arc
mailing list