Monitoring Docker environments

Prerequisites

1. Install the Wazuh agent on the Docker host and enroll it on a Wazuh manager.

2. Install Python and pip:

   APTYumDNF

   $ sudo apt install -y python3 python3-pip
   

3. Install Docker:

   $ curl -sSL https://get.docker.com/ -o get-docker.sh
   $ sudo sh get-docker.sh
   

4. Install Python Docker library and other dependencies:

   APTYumDNF

   $ sudo apt remove python3-urllib3
   $ sudo pip3 install docker==7.1.0 urllib3==1.26.20 requests==2.32.2 --ignore-installed --break-system-packages
   

   Note

   The above commands modify the default externally managed Python environment. See the PEP 668 description for more information. To prevent the modification, create a virtual environment and install the dependencies inside it. Then update the Docker /var/ossec/wodles/docker/DockerListener script shebang with your virtual environment interpreter, for example, #!<VIRTUAL_ENVIRONMENT_PATH>/bin/python3.

   The urllib3 and requests versions are pinned to the versions compatible with the Wazuh Docker listener. The command removes any existing version of urllib3 (and its dependencies) and replaces it with the pinned version.

5. Start and enable the Docker service:

   $ sudo systemctl start docker.service
   $ sudo systemctl enable docker.service
   

Enable the Wazuh Docker listener module

Perform the following steps on the Docker host to configure the Wazuh agent to forward Docker events to the Wazuh manager.

1. Add the following configuration within an <ossec_config> block in the Wazuh agent /var/ossec/etc/ossec.conf configuration file to enable the Wazuh Docker listener module:

   <wodle name="docker-listener">
     <interval>1m</interval>
     <attempts>5</attempts>
     <run_on_start>yes</run_on_start>
     <disabled>no</disabled>
   </wodle>
   

   Where:

   • <interval> sets how long to wait before restarting the Docker listener after it exits due to unexpected error or other issues. In this example, it is 1m (1 minute).

   • <attempts> sets how many times the Wazuh agent tries to run the Docker listener if it fails. In this example, it is 5.

   • <run_on_start> runs the Docker listener immediately when the Wazuh agent starts. The value yes, enables this behavior.

   • <disabled> enables or disables the Docker listener. The value no, enables it.

   Refer to Wazuh Docker listener module configuration options for more information about the available options.

2. Restart the Wazuh agent to apply the changes:

   $ sudo systemctl restart wazuh-agent
   

3. Verify that the Docker listener module started:

   $ sudo grep docker /var/ossec/logs/ossec.log
   

   The command output looks similar to this:

   2026/07/10 13:38:10 wazuh-modulesd:docker-listener: INFO: Module docker-listener started.
   2026/07/10 13:38:10 wazuh-modulesd:docker-listener: INFO: Starting to listening Docker events.
   2026/07/10 13:38:19 wazuh-modulesd:docker-listener: INFO: Wodle started.
   2026/07/10 13:38:20 wazuh-modulesd:docker-listener: INFO: Docker service was started.
   

Enable the Wazuh Docker integration

Perform the following steps on the Wazuh dashboard to enable the Wazuh Docker integration.

1. Navigate to Security Analytics > Overview.

2. Enter docker into the search box and select docker.

3. Click on Actions and select Enable.

   

Main options

The main options enable or disable the Wazuh Docker listener module. They also set how many times the listener retries after a failure.

Scheduling options

The scheduling options allow you to configure when the Wazuh Docker listener module executes. The available scheduling options are run_on_start, interval, day, wday, and time.