REST APIs : Observer REST : Understanding the filter syntax
  
Understanding the filter syntax
 
Page Contents
App
IP Pairs
IP Addresses
MAC Pairs
MAC addresses
Port
VLAN Tag
Observer filter
Understanding patterns
Using filters in your REST API request allows you to extract the data that you want, whether by IP Pairs, IP Address, L4 Port, VLAN tags, or combining filters.
Some filter examples are provided here. More examples are given in the sections for IP Pair, IP address, Port, and VLAN Tag.
"filter": "ip 10.1.16.32 OR (ip 10.1.16.20 AND port udp/53)"
"filter": "(ip 10.1.16.20 AND port udp/53)"
"filter": "ip 10.1.16.32 OR ip 10.1.16.20[udp/53] OR port tcp/80"
"filter": "(ippair 10.1.16.20<->10.1.23.114" AND (port udp/53 OR port tcp/80)) OR (ippair 10.1.16.20<->10.1.23.201" AND (port udp/53 OR port tcp/80))"
"filter": "vlan 1470 OR vlan outer/1865"
App
Applications can be filtered using the app or applicationkeyword.
 
Filter strings support groupings. To group options together, you must use parentheses “( )”. You may also use these keywords:
AND
OR
To exclude an application, you must use the ! character. Currently unsupported is the use of the ! character on groupings and the NOT keyword.
 
 
CIFS
"filter": "app CIFS/SMB"
 
 
HTTP
"filter": "app HTTP"
 
 
WebSphere MQ
"filter": "app 'WebSphere MQ'"
Be sure to use single quotes to enclose the space.
 
 
More examples
See Apex Filters.
 
IP Pairs
IP Pairs can be filtered using the ippair keyword. IPv4 or IPv6 addresses may be filtered using the ‘from,’ ‘to,’ or both addresses or a range of addresses.
 
Filter strings support groupings. To group options together, you must use parentheses “( )”. You may also use these keywords:
AND
OR
Valid direction arrows are ->, <-, and >-<. Each side of the pair supports a single address or a range of addresses with ranges specified with a - (hyphen). Ports are optional on each address and support single TCP/UDP/SCTP ports or port ranges.
To exclude a IP Pair group, you must use the ! character. Currently unsupported is the use of the ! character on groupings and the NOT keyword.
IP addresses may be in CIDR format, such as 192.168.1.10/24.
 
 
IPv4 address pair traffic in both directions
"filter": "ippair 10.1.16.20<->10.1.23.114"
 
 
IPv4 address pair traffic from addr1 to addr2
"filter": "ippair 10.1.16.20->10.1.23.114"
 
 
IPv4 address pair traffic to addr1 from addr2
"filter": "ippair 10.1.16.20<-10.1.23.114"
 
 
IPv4 address pair traffic in both directions with port on addr1
"filter": "ippair 10.1.16.20[tcp/80]<->10.1.23.114"
 
 
IPv4 address pair traffic in both directions with port on addr2
"filter": "ippair 10.1.16.20<->10.1.23.114[tcp/80]"
 
 
IPv4 address pair traffic in both directions with port on both addresses
"filter": "ippair 10.1.16.20[tcp/55428]<->10.1.23.114[tcp/80]"
 
 
IPv4 address pair traffic from addr1 to addr2 with port range on addr1
"filter": "ippair 10.1.16.20[tcp/80-100]->10.1.23.114"
 
 
Ipv4 address pair traffic in both directions with addr1 range with ports
"filter": "ippair 10.1.20.40-10.1.20.49[tcp/62033]<->176.32.103.205[tcp/443]"
 
 
IPv4 address range pair traffic in both directions with port ranges
"filter": "ippair 10.1.20.40-10.1.20.49[tcp/60000-62033]<->176.32.0.1-176.32.255.255[tcp/400-500]"
 
IP Addresses
IP addresses can be filtered using the ip keyword. IPv4 or IPv6 addresses may be used. Ports are optional on each address and support single TCP/UDP/SCTP ports or port ranges.
 
IP addresses may be in CIDR format, such as 192.168.1.10/24.
 
 
Single IPv4 address
"filter": "ip 10.1.20.50"
 
 
Single IPv4 address with port
"filter": "ip 10.1.20.50[tcp/80]"
 
 
Single IPv4 address with port range
"filter": "ip 10.1.20.50[tcp/80-100]"
 
 
IPv4 address range
"filter": "ip 10.1.20.1-10.1.20.255"
 
 
IPv4 address range with port
"filter": "ip 10.1.20.1-10.1.20.255[tcp/80]"
 
 
IPv4 address range with port range
"filter": "ip 10.1.20.1-10.1.20.255[sctp/60000-61000"]
 
