Event Definitions

An event refers to specific circumstances in your environment that would cause a change in normal behavior. For example an event could be changes made to firewall policies or a failed login attempt by a blacklisted IP address. Graylog helps you manage events by allowing you to define the specific parameters of an event and alerts you when your log data matches these parameters. In this article, we review how to create and manage event definitions, including how to attach an alert to the event.

There are two main ways to create a new event definition:

Create an Event Definition Through the Wizard

To create an event definition through the wizard in the Graylog interface:

  1. Navigate to Alerts.

  2. Click the Event Definitions tab.

  3. Select Create event definition in the upper right corner.

The first screen in the wizard presents fields where you set the event title, description, and priority.

Apply Remediation Steps

Graylog Security lets you specify remediation steps (represented as a text value) within event definitions, sigma rules, and anomaly detectors. This functionality allows you to outline actionable measures for security analysts to follow when an alert is triggered. When specified, these remediation steps are prominently displayed upon the triggering of security events, guiding analysts on the next steps to take.

Define a Priority

The priority of an event is a user-specified classification. Events can be prioritized from 1 to 3 (1 = low, 2 = normal, and 3 = high) according to their importance. This assessment can help you triage events, which is a necessary practice in security investigations. The priority of an event is displayed as a thermometer icon in the overview and is written into the alert.

An example of a low prioritized event (priority level 1) might be one failed login in 10 minutes. A normal prioritization (priority level 2) might be 2 or 3 failed logins in 10 minutes. More than 15 failed logins in 10 minutes could be considered high priority (priority level 3) because this occurrence could mean that a person or bot is trying to break into a system.

Set Event Type

Additionally in the wizard you can define the type of event. Select the event type from the Condition Type drop-down menu:

  • Filter & Aggregation: This type is an event based on search and filtering of log data.

  • Event Correlation: This type is an event based on the occurrence of multiple other defined events in a sequence.

After you make your selection, additional fields appear on this page to define the event.

The remainder of this article focuses on Filter & Aggregation events. For information about event correlation, see Correlation Engine.

Hint: Sigma rules events are displayed on the Event Definitions page, but you define sigma events on the Sigma Rules page in Graylog Security. Graylog Security is a part of the Graylog centralized log management platform and requires a separate license. Contact the Graylog Sales team for more information about this product.

Define Event Criteria

By combining a search query and an aggregation, you can specifically describe the criteria that would constitute a Filter & Aggregation event. In the Filter section, set your search query and other details:

  1. Define a search query that your messages should match. The query should use the same syntax as any search from the Search page.

  2. (Optional) Apply a search filter to modify the query results. See below for information about search filters.

  3. Select a stream in which the message can be found.

  4. Define the window of time that the filter searches backward to match messages.

The search is executed at the given interval. If the filter matches, an event is created.

An example of using a filter to define an event could be filtering against a search for failed user logins by further refining it to include only certain users. You might also define the window of time to be the last 24 hours or the last 3 days.

If the defined filter matches messages currently on the Graylog server, the messages are displayed in the Filter Preview panel on the right.

Apply a Search Filter

Search filters let you reuse query snippets to refine your search result. If you have properties that you frequently need to either include or exclude from event definitions, you can create them as search filters, which makes them easy to apply across different event definitions.

As an example, you may have a list of IP addresses for your internal users. For some events, you might want to omit this internal activity. You could create a search filter for this and use it in the event definition to eliminate any messages from those addresses. Having this query as a search filter lets you reuse it across different event definitions easily.

For complete information about creating and applying search filters, see Search Filters.

Create an Aggregation

An aggregation is the combination of two or more entities. The new entity processes specific and meaningful results. Aggregations can run a mathematical operation on either a numeric field value or the raw count of messages generated that match the filter. Aggregations can group matches by a selected field before making the comparison.

For instance, if the field username is defined, then it is possible to alert on five successive failed logins by a particular username. In this example, you would create an event definition that triggers if there are five or more consecutive failed login messages that pertain to the targeted user.

Create a Field

You can also create a custom field as part of an event definition in the Fields menu. These fields allow an event generated from this definition to populate data from the original log into the Graylog events index. This prevents you from having to run subsequent searches to get vital information. These fields can also be used to limit the amount of data sent to an alert target, and you can run aggregations that include custom fields.

Hint: The event is recorded to the All Events stream and contains the custom field as well as the result of the aggregation that triggered the event.

These fields can be accessed within an alert and can be used as part of the Enterprise event correlation feature.

Attach an Alert

