Filter Expressions
Filtering is a key feature of Visualizer. It is what lets you rapidly locate important information in the configuration. The essense is that you provide a specification for which slices are of interest, and then the Main Grid displays only slices that match the specification. The specification takes the form of a filter expression. The filter expression specifies the desired values of the columns for a slice and the Main Grid hides all slices that do not match. The remaining slices are those of interest.
Basics
Filtering is done by creating a filter expression and then applying it to the Main Grid. A filter expression is built out of predicates. A predicate is a column name, a comparison operator, and a value. For a particular slice, a predicate is true if the value in the slice for the named column compares correctly with the value in the predicate. The manner in which the value from the slice and the value in the predicate are compared is controlled by the comparison operator in the predicate.
Let's look at a few examples.
Consider this predicate
Destination Address ^ 192.168.56.0/24
The column name is "Destination Address" and the value is "192.168.56.0/24". The '^' character is the intersection operator. It is true if any destination address in the slice is the same as any address in the 192.168.56.0/24 network. If, instead of the destination address of the packets in the slice, we were concerned with the source address, we could use this predicate --
Source Address ^ 192.168.56.0/24
This is same as before except the source addresses in the slices are compared against the 192.168.56.0/24 network. When thinking of predicates, think of the column name as a stand in for the value in the slice, which is compared to the predicate value.
Every named column except "Index" can be used in a predicate. Each column has a specific type of value and the value in the predicate must be of that type. For instance, "Destination Address" must have a range of IP addresses, and "Scope" must have a list of scopes.
The full set of comparison operators is
| Name | Comparison | |
|---|---|---|
| ^ | Interset | True if any value in the predicate is the same as any value in the slice. |
| -< | Contained by | True if every value in the slice is also in the predicate value. I.e., the slice values is entirely contained by (is a subset of) the predicate value. |
| >- | Contains | True if every value in the predicate value is also in the slice. I.e., the slice value entirely contains (is a superset of) the predicate value. |
| = | Equal | True if the predicate value and the slice value are identical. |
| < | Less than | True if the slice value is less than the predicate value. |
| <= | Less than or equal | True if the slice value is less than or equal to the predicate value. |
| > | Greater than | True if the slice value is greater than the predicate value. |
| >= | Greater than or equal | True if the slice is greater than or equal to the predicate value. |
Not every column supports every comparison operator. For instance, it makes no sense to check if one range of IP address is greater than another.
Combining predicates
Predicates are useful by themselves, but they are even more useful as building blocks to more complex filter expressions. Predicates can be combined using three binary operators.
| Name | Meaning | |
|---|---|---|
| | | Or | True if either or both sides is true. |
| & | And | True only if both sides are true. |
| * | Otherwise | Only used in Querent, listed here for completeness because it may be displayed in the Query tab. |
A binary operator can combine two predicates or it can combine the result another binary operator and a predicate, or two results, so that predicates can be chained together by binary operators.
For example,
Source Address ^ 10.10.0.0/16 | Source Address ^ 172.16.24.0/24 & Destination Service ^ TCP::HTTP
The "or" operator combines the predicates on "Source Address" and is true if the source addresses in the slice intersect the 10.10.0.0/16 network or the 172.16.24/24 network. The "and" operator is true if the "or" was true and the destination service range for the slice contains TCP port 80 (HTTP). Binary operators in a sequence operate in order from left to right. This can be changed by using parentheses. Binary operators cannot reach inside parentheses so any operators inside parentheses operate before those outside.
For example, this filter expression is the same as the previous despite the change in ordering because the parentheses force the source address comparisons before the destination service.
Destination Service ^ TCP::HTTP & ( Source Address ^10.10.0.0/16 | Source Address ^ 172.16.24.0/24 )
Without the parentheses the "and" operator would go first which is probably not what was desired. Parentheses can be used inside other parentheses providing complete control over the order of operation of binary operators. A pair of matched parentheses and its contents are referred to as a "sub-expression".
Negation
A filter expression can be negated by placing a '!' character in front of it.
! Actions >- permit
The predicate here is true if the actions for a slice include the "permit" action. The '!' negates that, turning true in to false and false in to true. As a result this filter expression is true if and only if the slice actions do not contain the "permit" action. Negation can be applied to either a predicate or a sub-expression. Negation only affects what is immediately after the '!' character, which is either a predicate or a sub-expression.
For example, going back we could have the filter expression
Destination Service ^ TCP::HTTP & ! ( Source Address ^ 10.10.0.0/16 | Source Address ^ 172.16.24.0/24 )
This is true if the destination service in the slice contains the HTTP port and the source address does not contain any address from the 10.10.0.0/16 network nor the 172.16.24.0/8 network. Without the parentheses the negation would affect only the predicate with the 10.10.0.0/16 network.