Previous       Contents       Next

Filter Expressions


Syntax

The Network-I filter expressions are based on a flexible notation that allows complex capture criteria to be specified.

A filter expression consists of a set of rules, and the basic building block of a rule (known as an atom) has the generic format:
(Protocol-ID [Param1-Spec [Param2-Spec ...]])
ie. a protocol identifier, qualified by zero or more parameters

Param-Spec describes a protocol parameter, and is of the form:
Param-Name op Param-Value
where op can be any of:

although not every parameter supports all three operators.
Different protocols support different filter parameters, and neither the protocol-ID nor the parameter names are case-sensitive.

Compound rules can be built up, by combining atoms and nested sub-rules, using the usual Boolean operators:

  • & (AND)
  • | (OR)
  • ^ (NOT)
Atoms are bracketed in round brackets, and expressions of arbitrary complexity can be built up.

The negation operator, ^, can be placed before Protocol-ID, or Param-Spec, or an entire rule (compound or simple).
If placed in front of Protocol-ID, no parameters are permitted in that rule, and it is equivalent to saying "reject any packets that contain the specified protocol".
If placed in front of a rule (ie. before the opening bracket), it simply inverts the result of evaluating that rule.
Similiarly, negating a parameter-spec inverts the result of evaluating that parameter.

The valid protocol-IDs, along with their supported parameters are:

ID

Protocol

Parameters

ETHEthernet (ie. DIX ethernet)LEN, HLEN, DLEN, SRC, DST, SD, SD:1, SD:2, ETYPE
802.3IEEE CSMA/CD (ie. "ethernet" with Length field)HLEN, DLEN, SRC, DST, SD, SD:1, SD:2
LLC802.2 Logical Link ControlLEN, DLEN, SRC, DST, SD, SD:1, SD:2, C
SNAP802.2 Sub-Network Access ProtocolLEN, DLEN, ORG, ETYPE
ARPAddress Resolution ProtocolLEN, HLEN
RARPReverse ARPLEN, HLEN
IPInternet Protocol v4LEN, HLEN, DLEN, SRC, DST, SD, SD:1, SD:2, F
IPv6Internet Protocol v6LEN
ICMPInternet Control Message ProtocolLEN, HLEN, DLEN, TYPE, CODE
TCPTransmission Control ProtocolLEN, HLEN, DLEN, SRC, DST, SD, SD:1, SD:2, F
UDPUser Datagram ProtocolLEN, HLEN, DLEN, SRC, DST, SD, SD:1, SD:2
IGMPIGMPLEN
OSPFOSPFLEN
IPXthe Novell Netware family of protocols (includes NetBios)LEN
IP#narbitrary IP protocolnone

  • In the expression IP#n, n is an /etc/protocols style number, which specifies an arbitrary protocol layered above IP.
  • Other protocols (eg. those layered above ethernet or TCP/IP) can be specified by means of the parameters associated with one of the above Protocol-IDs.

The parameters are:
LENPDU length
HLENlength of PDU header
DLENlength of PDU user-data
SRCsource address - syntax depends on protocol
DSTdestination address - syntax depends on protocol
SDsource or destination address must match parameter value
SD:1source or destination address, but not both, must match parameter value
SD:2source and estination address must match parameter value (shorthand for SRC and DST parameters combined)
ETYPEEther Type (eg. 2048 means IP - see RFC-1700)
TYPEICMP Type
CODEICMP Code
CLLC Control field
ORGSNAP Organisation-ID field
FProtocol Flags - syntax depends on protocol


NOTES:

  • Numeric parameter values must always be specified in decimal.
  • Ethernet/802.3 addresses are specified as either a colon-separated sequence of 6 hexadecimal bytes, or as an /etc/ethers name. The special values, B, and M may also be used, to signify the broadcast address, or any multicast address, respectively.
  • IP addresses can be specified as either an IP address or a hostname, and in both cases, may be suffixed by /netmask where netmask is the number of significant leading bits
    eg. 158.152.0.0/16 specifies a class B network number.
  • TCP/UDP addresses may be specified as either a port number, or an /etc/services name.
  • ICMP types can be entered as either a numeric value, or as one of these symbolic names: echoreq, echorsp, unreach, redir, srcquench, rtradv (router advertisement), rtrwant (router solicitation).
    You can also use echo as a synonym for echoreq, echorep for echorsp, quench for srcquench, and rtrsol for rtrwant.
  • ICMP codes can be entered as a numeric value, or as one of these symbolic names (depends on ICMP type):
    • Type = Destination-Unreachable: net, host, proto, port, needfrag, unknown-net, unknown-host.
      prot and protocol are synonyms for proto, as is frag for needfrag, netbad for unknown-net and hostbad for unknown-host.
    • Type = Redirect: net, host.
  • When used with the protocol-ID, IP, the Protocol-Flags parameter can only contain the value, F (ie. F=F). This means only accept IP datagrams that are a fragment, ie. reject unfragmented datagrams.
  • When used with the protocol-ID, TCP, the Protocol-Flags parameter is a string, consisting of one or more of the following 6 characters, each of which represents a TCP flag: U (URG), A (ACK), P (PSH), R (RST), S (SYN), F (FIN).
    Each character in the string can also be optionally preceded by ^ to negate it, and the final character in the string may be *.
    The presence of a letter in the flags parameter means that only TCP flags containing that flag will be accepted. eg. F=S means accept connection requests, or responses (both contain the SYN flag) and F=SA means only accept responses to connection requests).
    The presence of * at the end means any flags not explicitly specified must be present in the TCP packet. The presence of ^ before any letter means reject any packets containing that flag, and ^ can also be applied to the wildcard, *. eg. F=S^* only matches connection requests.
    As usual, the meaning of the entire parameter can be inverted, by prefixing the parameter name with ^, eg. ^F=S^* matches TCP packets that are not a connection request.
  • Some parameters exclude each other, eg. SRC and SD cannot both appear in the same atom. Similiarly some parameters qualify each other, eg. ICMP codes can only be specified if the type was also specified.

