Event Filter Syntax
The boolean operators available ("AND" and "OR"), as well as various attributes (e.g. "Node Scanned", "Default") are case-sensitive.
The first rule of event filters is that every query must contain exactly one event type.
type=Node Created (VALID) type=Node Created OR type=User Logged In (NOT VALID)
You can also filter top level attributes of an event:
- By Environment using the
- By Node Group by using the
- Selecting events occuring after a particular time using the
- Selecting events occuring up until a particular time using the
type=Node Created AND environment=Default type=User Logged In AND start=2017-01-01 01:00:00 type=Policy Ran AND group=Windows type=User Logged In AND start=1 week ago AND end=1 day ago
While the above attributes can be used for any event type, variables are specific to certain events. There are two ways to find out what variables are available for an event.
- You can click on an event entry to expand the event in the list view to see what variables are collected.
- You can start typing
variables, followed by a dot, in the filter box (after specifying a type) to get an autocomplete of variables for that event type.
When you know what variables you have access to you can use them just like the top level attributes:
type=Node Created AND variables.type=Firewall AND variables.os_family=Cisco type=User Logged In AND email@example.com
You can add more granularity to your filtering by making use of OR statements.
type=Node Created AND group=Windows OR group=Linux type=User Logged In AND variables.ip_address=192.0.0.1 OR variables.ip_address=192.0.0.2
You can only use “OR” statements within the same parameter type. The example below is invalid
OR is operating on an
environment= operand and an
type=Node Created AND environment=Default OR group=Linux (NOT VALID)
The above examples all use equality checks. It is also possible to use negated equality checks.
type=Node Created AND group!=Windows type=Policy Ran AND variables.node!=Test Node
You cannot use “OR” to join negative checks. For example, the following would be invalid:
type=Node Created AND group!=Windows OR group!=Linux (NOT VALID)
Wildcards may also be used. When using them with top level attributes they can be used standalone.
type=Policy Ran AND group=Application* type=Node Created AND environment=Prod*
Due to the high possibility of an inefficient query when using wildcards we require a start date be added in those instances.
type=User Logged In AND firstname.lastname@example.org AND start=2017-01-01
Presence checks are also avaiable for variables.
type=Node Changed AND variables.file_diffs=~missing~ type=Node Changed AND variables.file_diffs=~present~
Due to the high possibility of an inefficient query when using a presence check we require a start date be added in those instances.
type=Node Changed AND variables.file_diffs=~present~ AND start=2017-01-01
Natural Language & Relative Dates
For the start and end parameters it is also possible to use natural language to get relative date ranges.
type=User Logged In AND start=1 day ago type=Node Created AND start=20 minutes ago AND end=10 minutes ago
Wildcard searches are not the only way that inefficient filters can be introduced. With millions of possible events in the system, it is important to choose filters carefully. When adding a new filter, it is advisable to include a start that limits the scope of the query. This will avoid kicking off long running searches that can impact appliance performance.