Filtering security data with the Wazuh Query Language

| by | Wazuh 4.7.3
Post icon

The Wazuh Query Language (WQL) simplifies security data filtering in the Wazuh dashboard with its user-friendly format. With the use of a specialized querying language like Wazuh Query Language, security analysts can analyze and query security log data, enabling effective detection and response to security threats. WQL provides a solution for navigating complex datasets, allowing users to quickly filter large amounts of data.

The Wazuh Query Language expands the search bar functionality to specific tabs on the Wazuh dashboard. These tabs include the following:

  • Security Configuration Assessment
  • Endpoint summary
  • MITRE ATT&CK Intelligence
  • Agent Inventory data
  • Rule management
  • Decoder management
  • CDB list management
  • Group management

Wazuh Query Language enables precise data retrieval by defining detailed criteria. WQL operates in its simplest form using a field name, operator, and value. This approach requires defining the following entities. 

  • Fieldname indicates the particular data type you want to filter, serving as the starting point in a query.
  • Operators equality =, inequality !=, greater than >, less than <, like as (~)
  • Value is the specific data that is being filtered for.

Basic syntax:

fieldname operator value

You can string simple queries together using separators or grouping operators.


To demonstrate Wazuh Query Language capabilities for our use cases, we set up the following infrastructure:

  • A pre-built, ready-to-use Wazuh OVA 4.7.3 which includes the Wazuh core components (Wazuh server, Wazuh indexer, and Wazuh dashboard). Follow the virtual machine (OVA) – installation alternatives to download and set up the Wazuh virtual machine.
  • An Ubuntu 22.04.3 endpoint with Wazuh agent 4.7.3 installed and enrolled to the Wazuh server.

Use cases

The Wazuh Query Language has several applications to make effective security data queries. In this blog post, we showcase some common uses of WQL that benefit security analysts by providing visibility into their IT environment.

busybox vulnerabilities search with more than High severity

One of the core Wazuh capabilities is to detect vulnerabilities in the monitored endpoints and display them on the Wazuh dashboard. We can use WQL to filter the vulnerabilities list and find the expected vulnerabilities. Based on our use case, we will look for any vulnerable packages with the name busybox. busybox is a software suite that provides several Unix utilities into a single executable file. It offers various command-line functions such as file management, process control, networking, and more.

Perform the actions below to look for vulnerabilities affecting the busybox utility with severity levels greater than High.

Wazuh server

Configure the Wazuh server to enable the Wazuh Vulnerability Detector module to scan the monitored Ubuntu endpoint. 

Perform the actions below to configure on the Wazuh server.

1. Enable the <vulnerability-detector> module for Ubuntu endpoints in the Wazuh server configuration file /var/ossec/etc/ossec.conf:


    <!-- Ubuntu OS vulnerabilities -->
    <provider name="canonical">

2. Restart the Wazuh manager for the changes to take effect:

# systemctl restart wazuh-manager

Wazuh dashboard

Perform the actions below on the Wazuh dashboard to write a WQL query to find the busybox vulnerabilities.

1. Navigate to the Modules > Vulnerabilities section on your Wazuh dashboard. 

2. Select the Ubuntu agent. 

You will see some query suggestions in the WQL search bar as shown below:

Wazuh Query Language suggestions
Figure 1: WQL suggestions for Vulnerabilities

Note: The suggestions help to understand the valid keywords for the specific query, as well as the possible options to construct a meaningful query.

3. Use the below query in the WQL search bar to extract the vulnerable busybox packages with severity levels greater than High:

name ~ busybox and severity < High


  • Field name: name, severity
  • Operator: ~, <
  • Value: busybox, High
  • Separator: and combines two simple queries


Query Language busybox vulnerability
Figure 2: WQL Query for busybox vulnerability

Search based on Wazuh agent names, groups, and Wazuh nodes

The number of Wazuh agents installed and enrolled in the Wazuh server usually depends on organization size and device usage. In a large environment, Wazuh agents are categorized based on their departments, OS types, or locations. Each agent is provided with a unique agent ID. In a distributed environment, Wazuh agents are usually connected to different Wazuh server nodes. In this use case, we write a query to filter Wazuh agents based on the following conditions:

  • The agent must be within the default group and must not have the agent name Winodws10.
  • Following the first condition, the agent must be within node01 Cluster node.

In this use case, we install a Wazuh agent on a Windows 10 endpoint and enroll it to the Wazuh server to show how WQL query filters enrolled Wazuh agents’ data. Follow this install Wazuh agents on Windows endpoints guide to install the Wazuh agent.