In the Notifications menu, you can attach an alert to your event definition. See the Alerts article for information on how to set up an alert and the alert types available.

Create an Event Definition Directly From Search Results

You can select any value in your search results to create an event definition. This event definition generates tailored alerts that include only the specific part of the query that you want to be alerted on. To do so:

  1. Go to your search results.

  2. Click any value in an aggregation widget, log view, or message widget.

  3. Select Create event definition from the drop down menu.

  4. Pick one of the Strategy by options in the dialog box that appears. You can select any of these options:

    • Exactly this value: Displays parameters related to your current search. You may add or remove any of these.

    • Any in widget: Displays parameters related to the selected value.

    • Custom: Allows you to include any part of the search query.

  5. Click Show strategy details to select or deselect any parameters you would like to add to the event definition. The parameters you select here populate in your event definition under Filter & Aggregation.

    Hint: In addition to the three options displayed above, you might be presented with other options depending on the value you select. For example, if you select an aggregation widget metric value, you are presented with additional Any in row and Any in column options.

  6. Click Continue Configuration. You are redirected to the Event Definitions page. Start by giving your event definition a unique title and filling in other details in Event Details. The selections you made in steps 4 and 5 are populated in Filter & Aggregation. You can add search filters, custom fields, and alerts in this menu.

  7. After reviewing the summary of your new event definition, click Create event definition. A new event definition is created, and you will receive alerts for the given condition.

Manage Defined Events

All defined events are available on the Alerts & Events page. You can find details about each entity, such as the priority, status, and scheduling, on the Event Definitions page. Click the information icon in the Scheduling column to view information about status, last execution, next execution, next time range, and queued notifications.

The Event Definitions page includes the Bulk actions menu, which lets you delete, enable, and disable multiple entities simultaneously. Under More , you can edit, duplicate, enable or disable, and delete individual definitions.

Manage Illuminate Events

Illuminate events are generated by the Illuminate Event Definitions Rollup pack. This collection provides many predefined events that you can run in your environment. When you enable this pack in Illuminate, these events are added to the Event Definitions page automatically. You can choose which of the events to enable.

To enable or disable an Illuminate event, you have two options from the Event Definitions page:

  • In the Status column, click the enabled / disabled icon to toggle the status.

  • From the More menu, select Enable / Disable to toggle the status.

Illuminate event definitions are predefined. However, these events include two customizable settings. Select More > Edit to open the event definition wizard where you can make the following changes:

  • Search filters: On the Filter & Aggregation page, add a search filter. Although Illuminate event definitions are fixed, you can add search filters to include or exclude properties from the results. See Apply a Search Filter above for information.

  • Alerts: On the Notifications page, add or update alerts you want to send if this event is triggered. See the Alerts article for information on how to set up an alert and the alert types available.

The remaining settings in the wizard are read-only for Illuminate events. Click Update event definition on the Summary page to save your changes.

Replay a Search

You can replay the specific search that first triggered an event. Select an entity on the Alerts & Events page to access the replay search option, which can be found under Actions. You may review the search results and messages to gather important details in investigating the event. Note that this page can also be bookmarked for future reference during investigations.

Filter with Dynamic Lists

The following section exclusively pertains to a Graylog Enterprise feature. To learn more about obtaining an Enterprise license, please contact the Graylog Sales team.

Dynamic lists allow you to define a filter where some of the search arguments are parameterized. Every time an event definition is being checked, these parameters are replaced with the result of a dynamic list.

Dynamic lists (such as a lookup tables) can be used to create event definitions:

  1. Go to the Alerts page.

  2. Navigate to Event Definitions and click Create Event Definition.

  3. Enter the required information for Event Details.

  4. Select Filter & Aggregation as the Condition Type.

  5. Enter your search query using the same syntax as used on the Search page.

  6. Click the undeclared parameter that shows up in the Query Parameters box. Enter the required information in the menu that appears and selectSave.

  7. Check the Filter Preview section to validate the outcome before you proceed.

  8. Click Create event definition on the Summary tab. Now you will receive alerts based on this event definition.

Dynamic Lists Use Case

In this scenario, the user wants to monitor a list of former employees for safety reasons. They want to receive an alert if anyone on the list tries to log in to the company system. Generally, this type of query is usually difficult to maintain because of the immense number of values to compare. Using a lookup table allows them to compare a log value to any value within the list. The lookup table will be updated to include all former employees, including ones that have recently left the company.

The parameter $former_employee$ is backed by a lookup table that returns a current list of former employees. After creating the event definition, the user will be alerted on any login attempts from anybody on the list.