This documentation assumes version 2.50 or higher of the UpGuard application.
Event Filter Syntax
The booleans for the query bar ("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 one of them must be done on one and only 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:
- Group (Node Group)
- Start (Start Date/Time)
- End (End Date/Time)
type=Node Created AND environment=Default type=User Logged In AND start=2017-01-01 01:00:00 type=Policy Ran AND group=Windows
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 expand the event in the list view to see what variables are present.
- You can start typing
variables.in the filter box (after specifying a type) to get the 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 firstname.lastname@example.org
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=Node Created AND Environment=Default OR group=Linux (NOT VALID)
The above examples all use equality checks. It is also possible to use negative 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 variables we require a start date be added in those instances.
type=User Logged In AND email@example.com 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.