Perform the following steps to construct a WQL query for searching Wazuh agents.

1. Navigate to the Agents section on your Wazuh dashboard.

2. Run the query below on the WQL search bar:

( group = default and name != Windows10 ) and node_name = node01


  • Field name: group, name, node_name
  • Operator: = , !=, ()
  • Value: default, Windows10, node01
  • Separator: and combines two queries two times

Note: The above WQL query is useful when multiple Wazuh agents are connected to the Wazuh server.


WQL Query Wazuh agents
Figure 3: WQL Query to find Wazuh agents

MITRE ATT&CK Intelligence search for Active Directory attacks

Data from the MITRE ATT&CK framework is integrated into Wazuh, which enhances the platform’s capability to monitor and visualize real-world adversary behaviors in a structured manner. Users can leverage the framework within Wazuh to create and refine rules that simulate advanced persistent threats, helping to identify and mitigate potential attacks more effectively. The framework aids in enriching the threat intelligence features of Wazuh, allowing teams to track and respond to evolving cyber threats accurately.

The incorporation of Wazuh Query Language further amplifies the utility of MITRE ATT&CK within the Wazuh platform. By using WQL, teams can efficiently query this data to pinpoint specific MITRE ATT&CK techniques, tactics, and software facilitating a more targeted approach to threat hunting and incident investigation. 

Here, we show a WQL query that finds command-line software that is used for Active Directory attacks.

1. Navigate to Modules > MITRE ATT&CK on the Wazuh dashboard.

2. Select the Intelligence tab from the MITRE ATT&CK window.

3. Find the WQL search bar by selecting the Software section from the left side menu.

4. Run the below query on the WQL search bar:

description ~ "Active Directory" and description ~ "command-line"


  • Field name: description
  • Operator:  ~
  • Value: “Active Directory”, “command-line”
  • Separator: and combines two simple queries


The image below shows a list of well-known software that causes command-line-based Active Directory attacks.

WQL query malicious software
Figure 4: WQL query to find malicious software in MITRE ATT&CK

Python 3 web server data retrieval

With WQL, we can efficiently query various aspects of system inventory information, including listening ports, installed packages, and running processes. This functionality lets administrators gain comprehensive insights into system activity and potential security vulnerabilities. By leveraging WQL within the Wazuh dashboard, organizations can enhance their threat detection capabilities and proactively mitigate risks.

In this use case, we run a Python 3 web server on the monitored endpoint and extract information about it using the Wazuh Query Language.

Wazuh agent

We configure the Wazuh agent installed on the Ubuntu endpoint to set a minimal interval and ensure that inventory data is rapidly synchronized with the Wazuh dashboard.

Note: The default value for the <interval> parameter in the <syscollector> module of the Wazuh agent is 1 hour. We have set the value to 1 minute in this blog post for demonstration purposes. However, having such a small time interval may not be ideal in production environments.

Additionally, we run a Python 3 web server on the same endpoint to ensure the web server-related information appears in the Wazuh dashboard.

1. Set a 1m interval for <syscollector> module in the Wazuh agent configuration file located at /var/ossec/etc/ossec.conf as shown below:

<!-- System inventory -->
<wodle name="syscollector">
  <ports all="no">yes</ports>

  <!-- Database synchronization settings -->

2. Restart the Wazuh agent for the configuration changes to take effect:

# systemctl restart wazuh-agent

3. Run a Python 3 server on port 8888:

# python3 -m http.server 8888

Keep the Python 3 server running for security analysis in the next section.

Wazuh dashboard

Perform the actions below on the Wazuh dashboard to extract information related to the Python 3 web server.

1. Navigate to the Agents section on your Wazuh dashboard.

2. Select Ubuntu_22.04 agent with agent ID 001.

Select Inventory data from the new window as shown below:

Agent inventory section
Figure 5: Agent inventory section in the Wazuh dashboard

In the Inventory data section, we can find useful information about the monitored endpoint such as:

  • Operating system details
  • Hardware details
  • Network related information
  • Installed packages
  • Running processes

Let’s find the following information for the Python 3 web server from the Inventory data section.

Python 3 packages

We will look for the Python 3 packages installed on the monitored Ubuntu endpoint that has a version more than 3.10. We will write a query in this regard. 

Construct the below query and run it on the WQL search bar in the Packages section.

name ~ python3 and version > 3.10


  • Field name: name, version
  • Operator: ~, >
  • Value: python3, version
  • Separator: and combines two simple queries


