IPEX(1)

NAME
ipex - packet examination utility

SYNOPSIS
ipex [-bdqvxDGHLNOX] [-c count] [-f file] [-i iface] [-o file] [-r regexp] [-t time] [-u uid] [-w file] [-B file] [-F file] [-P op=arg] [ expression ]

DESCRIPTION
This manual page describes the ipex packet auditing utility. ipex is similar to tcpdump or ngrep. It allows you to dump the contents of packets in hexadecimal or plain text. ipex allows you to inspect packets by binary signature, regular expression, pcap expression, process ID and real or effective user ID.

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.

OPTIONS

-b  Launch ipex into the background. A diagnostic message will be written to standard out and the PID will be written to /var/run/ipex.pid. Because the process is demonized the standard file descriptors get closed; thus you must specify an out file using the -o option.

-ccount
    Capture count packets then exit. The default is 0. This means that ipex will capture packets until its interrupted with a signal.

-d  When 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 /dev/bpf using an 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 -d switch causes the contents of this structure to be dumped. This feature would typically be used when debugging pcap(3) or bpf(4).

-ffile
    Pathname to the expression file. This file would contain pcap filter logic. If you use this option do not specify any pcap expressions on the command line.

-iiface
    Specify an alternate network interface to capture the packets from. If no interface is specified ipex will search the system interface list for the lowest numbered, configured and up interface (excluding loopback).

-ofile
    Rather then printing information to standard out; print data to the specified file named file. If this file does not exist, ipex will create it. This option should always be used with the -b option.

-q  Do not officially put the interface into promiscuous mode. By default this switch is turned off and the interface goes into promiscuous mode.

-rregexp
    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 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. If you want to use a ``grep'' like ``classical'' RE specify the -G flag on the command line. Further reading on POSIX 1003.2 regular expressions can be found in the re_format(7) manual page.

-ttime
    Capture packets for time amount of time. time can be suffixed by d for days, h for hours, m for minutes or s for seconds. If no suffix is given, seconds is assumed. The default for this option is eternity.

-uuid
    When running 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 numeric ID of the preferred user.

-v  Dump the current 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.

-wfile
    Instead of opening the network interface, you can read raw pcap trace files from the file specified by file. This pcap trace file can be generated with the -F option. It is also compatible with the tcpdump(1) -r option. If the specified file is ``-'' then standard-in is assumed.

-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 isgraph(3) then a ``.'' dot is printed in the characters place. To view the characters that would be processed by isgraph(3) see the man page.

-Bfile
    ipex implements a very elementary and general purpose Network Intrusion Detection functionality. In this file you would specify ipex signatures or sequences of binary bytes which ipex will scan each matched packet for. If one of these binary sequences are located in the packet; it can log to syslogd(8) using various log levels as specified by the signature. Otherwise ipex will generate a generic diagnostic message to whichever out stream its writing the packets to. Please read the TINY IDS section of this manual for more information on this feature.

-D  Dump the entire packet (including the link layer) in hexadecimal. No parsing or processing of the packet occurs. Its a straight hex dump of the ethernet or link layer frame.

-Ffile
    Write raw packets to file rather then processing and writing them to some out-put stream. Packets can later be processed with ipex, tcpdump(1) or any other program that can process pcap trace files. If you want to use ipex to process the trace file, use the -w option. If file is ``-'' then standard-out is assumed.

-G  -G disables the EXTENDED RC bit. You would use this option if you wanted to use grep(1) style regexps to match patterns of text in the packets.

-H  This option will print just the headers of the packets. It considered to throw 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.

-L  Display the physical link addresses of packets. The addresses are displayed in the form that ether_ntoa(3) returns them in. Which is an ASCII representation of an Ethernet address.