MAC Pairs
MAC Pairs can be filtered using the macpair keyword. Addresses may be filtered using the ‘from,’ ‘to,’ or both addresses or a range of addresses.
 
MAC Pairs address filters cannot include ports, only addresses.
 
 
MAC address pair traffic in both directions
"filter": "macpair 7C:FA:DF:9A:B1:4C<->34:DB:FD:35:6f:52"
 
 
MAC address pair traffic from addr1 to addr2
"filter": "macpair 7C:FA:DF:9A:B1:4C->34:DB:FD:35:6f:52"
 
 
MAC address pair traffic to addr1 from addr2
"filter": "macpair 7C:FA:DF:9A:B1:4C<-34:DB:FD:35:6f:52"
 
 
MAC address pair traffic from a range from addr2
The - character is used to separate ranges. When creating a range, the address before - must be lower than or occur before the ending address in the range. For example, FF:FF:FF:FF:FF:FF-FE:FF:FF:FF:FF:FF will fail.
"filter": "macpair 7C:FA:DF:9A:B1:4C-7C:FA:DF:9A:B1:FF<-34:DB:FD:35:6f:52"
 
MAC addresses
MAC addresses can be filtered using the mac keyword. Addresses may be filtered using the ‘from,’ ‘to,’ or both addresses or a range of addresses.
 
MAC address filters cannot include ports, only addresses.
 
 
MAC address
"filter": "mac 7C:FA:DF:9A:B1:4C"
"filter": "mac 34:DB:FD:35:6f:52"
"filter": "mac 33:33:00:00:00:FB"
 
 
MAC address range
The - character is used to separate ranges. When creating a range, the address before - must be lower than or occur before the ending address in the range. For example, FF:FF:FF:FF:FF:FF-FE:FF:FF:FF:FF:FF will fail.
"filter": "mac 7C:FA:DF:9A:B1:4C-7C:FA:DF:9A:B1:FF"
"filter": "mac 00:0F:E5:03:7A:8F-00:50:56:A1:6F:9F"
 
Port
Layer 4 ports may be used to filter content extracted by REST API calls using the port keyword. TCP/UDP/SCTP ports are supported. Port ranges must be separated using a - (hyphen).
 
Single TCP port filter
"filter": "port tcp/80"
 
 
TCP port range filter
"filter": "port tcp/80-100"
 
 
Single UDP port filter
"filter": "port udp/53"
 
 
UDP port range filter
"filter": "port udp/5500-9000"
 
 
Single SCTP port filter
"filter": "port sctp/90"
 
 
SCTP port range filter
"filter": "port sctp/60000-65000"
 
VLAN Tag
VLAN tags may be used to filter content extracted by REST API calls using the vlan keyword. When multiple VLAN tags are present, the location can be specified.
 
Innermost and outermost refer to the location of the VLAN tag. The outermost tag follows the MAC address. The innermost tag is closest to the payload. For packets that have a single VLAN tag the tag will match regardless of the specified location of the tag.
 
 
Filters the innermost VLAN tag
"filter": "vlan 1470"
 
 
Filters the outermost VLAN tag
"filter": "vlan outer/1470"
 
 
Filters the innermost VLAN tag
"filter": "vlan inner/1470"
 
Observer filter
Filters that you built using Observer may be used by REST API calls using the obsfilter keyword.
 