All the Python 3 related packages are visible as a result.

Wazuh Query Language Python 3 installed packages
Figure 6: WQL query to find Python 3 installed packages
Port 8888 search

The Python 3 web server is running on port 8888. Now, write a WQL query that searches for any listening ports between 8000 and 9000

We construct the below query and run it on the WQL search bar in the Network ports section.

(local.port > 8000 and local.port < 9000 ) and state=listening


  • Field name: local.port state
  • Operator: >, <, (), =
  • Value: 8000, 9000, listening
  • Separator: and combines two queries


Port 8888 which is used by a Python 3 process is shown in the below image:

WQL query to find port 8888
Figure 7: WQL query to find port 8888
Python 3 processes

Users can also send WQL queries via the API console in the Wazuh dashboard. In this section, we use the API Console in the Wazuh dashboard to find Python 3 processes created by the root user. Perform the following actions to find the running Python 3 processes.

1. Select Tools from the Wazuh menu.

2. Select API Console from the Tools section.

API Console in the Wazuh dashboard
Figure 8: API Console in the Wazuh dashboard

3. Run the below query in the API Console tab:

GET /syscollector/001/processes?euser=root&name=python3


Wazuh Query Language using API Console
Figure 9: WQL query using the API Console in the Wazuh dashboard
  "data": {
    "affected_items": [
        "scan": {
          "id": 0,
          "time": "2024-04-24T11:28:48+00:00"
        "tty": 34817,
        "name": "python3",
        "pid": "6625",
        "rgroup": "root",
        "state": "S",
        "utime": 33,
        "nlwp": 1,
        "resident": 11736,
        "nice": 0,
        "argvs": "-m http.server",
        "processor": 1,
        "stime": 11,
        "ppid": 1671,
        "size": 6871,
        "start_time": 1713957963,
        "vm_size": 27484,
        "fgroup": "root",
        "share": 901,
        "ruser": "root",
        "egroup": "root",
        "pgrp": 6625,
        "session": 1670,
        "tgid": 6625,
        "sgroup": "root",
        "priority": 20,
        "cmd": "python3",
        "euser": "root",
        "suser": "root",
        "agent_id": "001"
    "total_affected_items": 1,
    "total_failed_items": 0,
    "failed_items": []
  "message": "All specified syscollector information was returned",
  "error": 0

Search for Wazuh Docker rules and decoders

Wazuh has a wide array of rules and decoders for analyzing logs. When Wazuh receives logs, the decoders extract relevant fields from the logs. The fields extracted from the logs are compared against the rules, and alerts are triggered on the Wazuh dashboard if there is a match. 

In this use case, we write WQL queries to find all Docker rules and decoders currently enabled in the Wazuh server. 

Perform the actions below on your Wazuh dashboard.

1. Select Tools from the Wazuh menu.

2. Select API Console from the Tools section.

Navigation to the API Console
Figure 10: Navigation to the API Console in the Wazuh dashboard

3. Run the following query on the API Console tab:

GET /decoders/files?search=docker&status=enabled


Our query returns the Docker decoder as shown below.

Query Language using the API Console
Figure 11: WQL query using the API Console to find Wazuh decoders for Docker
  "data": {
    "affected_items": [
        "filename": "0410-docker_decoders.xml",
        "relative_dirname": "ruleset/decoders",
        "status": "enabled"
    "total_affected_items": 1,
    "total_failed_items": 0,
    "failed_items": []
  "message": "All decoder files were returned",
  "error": 0

4. Run the following query on the API Console window:

GET /rules/files?search=docker&status=enabled


Our query returns the Docker rules as shown below:

Wazuh rules for Docker
Figure 12: WQL query using the API Console to find Wazuh rules for Docker
  "data": {
    "affected_items": [
        "filename": "0455-docker_rules.xml",
        "relative_dirname": "ruleset/rules",
        "status": "enabled"
        "filename": "0560-docker_integration_rules.xml",
        "relative_dirname": "ruleset/rules",
        "status": "enabled"
    "total_affected_items": 2,
    "total_failed_items": 0,
    "failed_items": []
  "message": "All rule files were returned",
  "error": 0


In this post, we explore the Wazuh Query Language for navigating and filtering security data within Wazuh. Through examples and explanations, we have shown how WQL’s explicit and search term queries and its array of operators enable precise data filtering and rich security insights.

If you have questions or need further clarification, please join our community channels, our team and fellow contributors are ready to assist you.