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:
- = (equals)
- < (less than)
- > (greater than)
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:
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 |
| ETH | Ethernet (ie. DIX ethernet) | LEN, HLEN, DLEN, SRC, DST, SD, SD:1, SD:2, ETYPE |
| 802.3 | IEEE CSMA/CD (ie. "ethernet" with Length field) | HLEN, DLEN, SRC, DST, SD, SD:1, SD:2 |
| LLC | 802.2 Logical Link Control | LEN, DLEN, SRC, DST, SD, SD:1, SD:2, C |
| SNAP | 802.2 Sub-Network Access Protocol | LEN, DLEN, ORG, ETYPE |
| ARP | Address Resolution Protocol | LEN, HLEN |
| RARP | Reverse ARP | LEN, HLEN |
| IP | Internet Protocol v4 | LEN, HLEN, DLEN, SRC, DST, SD, SD:1, SD:2, F |
| IPv6 | Internet Protocol v6 | LEN |
| ICMP | Internet Control Message Protocol | LEN, HLEN, DLEN, TYPE, CODE |
| TCP | Transmission Control Protocol | LEN, HLEN, DLEN, SRC, DST, SD, SD:1, SD:2, F |
| UDP | User Datagram Protocol | LEN, HLEN, DLEN, SRC, DST, SD, SD:1, SD:2 |
| IGMP | IGMP | LEN |
| OSPF | OSPF | LEN |
| IPX | the Novell Netware family of protocols (includes NetBios) | LEN |
| IP#n | arbitrary IP protocol | none |
- 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:
| LEN | PDU length |
| HLEN | length of PDU header |
| DLEN | length of PDU user-data |
| SRC | source address - syntax depends on protocol |
| DST | destination address - syntax depends on protocol |
| SD | source or destination address must match parameter value |
| SD:1 | source or destination address, but not both, must match parameter value |
| SD:2 | source and estination address must match parameter value (shorthand for SRC and DST parameters combined) |
| ETYPE | Ether Type (eg. 2048 means IP - see RFC-1700) |
| TYPE | ICMP Type |
| CODE | ICMP Code |
| C | LLC Control field |
| ORG | SNAP Organisation-ID field |
| F | Protocol 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:
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.