The following article exclusively pertains to a Graylog Security feature or functionality. 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 on this product.

Anomaly detection plays a vital role in managing modern, large-scale distributed systems. Within these systems, analyzing data aggregations can be a significant pain point, and sometimes potential issues and threats slip into these systems undetected.

Anomaly Detection is a Security tool that utilizes your Graylog environment powered by Illuminate. This tool's primary purpose is to help you detect outliers in a dataset by running Artificial Intelligence / Machine Learning (AI/ML) behavioral analysis, allowing you to receive notifications whenever something deviates from its usual behavior or operates outside normal levels based on an understanding of your unique log data. As a result, you and your team become empowered to navigate cyber threats proactively, identify unusual activities, and take steps toward mitigating anomalies within your IT environment.

The process begins when Graylog Illuminate receives your log data, then normalizes and enriches it. Graylog then feeds the enriched data into the Anomaly Detection tool, which breaks the data up into time slices and looks for data points outside of the expected range based on your historical data. When anomalous data points are detected, these messages are logged into a special anomaly index in your Graylog instance. You can then create alerts and receive notifications regarding these anomalies based on your configuration settings. Additionally, these anomalies are represented on Security dashboards with various customizable widgets, offering users interactive and actionable analytics.

This user guide will help you to prepare for and set up your Anomaly Detection tool.


  • You must first upgrade to Graylog 4.3.x before proceeding. This is the minimum version required to support OpenSearch.
  • OpenSearch is the required data node to support Anomaly Detection. We strongly recommend using the latest version of OpenSearch to optimize user experience.
  • Install or migrate to your latest installed OpenSearch application.
Warning: For Graylog versions prior to 5.x, do not upgrade to OpenSearch 2.0 as this will break your Graylog instance!
  • A valid Graylog Security license is also required. Contact the Graylog Sales team for more information on purchasing and downloading this license.
  • Illuminate 2.2.2 or above is also required to run the detection tool. New users can install the product or upgrade an existing instance as needed.
  • You will need live data constantly flowing into the server for the AI/ML behavioral analysis to function properly. It is recommended that you have at least a day's worth of ingested data on the server before running Anomaly Detection.


How to use Graylog Anomaly Detection

Using Anomaly Detection requires no prior experience in machine learning as the user interface is intuitive and provides numerous descriptors. Configuring the tool begins by switching the toggles to enable any of the available detectors offered.

  1. After you have purchased the Graylog Security license and installed or updated your Illuminate product, you can then install the Anomaly Detection content pack.
  2. Navigate to System > Content Packs, then search for "Anomaly Detection" in the search filter box and install the Graylog Anomaly Detection Rules Content Pack.

  1. Then, in your Graylog instance, select Security from the menu header. This contains your Graylog Security content.
  2. Select the Anomalies button on the left pane to see available anomaly detectors. Depending on your organization's needs and preferences, enable the required detectors by clicking on the toggle so that running state is shown.

Hint: A full list of all the available detectors and their functions may be reviewed in the relevant detector user guide.

Interpreting the Data

When the anomaly tool detects anomalies in the log data, it pulls that data into the Anomaly Detection processor. The data is then deconstructed into human-readable and decluttered messages known as Graylog anomaly event messages, which will flow through the standard event message processing flow. These anomaly event messages summarily give a user precise details of detected anomalous events.

HintFor a complete list of these event message types and their definitions, reviewthe anomaly event message index.

All anomaly event messages have common fields and additional fields depending on which detector the messages originate from. These additional fields tell us which entity (user, host, etc.) had anomalous behavior. Different detectors, like anomaly_detector_name, will add different fields.

Let's look at an example.

Below is a screenshot of an anomaly event message with both standard fields and anomaly fields populated. Think of an anomaly event message simply as how the Graylog anomaly detection tool represents data ingested behind the scenes.

In this example, an anomaly was detected by the Windows Event Log File Permissions Change Spike detector, with an anomaly confidence value of 0.99, meaning that the detector is quite certain that the detected event is anomalous. The full event message goes even further:

anomaly score: 3.99 (Indicates relative severity of an anomaly. The higher the score, the more anomalous a data point is. With an anomaly score of 3.99, this represents a relatively high anomalous data point)

anomaly grade: 1 (This is a severity level scale, ranging from 0 to 1. 0 is ‘not anomalous’ and a non-zero value represents the relative severity of the anomaly. With a value of 1 in this case, this is a high severity anomaly.

anomaly_file_perm_change_count: 3  (This is an additional field value which is specific to the Windows Event Log File Permissions Change Spike detector, and this value represents the number of times a file was permanently changed.

user_name: (This is an additional field value that is specific to the Windows Event Log File Permissions Change Spike detector and this value provides information on the username where the detected anomaly originated from. 

Here, the tool provides filtered data in the anomaly event message, further empowering users to locate the needle in the haystack within their IT infrastructure.

Events and Alerts

Now that you know what Graylog Anomaly Detection is and how to enable it, the next step is to utilize the anomaly event messages to create events and alerts.

Using the example of the Windows Event Log File Permissions Change Spike above, let's assume a user wants to be alerted any time there are changes to file permissions in a given environment’s Windows hosts. This user could begin by creating the search query:

anomaly_detector_name:wineventlog_file_permissions_change  AND anomaly_file_perm_change_count:>0 AND anomaly_confidence:>.01 

This query would then generate log data within the set parameters.

From here, you can create an alert that triggers a specific notification, like an email or Slack message, to a specific group of users. For full instructions on this process, see the events and alerts user guide.

Generate Events from Anomaly Detectors

By default when you enable an anomaly detector, it will now generate an event definition. You have the option to disable event definitions for enabled anomaly detectors by toggling the Enable event definition capsule button found in the Anomaly Detectors tab on the Anomalies page.

In this example, the anomaly detector for the Windows Security Event Log-File Permissions Change is enabled, while its corresponding event definition is disabled.

When a system-generated event definition is created by enabling an anomaly detector, this appears on the Events Definitions page. You can then add notifications to event definitions for when an anomalous event definition is triggered:

  1. Click on the More button for a selected event definition.

  2. Select Edit from the drop-down options.

  3. Navigate to the Notifications section in the resulting screen and click the Add Notification button.

  4. Select the required notification type and configure the applicable parameters.