Examples

These filter expressions all mean the same thing, and capture only those packets that contain an IP datagram (eg. ARP, IPX or IPv6 packets would be rejected).
  • (IP)
  • ((IP))
  • IP ... brackets not needed, because rule consists of a single atom.
These filter expressions all mean the same thing, and capture only those packets that don't contain an IP datagram (eg. ARP, IPX or IPv6 packets would be accepted).
  • ^(IP)
  • (^IP)
  • (^(IP))
  • ^IP ... brackets not needed, because rule consists of a single atom.
These filter expressions all mean the same thing, and capture only those packets that contain an IP datagram, with a source address from the specified subnet (10.2.x.x)
  • (IP SRC=10.2.0.0/16)
  • ((IP SRC=10.2.0.0/16))
  • IP SRC=10.2.0.0/16 ... brackets not needed, because rule consists of a single atom.
Assuming that you have the class C network, 194.152.159.0, the following filters (which mean the same thing) will only capture packets that are to or from the outside world.
When combined with niftap -r frq:1, such a filter would indicate whether external traffic is at a level which might be pushing your leased line or external router to their limits.
  • (IP SRC=194.152.159.0/24 ^DST=194.152.159.0/24) | (IP ^SRC=194.152.159.0/24 DST=194.152.159.0/24)
  • (IP SD:1=194.152.159.0/24) ... more efficient
Here is an example of two filters which appear similiar, but are completely different in meaning.
  • ^(UDP SD=2049) ... reject UDP packets to/from port 2049, but accept all others (ie. both UDP and non-UDP)
  • (UDP ^SD=2049) ... reject all non-UDP packets, and all UDP packets to/from port 2049.
If you have the class C network, 194.152.159.0, the following filter will record all outgoing web sessions from your site.
This example makes it easy to see how you might construct a filter which captured all incoming web sessions from the outside world (or even from within the same LAN).
  • ((IP ^DST=195.63.92.0/24) & (TCP DST=80)) | ((IP ^SRC=195.63.92.0/24) & (TCP SRC=80))
Some other examples
  • (IP ^DST=195.63.92.0/24) & (TCP DST=80 F=S^*) ... capture all outgoing web connections, on 195.63.92.x (ie. just the connection-request packets, not the subsequent traffic on that connection).
  • (^IP) & (UDP) ... reject everything (since UDP is always layered above IP).
  • (TCP F=S^*) | (TCP F=F) | (TCP F=R) ... select TCP connect and disconnect packets only - good first step, in analysing a large log file.
  • (IP) & ((UDP SD=53) | (TCP SD=53)) ... this will capture all DNS traffic, but the (IP) atom is redundant, and therefore makes the filter less efficient.
  • (UDP SD=53) | (TCP SD=53) ... more efficient form of the above.
  • (TCP SD=21) & (TCP ^dlen=0) ... capture FTP commands (combine with nifpan -v1 -l200, for easy viewing).

Short-Hand Filter

The basic shorthand formats are:
  • host:port
  • host
  • :port
In each case, the host can be a dotted IP address or a hostname, and can be suffixed by /netmask, just like the source/dest params for the IP protocol, in the regular filter notation.
The port can also be a number or an /etc/services style name, just like the source/dest params for TCP or UDP, in the regular filter notation. If you specify a port number, it is applied to both TCP and UDP. If you supply an /etc/services name, it is applied to both TCP and UDP if possible, else just the one for which it is listed in /etc/services.
Both the host and port can be individually negated, by prefixing with ^.

This allows users to enter simple commands, such as:
niftap | nifpan -n alpha:80

The best way to verify what a short-hand filter translates to, is to run the following niftap command ...
niftap -rtest:1 short-hand-filter > /dev/null
... and then interrupt it immediately. If you now examine the newly created file, test, it will contain the filter expression in the regular notation.


Previous       Contents       Next