Like IP Pairs, which can be grouped together, so may “Observer filters.” Observer filters can be pre-built, making them ideal when you need to use a complex filter. Also like the IP Pairs filter you may use groupings. To group options together, you must use parentheses “( )”. You may also use these keywords:
AND
OR
You must exclude a single Observer filter by using the ! character. Currently unsupported is the use of the NOT keyword preceding the Observer filter.
An Observer filter name may contain any characters that are valid in a Windows Registry subkey name, including the double quote (") character. The parameter for an obsfilter keyword must also be quoted; any quotes that appear in the filter name must be escaped with a \ character, which itself must also be escaped, as in the last example.
 
 
Single filter named “Multiple Addresses”
"filter": "obsfilter \"Multiple Addresses\""
 
 
Combining filters using OR
"filter": "obsfilter \"Complex Filter\" OR \"Multiple Addresses\""
 
 
A filter with quotes in its name
"filter": "obsfilter \\\"A filter with quotes in its name\\\""
 
Understanding patterns
Several pattern filters are available so you can extract just the packets you need. This is especially useful when investigating specific issues, such as when detecting a network intrusion.
pattern|patternSensitive|patternBin|patternHex|
patternRegex search pattern[(ip|tcp|
tcpData|udp|udpData:)#|#-#]
A search pattern may be ASCII (default), binary, or hex. It may start from an offset. The offset can be a specific location or range from the beginning of the:
Undefined: Packet (default, no packet component is specified)
ip: IP header
tcp: TCP header
tcpData: TCP data
udp: UDP header
udpData: UPD data
Any offset looks only at the specified location or range (if provided). For example, if you specify an offset of [14] the filter only searches byte 14 for the first character of the search pattern.
If you specify the offset range [14-20] the filter searches at byte 14 to byte 20 for the first character of the search pattern. The search may not necessarily end at byte 20; byte 20 is the last starting location. For instance, if your search is HTTP/1.1 (an 8-byte string) the bytes 14 through 20 are searched for H. If the H is found in any of those locations the next byte is searched for T and so on until the second 1 is found (which could be on byte 27 if the H was found on byte 20) or pattern stops matching.
If you want to search from a specific offset to the end of the packet, then use 32767 for the ending offset. For example, [14-32767].
ASCII patterns may be case-sensitive. The pattern filters are case-insensitive. If you need a case-sensitive use patternSensitive.
Search patterns that contain spaces must be surrounded by double quotes.
Any Unicode characters used in the filter are converted to your web browser's character encoding. If a different UTF-level is required, use hexadecimal characters in the filter pattern.
Hex filters work with or without spaces. These are the same search:
 
“41 70 65 78”
41706578
“0x41 0x70 0x65 0x78”
 
A binary pattern is one or more 8-bit numbers separated by a space. Each binary number is a sequence of 0, 1, or x. An x is a wildcard character that matches either the 0 or 1 bit.
Regular Expression filters allow you to use Unix/Perl-style regular expressions, which let you use a wildcard for single characters, groups of characters, ranges of characters and numeric values, and more. These searches may be slow, especially if the expression is complex or the data to be searched is large.
After the trace extraction completes the saved file can be opened in Observer to analyze the packets. If you open your trace in Observer one of two things happen with the filter. If this filter does not already exist a filter is created in the temp folder. If you want to permanently keep the filter in Observer you must move the filter out of the temp folder. If this filter already existed, the existing filter is automatically updated. The previous one is overwritten with the values from this one.
pattern
Case-insensitive ASCII strings can be searched for using the pattern keyword. If you need a case-sensitive search use patternSensitive.
 
pattern search pattern[(ip|tcp|
 
 
“HTTP/1.1”
"filter": pattern “HTTP/1.1”
A case-insensitive ASCII search of the entire packet for “HTTP/1.1.”
 
 
“HTTP/1.1” [tcpData]
"filter": pattern “HTTP/1.1” [tcpData]
A case-insensitive ASCII search of the starting at the beginning of the TCP Data section of the packet for “HTTP/1.1.”
 
 
“HTTP/1.1” [14]
"filter": pattern “HTTP/1.1” [14]
A case-insensitive ASCII search at byte 14 of the packet for “HTTP/1.1.”
 
 
“HTTP/1.1” [14-20]
"filter": pattern “HTTP/1.1” [14-20]
A case-insensitive ASCII search starting at byte 14 through byte 20 for “HTTP/1.1.”
 
 
“HTTP/1.1” [14-32767]
"filter": pattern “HTTP/1.1” [14-32767]
A case-insensitive ASCII search starting at byte 14 through the end of the packet for “HTTP/1.1.”
 
 
“HTTP/1.1” [tcpData:14-20]
"filter": pattern “HTTP/1.1” [tcpData:14-20]
A case-insensitive ASCII search starting at byte 14 through byte 20 of the TCP Data section for “HTTP/1.1.”
 
patternSensitive
Case-sensitive ASCII strings can be searched for using the patternSensitive keyword.
 
patternSensitive search pattern[(ip|tcp|
 
 
“SELECT Query”
"filter": patternSensitive “SELECT Query”
A case-sensitive ASCII search of the entire packet for “SELECT Query.”
 
 
“SELECT Query” [udpData]
"filter": patternSensitive “SELECT Query” [udpData]
A case-sensitive ASCII search of the starting at the beginning of the UDP Data section of the packet for “SELECT Query.”
 
 
“SELECT Query” [14]
"filter": patternSensitive “SELECT Query” [14]
A case-sensitive ASCII search at byte 14 of the packet for “SELECT Query.”
 
 
“SELECT Query” [14-20]
"filter": patternSensitive “SELECT Query” [14-20]
A case-sensitive ASCII search starting at byte 14 through byte 20 for “SELECT Query.” For more details about ranges, see Understanding patterns.
 
 
“SELECT Query” [14-32767]
"filter": patternSensitive “SELECT Query” [14-32767]
A case-sensitive ASCII search starting at byte 14 through the end of the packet for “SELECT Query.”
 
 
“SELECT Query” “SELECT Query” [udpData:14-20]
"filter": patternSensitive “SELECT Query” [udpData:14-20]
A case-sensitive ASCII search starting at byte 14 through byte 20 of the UDP Data section of the packet for “SELECT Query.”
 
patternBin
Binary bits can be searched for using the patternBin keyword.
 
A binary pattern is one or more 8-bit numbers separated by a space. Each binary number is a sequence of 0, 1, or x. An x is a wildcard character that matches either the 0 or 1 bit.
patternBin search pattern[(ip|tcp|
 
 
xxx1xxxx
"filter": patternBin xxx1xxxx
A search of the entire packet for a particular bit surrounded by wildcards.
 
 
xxx1xxxx [tcp]
"filter": patternBin xxx1xxxx [tcp]
A search of the TCP header for a particular bit surrounded by wildcards.
 
 
xxx1xxxx [tcp:13]
"filter": patternBin xxx1xxxx [tcp:13]
A search at byte 13 of the TCP header for a particular bit surrounded by wildcards.
 
 
“0101xxxx xxx1xxxx” [tcp:10-15]
"filter": patternBin “0101xxxx xxx1xxxx” [tcp:10-15]
A search starting at byte 10 through byte 15 of the TCP header for a particular bit pattern using wildcards. For more details about ranges, see Understanding patterns.
 
patternHex
Hex characters can be searched for using the patternHex keyword.
 
patternHex search pattern[(ip|tcp|
 
 
41706578
"filter": patternHex 41706578
A search of the entire packet for a particular hex pattern.
 
 
41706578 [ip]
"filter": patternHex 41706578 [ip]
A search of the IP header for a particular hex pattern.
 
 
"56 69 61 76 69" [13]
"filter": patternHex "56 69 61 76 69" [13]
A search at byte 13 of the entire packet for a particular hex pattern. The pattern contains a space and therefore must be enclosed in double quotes.
 
 
"56 69 61 76 69" [tcp:10-15]
"filter": patternHex "56 69 61 76 69" [tcp:10-15]
A search starting at byte 10 through byte 15 of the TCP header for a particular hex pattern. For more details about ranges, see Understanding patterns.
 
patternRegex
Regular expressions can be used for a search using the patternRegex keyword.
 
Regular Expression filters allow you to use Unix/Perl-style regular expressions, which let you use a wildcard for single characters, groups of characters, ranges of characters and numeric values, and more. These searches may be slow, especially if the expression is complex or the data to be searched is large.
patternRegex search pattern[(ip|tcp|
 
 
/\d+ABCD/
"filter": patternRegex "/\d+ABCD/"
A search of the entire packet using a regular expression looking any number (or group of numbers) followed by ABCD. The / at the beginning and end is a delimiter. If your regular expression contains / it must be escaped with \.
 
 
/\d+ABCD/i
"filter": patternRegex "/\d+ABCD/i"
A case-insensitive search of the entire packet using a regular expression looking any number (or group of numbers) followed by ABCD. The / at the beginning and end is a delimiter. If your regular expression contains / it must be escaped with \.