The Event Filter Syntax allows users to utilize a special search in order to come up with various views to help them monitor their environments within their UpGuard 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 wired up with Actions.

Type

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)

Attributes

You can also filter top level attributes of an event:

  • Environment
  • Group (Node Group)
  • Start (Start Date/Time)
  • End (End Date/Time)

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

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 expand the event in the list view to see what variables are present.
  2. You can start typing variables. in the filter box (after specifying a type) to get the 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=Node Created AND Environment=Default OR group=Linux (NOT VALID)

Operators

The above examples all use equality checks. It is also possible to use negative 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