.ig ---------------------------------------------------------------------------- Copyright (c) 2001, 2002, C.S. Peron All rights reserved. ---------------------------------------------------------------------------- * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the ipex developers nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. ---------------------------------------------------------------------------- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ---------------------------------------------------------------------------- .. .\" man page for ipex 2.3.5 .\" define a string tx for the TeX logo .ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X .el .ds tx TeX . .de TQ .br .ns .TP \\$1 .. . .\" Like TP, but if specified indent is more than half .\" the current line-length - indent, use the default indent. .de Tp .ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP .el .TP "\\$1" .. . .\" The BSD man macros can't handle " in arguments to font change macros, .\" so use \(ts instead of ". .tr \(ts" . .TH IPEX 1 "2 April 2003" "ipex version 2.4.0" . .SH NAME . . ipex \- packet examination utility . .SH SYNOPSIS . . .nr a \n(.j .ad l .nr i \n(.i .in +\w'\fBtroff 'u .ti \niu .B ipex\ .de OP .ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]" .el .RB "[\ " "\\$1" "\ ]" .. .OP \-dlnqvxDGHLOT .OP \-a file .OP \-c count .OP \-E regexp .OP \-e expression .OP \-f file .OP \-i iface .OP \-r file .OP \-t time .OP \-u uid .OP \-w file .OP \-B pattern .OP \-P op=arg .RI "[\ " expression "\ ]" .br .ad \na . .SH DESCRIPTION . This manual page describes the .BR ipex packet auditing utility. .BR ipex is similar to .BR tcpdump or .BR ngrep . It allows you to dump the contents of packets in hexadecimal or plain text. .BR ipex allows you to inspect packets by binary signature, regular expression, pcap expression, process ID and real or effective user ID. .ad \na .PP .BR ipex also gives you the option of running in daemon mode while dumping the contents of the packets to a specified file. This manual comes with some descriptive examples close to the closing. . . .SH OPTIONS . . .TP \w'\-dname=s'u+2n .\" -a option .BI \-a file Decode TCP session filenames that was previously generated by the .B \-T flag. If .IR file is .B "all" every TCP session file in the current working directory will be decoded. NOTE: if you rename the file it can not be decoded. The filename is a 16 .B byte value that stores 1) the time the session was started, or the time the first packet was captured. 2) the src and dst port and hosts of the session. This value is represented in base16. .TP .\" -c option .BI \-c count Capture .IR count packets then exit. The default is 0. This means that .BR ipex will capture packets until its interrupted with a signal. .TP .\" -d option .B \-d When .IR pcap_compile(3) is called, it takes the supplied (``pcap expression'') and generates something called a (``struct bpf_program''). This struct is then fed to .IR /dev/bpf using an .IR ioctl(3) . One of this structures elements is something called a (``struct bpf_insn''). This determains which packets are to be captured and which packets are to be ignored. The .BI \-d switch causes the contents of this structure to be dumped. This feature would typically be used when debugging .IR pcap(3) or .IR bpf(4) . .TP .\" -e expression options .BI \-e expression Match packet if the date/time expression matches the date/time the packet was captured off the wire. The expression can consist of date, time or date and time combinations. See examples for more information on legal expression synopsis. .TP .\" -f option .BI \-f file Pathname to the expression file. This file would contain .IR pcap filter logic. If you use this option do not specify any .IR pcap expressions on the command line. .TP .\" -i option .BI \-i iface Specify an alternate network interface to capture the packets from. If no interface is specified .BR ipex will search the system interface list for the lowest numbered, configured and up interface (excluding loopback). .TP .\" -n option .B \-n Do not use .IR gethostbyaddr(3) to resolve the IP addresses to their hostnames. If this flag is specified on the command line; .BR ipex will not resolve the IP address. Thus src and dst addresses will be expressed in xxx.xxx.xxx.xxx (Internet standard `.') notation. .TP .B \-q Do not officially put the interface into promiscuous mode. By default this switch is turned off and the interface goes into promiscuous mode. .TP .\" -r option .BI \-E regexp Process packets which only have occurances in them that match the supplied regular expression. See examples for better idea on how this flag works. The .IR REG_EXTENDED bit is set. Which makes the internal regex handler compile modern (``extended'') RE's. This routine implements IEEE Std 1003.2 POSIX.2. .TP .\" -t option .BI \-t time Capture packets for .IR time amount of time. .IR time can be suffixed by .IR d for days, .IR h for hours, .IR m for minutes or .IR s for seconds. If no suffix is given, seconds is assumed. The default for this option is eternity. .TP .\" -u option .BI \-u uid When running .BR ipex in a demonized state you can set the UID that ipex is running as. This feature was implemented for obvious security reasons. This flag requires the .IR numeric ID of the preferred user. .TP .\" -v option .B \-v Dump the current .BR ipex build number and exit. When reporting a bug or contributing a source code patch be sure to include this build number with the contribution. .TP .\" -w file .BI \-r file Instead of opening the network interface, you can read raw pcap trace files from the file specified by .IR file . This pcap trace file can be generated with the .IR \-w option. It is also compatible with the .IR tcpdump(1) .IR \-r option. If the specified .IR file is ``-'' then standard-in is assumed. .TP .\" -x option .B \-x When dumping the packet's contents or payload, process the data such that its printed as a formatted hexadecimal dump. The far left column is the offset, the middle column is the hexadecimal dump in the corresponding offset and the far right column is an ascii dump. If a character is not printable as decided by .IR isgraph(3) then a ``.'' dot is printed in the characters place. To view the characters that would be processed by .IR isgraph(3) see the man page. .TP .\" -B option .BI \-B pattern Match if packet contains binary pattern .IR pattern . These patterns must be specified in hexadecimal. Each octet must be represented using two digits. For example, if you wanted to match every packet which contained a NULL character, the binary pattern specification would be ``00''. The pattern spec can contain spaces. .TP .\" -F option .BI \-w file Write raw packets to .IR file rather then processing and writing them to some out-put stream. Packets can later be processed with .BR ipex , .IR tcpdump(1) or any other program that can process pcap trace files. If you want to use .BR ipex to process the trace file, use the .IR \-r option. If .IR file is ``-'' then standard-out is assumed. .TP .\" -H option .B \-H This option will print just the headers of the packets. It considered to throw .BR ipex into a very low verbosity mode. This is useful when you would like a general idea on what traffic is coming through the node; without having all the protocol noise that comes with default packet dumps. .TP .B \-l Put ipex into line buffered mode. .TP .\" -L option .B \-L Display the physical link addresses of packets. The addresses are displayed in the form that .IR ether_ntoa(3) returns them in. Which is an ASCII representation of an Ethernet address. .\" -O option .B \-O Run the packet-matching code optimizer. This option should be enabled by default and soon will be. .TP .\" -P option .BI \-P op = arg Open .IR /dev/mem and scan all the process for a given .IR op using .IR arg as the argument for the op. Supported .IR op ' s are .B uid, .B ruid, and .B pid. For example, if one wanted to monitor all traffic coming from and going to a process which had a pid of 44556; you would specify .IR \-P\ pid = 44556 on the command line. Arbitrarily for .IR uid and .IR ruid. .TP .B \-T Enable TCP session tracking. When this switch is used, the contents of entire TCP sessions will be written to their own independent file. This file can be later viewed using .B tcpdump , .B ethereal or any other program that supports processing of tcpdump capture files. For more information on how the filenames are encoded, please see the .B \-a option documented above in this manual. .br .IP "\fI expression\fP" .RS See tcpdump(1) for more information on pcap(3) expressions. .SH EXAMPLES .LP Here are some examples using .BR ipex , from simple examples to more esoteric. For more information regarding regular expressions you should consult your .IR re_format(7) manual. The better you get at learning these RC's the more efficient your packet filtering skills will become. Also a good solid knowledge on using pcap expressions will really help. I designed .BR ipex to be a network protocol debugger. Please do not abuse this program. .IP "\fBipex -x '\&(tcp[13] & 0x02 != 0) && (tcp[13] & 0x10 != 0)'" Capture all TCP packets which have the ACK+SYN flags sent. This is primarily handy when a user wants to log all ESTABLISHED connections. If you wanted to log say all established connections to your host, you could tag a .B "src host" .IR host to the ruleset. .IP "\fBipex '\&(ip[9] = 17) and (ip[22:2]=161)'" Capture all SNMP packets. We are looking for UDP packets sent to port 161. The protocol is stored in the tenth byte of the IP header, that is offset 9. Protocol 17 specifies UDP. The \&IP[22:2]=161 ensures the packet is going to port 161. .IP "\fBipex -i ed0 -P pid=1335" Would cause ipex to open /dev/ed0 as its primary interface and capture packets going to and coming from the process which had a pid of 1335. .IP "\fBipex -B '91d0 2008' Match any packet which contains the Solaris Sparc binary machine codes for the ``ta 8'' instruction. .IP "\fBipex -r massivedump.pcp -e '\&time > 04:00:00' Process packets from the file ``massivedump.pcp'' and only process the packets that were captured after 4:00 AM. .IP "\fBipex -r massivedump.pcp -e '\&date < 2003-12-01' Process packets from the file ``massivedump.pcp'' and only process the packets that were captured before December first, 2003. .IP "\fBipex -r raw.cp -e '\&date time 2003-12-01 5:00:00 >< 2003-12-02 6:00:00' Process packets from the file ``raw.cp'' and only process the packets that were captured after 5:00 AM on December first, 2003 and before 6:00 AM December the second 2003. .IP "\fBipex -x -E '\&[0-9]{3}-[0-9]{4}'" Capture all packets with North American phone numbers in them. Once the packet has been matched dump in with a formatted hexadecimal dump. .IP "\fBipex port 6667" Capture all packets going to and coming from IRC .IP "\fBipex -E 'user|pass' port 21" Process all packets going to or coming from port 21 which contain the text "user" .IR OR "pass". NOTE: the string .B Password would also match this extended regular expression. .IP "\fBipex icmp[0] == 8 or icmp[0] == 0" Process all .IR icmp ECHO requests or replies. .IP "\fBipex -t '3d 1m 43' tcp" Process all TCP packets for 3 days, 1 minute and 43 seconds. After this time period has exceeded; exit gracefully. .IP "\fBipex -r packet.dump udp" Do not open the network interface, read all udp packets from the file .IR packet.dump. This file can be created from the .BR ipex .IR \-w option or the .IR tcpdump(1) .IR \-w option. .SH "SEE ALSO" pcap(3), ipex(1), bpf(4), re_format(7), regex(3), .br .ti tcpdump(1), ascii(7) .SH AUTHORS The following people have made ipex a possibility: .LP o Core: Christian S.J. Peron (maneo@bsdpro.com) o glaive o Daniel B. Hemmerich (code@psu.edu) .SH BUGS None known. Send bugs or source code patches to (maneo@bsdpro.com) .LP Currently ipex does not process IPv6 packets. It is still capable of dumping them in hexadecimal however. .br