The Event Filter Syntax allows users to utilize a special search in order to construct various views to help them monitor their environments within their UpGuard Core instance.

Event Filter Syntax

Filtering Events allows you to focus on those which impact your business most. Custom filters can be used to create event views, which in turn can be connected to Actions.

Type

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)

Attributes

You can also filter top level attributes of an event:

  • By Environment using the environment operator
  • By Node Group by using the group operator
  • Selecting events occuring after a particular time using the start operator
  • Selecting events occuring up until a particular time using the end operator

Examples:

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

Variables

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.

  1. You can click on an event entry to expand the event in the list view to see what variables are collected.
  2. 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.

events

When you know what variables you have access to you can use them just like the top level attributes:

Examples:

type=Node Created AND variables.type=Firewall AND variables.os_family=Cisco

type=User Logged In AND variables.email=user@mycompany.com

Conditionals

You can add more granularity to your filtering by making use of OR statements.

Examples:

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 because the OR is operating on an environment= operand and an group= operand.

type=Node Created AND environment=Default OR group=Linux (NOT VALID)

Operators

The above examples all use equality checks. It is also possible to use negated equality checks.

Examples:

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

Wildcards may also be used. When using them with top level attributes they can be used standalone.

Examples:

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=*@upguard.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.

Examples:

type=User Logged In AND start=1 day ago

type=Node Created AND start=20 minutes ago AND end=10 minutes ago

Performance

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.

Tags: events