-N  Do not use gethostbyaddr(3) to resolve the IP addresses to their hostnames. If this flag is specified on the command line; ipex will not resolve the IP address. Thus src and dst addresses will be expressed in xxx.xxx.xxx.xxx (Internet standard `.') notation.

-O  Run the packet-matching code optimizer. This option should be enabled by default and soon will be.

-Pop=arg
    Open /dev/mem and scan all the process for a given op using arg as the argument for the op. Supported op's are uid, ruid, and 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 -P pid=44556 on the command line. Arbitrarily for uid and ruid.

-X  Display ip addresses in hexadecimal. This flag was created mostly for debugging purposes, however it is useful when you require high speed packet dumps. Naturally less time is taken by the ip conversion process.

expression
    selects which packets will be dumped. If no expression is given, all packets on the net will be dumped. Otherwise, only packets for which expression is `true' will be dumped.

    The expression consists of one or more primitives. Primitives 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 foo', `net 128.3', `port 20'. If there is no type qualifier, host is assumed.

    dir qualifiers specify a particular transfer direction to and/or from id. Possible directions are src, dst, src or dst and src and dst. E.g., `src foo', `dst net 128.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 restrict the match to a particular protocol. Possible protos are: ether, fddi, tr, ip, ip6, arp, rarp, decnet, lat, sca, moprc, mopdl, iso, esis, isis, icmp, icmp6, tcp and udp. E.g., `ether src foo', `arp net 128.3', `tcp port 21'. If there is no proto qualifier, all protocols consistent with the type are assumed. E.g., `src foo' means `(ip or arp or rarp) src foo' (except the latter is not legal syntax), `net bar' means `(ip or arp or rarp) net bar' and `port 53' means `(tcp or udp) port 53'.

    [`fddi' is actually an alias for `ether'; the parser treats them identically as meaning ``the data link level used on the specified network interface.'' FDDI headers contain Ethernet-like source and destination addresses, and often contain Ethernet-like packet types, so you can filter on these FDDI fields just as with the analogous Ethernet fields. FDDI headers also contain other fields, but you cannot name them explicitly in a filter expression.

    Similarly, `tr' is an alias for `ether'; the previous paragraphs statements about FDDI headers also apply to Token Ring headers.]

    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 foo and not port ftp and not port ftp-data'. To save typing, 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'.

    Allowable primitives are:

    dst host host
        True if the IPv4/v6 destination field of the packet is host, which may be either an address or a name.

    src host host
        True if the IPv4/v6 source field of the packet is host.

    host host
        True if either the IPv4/v6 source or destination of the packet is host. Any of the above host expressions can be prepended with the keywords, ip, arp, rarp, or ip6 as in:
        ip host host
        which is equivalent to:
        ether proto \ip and host host
        If host is a name with multiple IP addresses, each address will be checked for a match.

    ether dst ehost
        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.) This syntax does not work in IPv6-enabled configuration at this moment.

    dst net net
        True if the IPv4/v6 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 IPv4/v6 source address of the packet has a network number of net.

    net net
        True if either the IPv4/v6 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. Note that this syntax is not valid for IPv6 net.

    net net/len
        True if the IPv4/v6 address matches net a netmask len bits wide. May be qualified with src or dst.

    dst port port
        True if the packet is ip/tcp, ip/udp, ip6/tcp or ip6/udp and has a destination 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:
        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 protocol type protocol. Protocol can be a number or one of the names icmp, icmp6, igmp, igrp, pim, ah, esp, udp, or tcp. Note that the identifiers tcp, udp, and icmp are also keywords and must be escaped via backslash (\), which is \\ in the C-shell. Note that this primitive does not chase protocol header chain.

    ip6 proto protocol
        True if the packet is an IPv6 packet of protocol type protocol. Note that this primitive does not chase protocol header chain.

    ip6 protochain protocol
        True if the packet is IPv6 packet, and contains protocol header with type protocol in its protocol header chain. For example,
        ip6 protochain 6
        matches any IPv6 packet with TCP protocol header in the protocol header chain. The packet may contain, for example, authentication header, routing header, or hop-by-hop option header, between IPv6 header and TCP header. The BPF code emitted by this primitive is complex and cannot be optimized by BPF optimizer code in ipex, so this can be somewhat slow.

    ip protochain protocol
        Equivalent to ip6 protochain protocol, but this is for IPv4.

    ether broadcast
        True if the packet is an Ethernet broadcast packet. The ether keyword is optional.

    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.

    ether multicast
        True if the packet is an Ethernet multicast packet. The ether keyword is optional. This is shorthand for `ether[0] & 1 != 0'.

    ip multicast
        True if the packet is an IP multicast packet.

    ip6 multicast
        True if the packet is an IPv6 multicast packet.

    ether proto protocol
        True if the packet is of ether type protocol. Protocol can be a number or one of the names ip, ip6, arp, rarp, atalk, aarp, decnet, sca, lat, mopdl, moprc, or iso. Note these identifiers are also keywords and must be escaped via backslash (\). [In the case of FDDI (e.g., `fddi protocol arp'), the protocol identification comes from the 802.2 Logical Link Control (LLC) header, which is usually layered on top of the FDDI header. Tcpdump assumes, when filtering on the protocol identifier, that all FDDI packets include an LLC header, and that the LLC header is in so-called SNAP format. The same applies to Token Ring.]

    decnet src host
        True if the DECNET source address is host, which may be an address of the form ``10.123'', or a DECNET host name. [DECNET host name support is only available on Ultrix systems that are configured to run DECNET.]

    decnet dst host
        True if the DECNET destination address is host.

    decnet host host
        True if either the DECNET source or destination address is host.

    ip, ip6, arp, rarp, atalk, aarp, decnet
        R, iso" Abbreviations for:
        ether proto p
        where p is one of the above protocols.

    lat, moprc, mopdl
        Abbreviations for:
        ether proto p
        where p is one of the above protocols. Note that ipex does not currently know how to parse these protocols.

    vlan [vlan_id]
        True if the packet is an IEEE 802.1Q VLAN packet. If [vlan_id] is specified, only true is the packet has the specified vlan_id. Note that the first vlan keyword encountered in expression changes the decoding offsets for the remainder of expression on the assumption that the packet is a VLAN packet.

    tcp, udp, icmp
        Abbreviations for:
        ip proto p or ip6 proto p
        where p is one of the above protocols.

    iso proto protocol
        True if the packet is an OSI packet of protocol type protocol. Protocol can be a number or one of the names clnp, esis, or isis.

    clnp, esis, isis
        Abbreviations for:
        iso proto p
        where p is one of the above protocols. Note that ipex does an incomplete job of parsing these 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 accessors. To access data inside the packet, use the following syntax:
        proto [ expr : size ]
        Proto is one of ether, fddi, tr, ip, arp, rarp, tcp, udp, icmp or ip6, and indicates the protocol layer for the index operation. Note that tcp, udp and other upper-layer protocol types only apply to IPv4, not IPv6 (this will be fixed in the future). 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 un-fragmented 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 intervening 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 concatenation have equal precedence and associate left to right. Note that explicit and tokens, not juxtaposition, are now required for concatenation.

    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 ipex as either a single argument or as multiple arguments, whichever is more convenient. Generally, if the expression contains Shell meta-characters, it is easier to pass it as a single, quoted argument. Multiple arguments are concatenated with spaces before being parsed.

TINY IDS

ipex has the capability of acting as a very basic and general purpose Intrusion Detection System. What can it do? It can scan packets for specific binary signatures. What constitutes a signature? Basically a signature is a sequence of values. For the most part these values would match a pattern or sequence of values in known exploit payloads and or known virus binaries.

You keep these signatures in a file. You can instruct ipex to open a signature file and compile it's internal watch dog for these signatures with the -B option. Here is the format of the signature string ipex will look for in this file:

values|alert message|log-level|signature id

values
    This portion of the signature string would normally contain the hexadecimal values or binary sequence that ipex would be watching for in the payload section of the packets.

alert message
    When the signature is matched, ipex will generate a brief alert message based on this portion of the signature string. This string can not contain any ``|'' characters as this character acts as a delimiter for the signature string.

log-level
    The log level is an integer. The value of this integer will specify which level ipex will log at. ipex will log to syslogd(8) unless the value is 0. If the value is zero; then ipex will not notify the system log and generate a debug message to whatever output stream ipex is dumping to. A log level of 1 will notify syslog using the LOG_ALERT level. Log level 2 will notify the syslog using the LOG_ERR level, 3 the LOG_WARNING level; 4 the LOG_INFO and finally the highest being 5 which will log using the LOG_SECURITY level.

signature id
    This section of the signature string contains the ``signature id'' of the signature. This should be a unique identifier for the signature itself.

SIGNATURE FORMAT

This section of the manual documents the legal ipex signature format. After you generate your signature file you will need to run ipex with the -B option using the signature file as an argument to invoke the MINI-IDS functionality.

9090 9090|x86_opcode - possible x86 nop instructions|5|1
    This signature looks for possible traces of the x86 nop instruction. When you disassemble the nop instruction to the lowest possible level of abstraction; you will see that the nop opcode has a value of 90 (base 16). If ipex encounters 4 adjacent nop instructions, it will generate an alert using the "x86_opcode - possible x86 nop instructions" string. The alert will be made at the LOG_SECURITY level.

cd80|x86_opcode - possible x86 int 80 instruction|0|2
    This signature would look for the int $0x80 opcodes in a packet. If it encountered the opcode it would generate an alert message using the "x86_opcode - possible x86 int 80 instruction" string. This log would not be written to the system log at all. Just a message would be printed to the out-put stream ipex was dumping the processes packets to.

FORMAT

This section of the manual documents the output format that ipex uses when processing packets. The hexadecimal dumps have been omitted from the output format discussion for clarity reasons. This document will outline the TCP/UDP/ICMP/IGMP protocols.

  TCP
00:12:59.149336 src:port >> dst.port tcp A seq=n ack=n win=n (DF)

The first field is the time-stamp, followed by the source host/port and destination host/port. Next the protocol is displayed. For TCP we display the set flags followed by the sequence, acknowledgment number, window size and finally IP fragment status. Control Bits or TCP flags: 6 bits (from left to right):
    U: Urgent Pointer field significant
    A: Acknowledgment field significant
    P: Push Function
    R: Reset the connection
    S: Synchronize sequence numbers
    F: No more data from sender

  UDP/ICMP/IGMP
00:14:15.272532 src:port >> dst.port proto (DF)

The first field is the time-stamp, followed by the source host/port and destination host/port. Next the protocol is displayed. Next we do a hexadecimal dump and display the fragment status. Eventually more specific parsing of packets will occur.

  IP Fragmentation

Fragmented Internet datagrams are printed as

    (frag id:size@offset+)
    (frag id:size@offset)

(The first form indicates there are more fragments. The second indicates this is the last fragment.)

Id is the fragment id. Size is the fragment size (in bytes) excluding the IP header. Offset is this fragment's offset (in bytes) in the original datagram.

A packet with the IP don't fragment flag is marked with a trailing (DF).

EXAMPLES

Here are some examples using ipex, from simple examples to more esoteric. For more information regarding regular expressions you should consult your 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 ipex to be a network protocol debugger. Please do not abuse this program.

ipex -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 src host host to the ruleset.

ipex '(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.

ipex -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.

ipex -xG -r '[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.

ipex port 6667
    Capture all packets going to and coming from IRC

ipex -r 'user|pass' port 21
    Process all packets going to or coming from port 21 which contain the text "user" OR "pass". NOTE: the string Password would also match this extended regular expression.

ipex icmp[0] == 8 or icmp[0] == 0
    Process all icmp ECHO requests or replies.

ipex -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.

ipex -w packet.dump udp
    Do not open the network interface, read all udp packets from the file packet.dump. This file can be created from the ipex -F option or the tcpdump(1) -w option.

SEE ALSO
pcap(3), ipex(1), bpf(4), re_format(7), regex(3),
kill(1), syslogd(8), ascii(7), ioctl(2)

AUTHORS

 o Founder - C.S. Peron (maneo@bsdpro.com)
 o Lead Developer - C.S. Peron
 o Developer - Daniel B. Hemmerich (code@psu.edu)
 o
 o Development site: http://ipex.sourceforge.net

LIBPCAP
The original libpcap can be downloaded from ftp://ftp.ee.lbl.gov/libpcap.tar.Z). However the official maintainer is now http://www.tcpdump.org

BUGS
None known. Send bugs or source code patches to (maneo@bsdpro.com)

Currently ipex does not process IPv6 packets. It is still capable of dumping them in hexadecimal however.