How Wazuh Works: Architecture, Agent Communication, Rules and Vulnerability Detection

Now we will see how to deploy wazuh agents in Linux and Windows machine. The process is pretty straightforward as all the commands will be provided to us, we simply need to run these commands.

Deploying a Linux agent

I will be deploying a wazuh agent in my kali Linux which has ip address 192.168.122.76.
The steps are:

1. Click 'Deploy new agent' button in the wazuh dashboard.
2. Select the appropriate OS and architecture, (for Kali and 64 bit PC it is 'DEB amd64'(debian based 64 architecture PC)) and put in the IP address of the wazuh server(the computer where you installed wazuh server, in my case it is 192.168.122.181).
3. Provide a name to the agent if you want, I recommend you do.
4. Wazuh will provide a code to deploy the agent simply run that code in the machine you want to deploy your agent.
5. After running the command on kali run:
   sudo systemctl daemon-reload
sudo systemctl enable wazuh-agent
sudo systemctl start wazuh-agent
   And check the status using:
   sudo systemctl status wazuh-agent
   The status should be active.
6. If You are using UFW allow ports 1514 and 1515 tcp so that agent can communicate with the server.
   sudo ufw allow 1514/tcp
sudo ufw allow 1515/tcp
sudo ufw reload
   

After the agent deployment, a direcotry will be created for wazuh at /var/ossec. This is the main configuration directory for wazuh. All the agents configs and logs will be available here. We will talk about this directory And some important files later.

After deploying the agent you will see the agents listed in the wazuh dashboard. Access the agent from the dashboard by clicking on 'Active' under 'Agent Summary' section in your dashboard and then click your agent.
Wazuh will automatically run a scan on agents and show the vulnerabilities it found in the agent. Click Critical, High, Medium or Low to see the vulnerabilities it found. To really understand what this vulnurability is, what causes it and its fixes, notice the name of the vulnerability ( written as CVE-2026-40606 in my case). CVE stands for Common Vulnerabilities and Exposures, it is basically a database of all the common vulnerabilities that attackers exploit, its causes and fixes. To learn about a certain CVE just type in that CVE code in google and learn what it is, what causes it and how to fix it. After learning about the vulnerability you need to determine whether it is a false positive or true positive

Click the first link to learn about the vulnerability. In my case it was an LDAP related vulnerability which I fixed in my kali.

For deploying agents in Windows, do exactly what we did here. Fill the information in the dashboard and execute the generated code in Windows Powershell as administrator. Then start the Wazuh agent(the code for this is also provided by Wazuh).

I have already discussed the process of log generation by agents, transferring it to the server, decoding it, matching rules and generating alerts along with all the important files here.
Logs are Generated by the Operating System and those logs are stored in fixed location. In Linux, logs are stored in /var/log directory. The wazuh agents send these logs to the manager. We can configure what logs the wazuh agent sends by modifying the <localfile> block of file /var/ossec/etc/ossec.conf, as shown here.

Some important log files in Linux are:

📂 Core System & Security Logs

• /var/log/syslog or /var/log/messages
  Purpose: The central clearinghouse for system messages. Tracks everything from system startups to network glitches and application errors. (Ubuntu/Debian systems use syslog; RHEL/CentOS/Fedora use messages).
• /var/log/auth.log or /var/log/secure
  Purpose: Tracks authorization and security events, including successful and failed SSH login attempts. (Ubuntu/Debian uses auth.log; RHEL/CentOS uses secure).
• /var/log/boot.log
  Purpose: Contains all the messages printed to the screen while the system is booting up. Ideal for diagnosing startup hangs.
• /var/log/dmesg
  Purpose: Contains kernel ring buffer messages. Primarily used to diagnose issues with hardware drivers and core kernel errors.

🌐 Network & Application Logs

• /var/log/nginx/ or /var/log/apache2/
  Purpose: Web server traffic directories. Typically contain an access.log (every incoming request) and an error.log (broken links, misconfigurations).
• /var/log/cron
  Purpose: Logs scheduled background tasks (cron jobs). Check here if an automated script fails to execute.
• /var/log/mail.log or /var/log/maillog
  Purpose: Tracks postfix, sendmail, or other mail server utilities running on the host.

👥 User Login History (Binary Logs)

These files are stored in a binary format and cannot be viewed with standard text editors. You must use the designated commands listed below:

Log File Path	Purpose	Command to Read
/var/log/wtmp	Tracks historical records of all user logins and logouts.	last
/var/log/utmp	Tracks users who are currently logged into the system.	who or w
/var/log/btmp	Tracks failed login attempts (crucial for spotting brute-force attacks).	lastb
/var/log/lastlog	Shows the most recent login timestamp for all valid users.	lastlog

⚙️ Modern Logs: Systemd and Journalctl

Modern Linux distributions utilize systemd to capture logs in a binary format inside /var/log/journal. Use the journalctl utility to query them:

# View system logs in real-time
journalctl -f

# View logs for a specific service (e.g., SSH)
journalctl -u ssh

# View only error logs from the current boot
journalctl -p err -b

After you have set this up, the flow of logs happen as discussed here and the wazuh dashboard only displays alerts for logs that trigger a rule with a severity level of 3 or higher by default. I have configured the localfile section of ossec.conf in my kali Linux agent as follows:
As you can see I have journald, apache and syslog tracked. 'journald' collects and stores log messages from the kernel, system services, and applications running on a Linux system such as SSH login attempts, sudo usage, systemd service starts/stops, and kernel hardware errors.
Let's try to trigger an alert by entering wrong sudo password three times and see the alert in the wazuh dashboard. When you enter a wrong sudo password 3 times, PAM and sudo both log the failure and journald captures it. PAM(Pluggable Authentication Modules) is a Linux framework that handles authentication for applications and services. Instead of each app implementing its own login logic, they all delegate to PAM, which checks passwords, enforces limits, and logs results. For example, when you run sudo, it's PAM that actually verifies your password and decides whether to allow or deny access. To see the alert go to your wazuh dashboard and click 'Threat Hunting': Now click 'Events' and see the log: This alert triggered because there is a default ruleset for this. You can see this in your wazuh server's /var/ossec/ruleset/rules/ directory. This is the directory where all default rules live. For this particular action(3 failed sudo logins), the rule is defined in /var/ossec/ruleset/rules/0020-syslog_rules.xml in rule id 5404 with level 10.
But why is this in syslog rules and not PAM rule? As mentioned earlier both PAM and sudo log the failure but PAM logs the authentication failure i.e. "password check failed" sudo logs the overall event i.e "3 incorrect password attempts" Both messages end up in journald and Wazuh reads both from there. But the Wazuh rule that fires (syslog ruleset) is typically matching the sudo message, not the PAM one, since the sudo message is cleaner and more definitive.

Windows Agent and Logs

In windows the ossec.conf is present in C:\Program Files (x86)\ossec-agent\ossec.conf. The Wazuh agent can be configured to monitor Windows Event Logs and application log files using the <localfile> block in the same way as Linux. Unlike Linux, most important Windows logs are stored in the Event Log subsystem rather than as plain text files.

📂 Windows Event Logs

Windows stores its system, security, and application logs as .evtx files under C:\Windows\System32\winevt\Logs\. These logs are typically monitored through their Event Log channel names rather than by directly reading the files.

Event Log Channel	Purpose
Security	Contains authentication events, privilege usage, account management, and audit logs. Useful for detecting unauthorized access and brute-force attacks.
System	Contains operating system events such as driver failures, service crashes, hardware issues, and system startups or shutdowns.
Application	Contains events generated by installed applications and services.
Microsoft-Windows-PowerShell/Operational	Records PowerShell command execution and script activity.
Microsoft-Windows-Sysmon/Operational	Provides detailed process creation, network connection, registry modification, and file activity logs when Sysmon is installed.
Microsoft-Windows-Windows Defender/Operational	Contains malware detection, quarantine, and antivirus activity generated by Microsoft Defender.

🌐 Application and Service Logs

• C:\inetpub\logs\LogFiles\
  Purpose: Default location for IIS web server logs. Contains records of incoming HTTP requests and server errors.
• C:\ProgramData\
  Purpose: Many applications store log files in application-specific directories under this path.
• C:\Program Files\ and C:\Program Files (x86)\
  Purpose: Some applications maintain their own log directories within their installation folders.

🔍 Viewing Windows Logs

Windows logs can be viewed using the Event Viewer application or through PowerShell.

# List available event log channels
Get-WinEvent -ListLog *

# Read recent Security events
Get-WinEvent -LogName Security

# Export logs to a file
wevtutil epl Security security.evtx

⚙️ Example Wazuh <localfile> Configuration for Windows

The Wazuh agent uses the <localfile> block to specify which Windows Event Log channels or log files should be monitored. Some common examples are shown below.

<!-- Monitor Windows Security Events -->
<localfile>
    <location>Security</location>
    <log_format>eventchannel</log_format>
</localfile>

<!-- Monitor System Events -->
<localfile>
    <location>System</location>
    <log_format>eventchannel</log_format>
</localfile>

<!-- Monitor Application Events -->
<localfile>
    <location>Application</location>
    <log_format>eventchannel</log_format>
</localfile>

<!-- Monitor PowerShell Activity -->
<localfile>
    <location>Microsoft-Windows-PowerShell/Operational</location>
    <log_format>eventchannel</log_format>
</localfile>

<!-- Monitor Sysmon Events -->
<localfile>
    <location>Microsoft-Windows-Sysmon/Operational</location>
    <log_format>eventchannel</log_format>
</localfile>

Wazuh can also monitor ordinary text log files generated by applications. For example, to monitor IIS web server logs:

<localfile>
    <location>C:\inetpub\logs\LogFiles\W3SVC1\u_ex*.log</location>
    <log_format>iis</log_format>
</localfile>

File integrity monitoring is a very powerful security process that can be used to disrupt the Cyber Kill Chain by detecting unauthorized and unexpected changes to critical files, configurations, and registry entries. before attackers can fulfill their mission.

But what is the Cyber Kill Chain? The phrase sounds cool doesn't it? I should have introduced this concept a bit earlier but I prefer to do it here. Cyber Kill Chain is a foundational cybersecurity framework developed by Lockheed Martin that maps out the sequential phases of a cyberattack. By breaking down the attack lifecycle from the adversary's perspective, security teams can identify, disrupt, and prevent threats at different stages. It takes inspiration from the military's kill chain, which is a step by step approach that identifies and stops enemy activity.
The framework breaks down cyberattack into 7 tightly linked phases:

1. Reconnaissance: The attacker researches and identifies the target, gathering information on the organization's network, systems, and employees.
2. Weaponization: The attacker pairs a malicious payload (like malware) with an exploit designed to take advantage of specific vulnerabilities found during reconnaissance.
3. Delivery: The weaponized payload is transmitted to the target environment via methods such as phishing emails, infected USB drives, or malicious websites.
4. Exploitation: The malicious code is triggered or executed, allowing the attacker to take advantage of the targeted vulnerability.
5. Installation: The attacker installs malware or a backdoor on the compromised system to ensure continuous, long-term access (persistence).
6. Command and Control (C2): The compromised system establishes an outbound connection to a server controlled by the attacker, allowing remote control over the target network.
7. Actions on Objectives: The attacker achieves their final goal, which may include data exfiltration, ransomware deployment, or destroying network operations.

Using FIM we can neutralize the attack in the most critical stages of the kill chain. During exploitation and installation, attackers execute malicious code to gain a foothold and establish persistence, often installing rootkits, Trojans, or custom web shells.
FIM continuously monitors highly targeted operating system directories (like C:\Windows\System32 or /etc/). The moment a new binary is created or an executable file is replaced, FIM alerts the Security Operations Center (SOC) immediately. This stops the attacker from solidifying their hold on the machine.

How FIM works and what kind of files do we monitor?

FIM takes a cryptographic hash (like SHA-256) of files at a known-good baseline state. It then periodically re-hashes those same files and compares the results. If a hash changes, the file was modified, even a single byte difference produces a completely different hash.

The basic workflow

1. Baseline creation: An agent scans designated files/directories and records hashes, permissions, ownership, timestamps, and file size into a secure database.
2. Scheduled or real-time scanning: Either periodically re-scans and compares, or hooks into the OS kernel (via inotify on Linux, FSEvents on macOS, or the Windows change journal) to get immediate change notifications.
3. Alerting: When a deviation is detected, it logs the event and sends an alert with details: what changed, when, and sometimes which process made the change.
4. Review and response: A security team reviews whether the change was authorized (a software update, config change) or suspicious (malware, intrusion).

FIM monitors File Content(hash), Permissions and ownership, Timestamps(created, modified, accessed), File size, Directory Structure(additions/deletions).

So what files to monitor? That is a important question. Not all files needs monitoring and its a waste of time monitoring each and every file in the system. Let's see what to monitor and what you dont.

What Files Feed Monitoring

System Binaries & Executables

• /bin, /sbin, /usr/bin on Linux — core OS commands like ls, sudo, ssh
• DLLs and .exe files on Windows (System32)
• If malware replaces these, it's serious

Configuration Files

• /etc/passwd, /etc/shadow, /etc/sudoers — user accounts and privileges
• SSH configs (sshd_config, authorized_keys)
• Firewall rules, cron jobs
• App configs (nginx, Apache, database)

Boot & Kernel Components

• Bootloader files
• Kernel modules (/lib/modules)
• Tampered boot components can compromise the entire system before the OS even loads

Web Application Files

• PHP, JS, HTML files on a web server
• A common attack pattern is dropping a web shell (a small backdoor script) into a web directory; FIM catches this

Security-Sensitive Data Files

• Certificate and key files (.pem, .key)
• /etc/hosts, DNS hijacking via this file is a classic attack
• PAM modules (authentication stack)

Log Files (Special Case)

• These are monitored differently, watch for deletions or truncations rather than modifications
• Attackers often wipe logs to cover tracks

What Files You Generally Don't Monitor

• Frequently changing files (databases, mail spools, temp files) — they'd generate constant noise
• Log files that grow normally
• User home directories in most cases because it's too much churn

The art of FIM is narrowing the scope to files that should almost never change in normal operation, so that any alert is genuinely meaningful rather than noise.

Configure the FIM module

Till now this article has been linux heavy so for this part I will be using Windows agent to show you how to configure the FIM module. Although tech people like to bash on Windows and almost all of them see Linux as the superior OS, we should accept the fact that there are a lot of Windows machine out there. But always remember, the concepts remain the same no matter what OS you are on.

We need to configure what files or directory to monitor in the Wazuh agent conifg file. In Linux it is /var/ossec/etc/ossec.conf, which we have seen already. In Windows the same file lives in C:\Program Files (x86)\ossec-agent\ossec.conf
Add the file or directory you want to monitor in with the <directories> option within the

<syscheck>
    <directories>FILEPATH_OF_MONITORED_FILE</directories>
    <directories>FILEPATH_OF_MONITORED_DIRECTORY</directories>
</syscheck>

Real-Life Windows Example

Track C:\Windows\System32\drivers\etc\hosts -> this file maps hostnames to IP addresses. Attackers commonly modify it to redirect legitimate domains (e.g. your bank's website) to malicious servers. This is known as 'DNS hijacking/DNS spoofing/Host file poisoning'. This hosts file should almost never change in normal operation, making it an ideal FIM target.

<syscheck>
    <directories>C:\Windows\System32\drivers\etc\hosts</directories>
</syscheck>

⚠️ Every command in Windows should be run as administrator so open powershell as administrator.

Run command notepad C:\Program Files (x86)\ossec-agent\ossec.conf in privileged powershell to open the ossec.conf file. I have also changed the frequency to 360 seconds. This means File Integrity check will run every 360 seconds. By default this value is 43200(12 hrs).
Now restart the wazuh agent by running the command:
Restart-Service -Name WazuhSvc Now let's change the hosts file in Windows client and see if an alert is triggered or not.
In a priviledged powershell run notepad C:\Windows\System32\drivers\etc\hosts to open the hosts file. This is the original hosts file in my windows machine where the address 38.25.36.10 is associated with x.acme.com(although this is just an example and actually commented out it does not matter, we just want to monitor the integrity of the file).
Now I will make a small change and change the Ip address to 38.25.36.1. We have set the frequency to 360 ie 5 mins. Syscheck needs 2 scans to detect a change. First scan builds the baseline and second scan compares the current state to baseline. The first scan happens immediately after agent restart. Every subsequent scans then take place after 5 mins. So we need to wait about 5 minutes to see the alert. After some time, the alert will appear in the wazuh dashboard. To see the alert go to your agent dashboard then click File Integrity Monitoring then click Events. The alert appears in the log with alert level 7.

We saw that wazuh has a Vulnerability Module here. But how does this work? Let's find out.

The Wazuh Agent has a module called Syscollector. This module is responsible for collecting system inventory data. The inventory data includes information about the Operating system(version. build, patch level) and Installed packages/application(Names and versions). The collected data is periodically sent to the Wazuh server and stored in a local SQLite database. Each agent has its separate inventory, which is continuously updated to reflect the changes on the monitored endpoint.
One added dimension for Windows: For Microsoft Windows System and certain Microsoft products, the module also includes the hotfixes options in Syscollecctor Configuration. This means for Windows, inventory effectively extends to include applied hotfixes, not just installed package versions.

The Wazuh Server has the Vulnerability Detection module. This module analyzes the inventory by correlating it with vulnerability information from the Wazuh Cyber Threat Intelligence(CTI) platform. A package is marked as vulnerable when its installed version falls within the affected range of a CVE. Matches generate alerts and get stored in a queryable, agent-filterable vulnerability inventory.

The CTI Platform (this replaces the old per-vendor feed model)

The Wazuh CTI platform aggregates vulnerability data from operating system vendors and public vulnerability databases into one unified repository.

Sources:

Operating system vendors:

• AlmaLinux
• Amazon Linux
• Arch Linux
• Ubuntu (Canonical)
• Debian
• Fedora
• Oracle Linux
• RHEL
• Rocky Linux
• SUSE Linux Enterprise

Security databases:

• Microsoft Security Updates (MSU)
• National Vulnerability Database (NVD)
• Open Source Vulnerabilities (OSV)
• Cybersecurity and Infrastructure Security Agency (CISA)

The VDP (Vulnerability Detector Provider) : the normalization layer

This is the piece most people miss. The VDP organizes vulnerability data from multiple vendors into a standardized format, producing consistent intelligence that let's the module identify vulnerabilities across Windows, CentOS, RHEL, Ubuntu, Debian, Amazon Linux, Arch Linux, SUSE, and macOS.

It does this in three steps:

1. Content migration: Fetches raw vendor data and normalizes it into the CVE JSON v5 format.
2. Data sanitization: Fixes inconsistencies such as version mismatches and typographical errors and fills missing fields.
3. Content merging: Combines vendor-specific content with internally maintained intelligence (product name mappings, translations, and OS base rules) to produce one unique document per CVE.

The Wazuh manager retrieves this intelligence by querying the CTI API or an offline local repository and compares newly fetched content against previously stored data to detect updates, making the process incremental rather than requiring a full re-download each time.

Alert Generation

Now this is what you need to understand to solve problems that may frustate you. This is the part with real operational gotchas. This is the most practically important section if you're trying to understand why you're not seeing an alert you expected.

OS-level alerts

• These are never generated during the initial inventory scan. When an Wazuh Agent first syncs with the Wazuh Manager, OS version or patch changes are not treated as new events.
• Alerts only fire on subsequent scans when an actual change inm OS version or patch state is detected.

Package-level alerts

• These only fire when a vulnerability is added to or removed from inventory due to a package installation or removal.
• The event must be captured during a scheduled Syscollector scan.
• If packages change while the Wazuh agent is stopped, no alert is generated.
• If the change is only detected after the Wazuh agent restarts, no alert is generated.

Two more easy-to-miss cases:

• Clustered managers: If an agent reconnects to a different node, it re-syncs its inventory with the new node, but that initial sync does not generate alerts even if changes exist.
• CTI content updates: When CVE definitions, translations, or mapping rules are updated server-side, every agent gets re-evaluated against the new content, but that re-evaluation itself does not generate alerts.

In short, alerts require a detected delta during a live, scheduled scan—not just the existence of a vulnerability in the data. This explains a common confusion: a freshly enrolled agent with 200 known CVEs will not generate 200 alerts. Instead, it silently populates the inventory, and alerts only begin appearing when changes are detected in future scans.

Viewing the data

In the dashboard, vulnerability information is available under:

Threat Intelligence → Vulnerability Detection

• Dashboard tab — displays severity distributions, vulnerability scores, and asset trends.
• Inventory tab — displays the complete per-CVE inventory and provides links to the Wazuh CTI site for detailed vulnerability information.

The Vulnerability Detection module is enabled by default on the Wazuh manager. The default vulnerability detection setting is in the following block in the Wazuh manager configuaration file at /var/ossec/etc/ossec.conf

I basically have tried to narrow down the Vulnerability detection of Wazuh in this section of the article. But I highly encourage you to check out the official docs here for more up to date and detailed information.

PLACEHOLDER — active response

There seems to be a confusion that Wazuh(SIEM in general) is just a passive tool where you see logs and alerts and take actions manually. While this was true traditionally, modern SIEM platform are capable of automatically responding to threats as well. Complex responses are typically handled via Security Orchestration, Automation and Response(SOAR) platform. Lern more about SOAR here.
SOAR is a different platform that needs to be connected in SIEM platforms, but there is a built in module in wazuh called Active Response that helps automate response actions based on specific triggers. This is very useful and often overlooked module in Wazuh. It massively helps reduce alert fatigue.

How does Wazuh Active Response work?

The Wazuh Active Response module is configured with scripts. Wazuh provides some out-of-the scrips for basic triggers like blocking malicious network access and deleting malicious files on monitored endpoints, but we can also write out own scripts in python, bash etc)(check out my article on bash scripting here). The Wazuh Active Response module executes these scripts on monitored endpoints when an alert of a specific rule ID, level, or rule group triggers. You can have more than one script file for a trigger.

The Wazuh Active Response mechanism

We have already seen how logs travel from Wazuh Agent to the Wazuh Manager, how logs are decoded and a rule is triggered generating an alert. For active response, the followings further steps take place:

1. The manager checks its configurations (ossec.conf) for an explicit <active-response> block tied to that rule ID, group, or severity level.
2. If a match exists, the manager looks up the corresponding <command> block to identify the exact filename of the remediation script (e.g., firewall-drop.sh or a custom script file).
3. The manager sends an encrypted command string along with this JSON payload back down to the target agent(s) through the established agent-manager communication channel. This JSON payload contains things like full generated alert including target IP address, source usernames, file hashes and rule severities.
4. The Wazuh agent receives the payload and reads the target executable from its local directory:
   • Linux:/var/ossec/active-response/bin/
   • Windows:C:\Program Files (x86)\ossec-agent\active-response\bin\
5. The agent runs the script as a subprocess, passing the JSON alert metadata directly into the script's standard input (stdin).
6. The active response script parses the stdin payload, extracts the target indicators (like an IP address), and runs local system utilities to neutralize the threat. Examples: Blocing an IP via iptables, disabling a compromised user account via net user, or deleting malware.
7. The script outputs its execution status to the local agent log (active-responses.log) for auditing.

Practical Active Response Configuration And Response Trigger

Let's setup a simple Lab to see the Active Response module in action. First we will trigger out-of-the-box active response scripts provided by Wazuh(see the full list of provided scripts here.) Later we will write a custom script

The scenario is, I want to block IP of an attacker using the firewall-drop active response after multiple failed SSH login attempts. I will use my Kali Linux as the SSH server and I will use my Fedora host to perform multiple failed login attempts.

The sshd service is active in my Kali machine and the ip of my Kali machine is 192.168.122.76.

Wazuh Server Setup

1. Configure the <command> block in the Wazuh server /var/ossec/etc/ossec.conf Here,
   
   • <name>: Sets a name for the command. In this case, firewall-drop.
   • <executable>: Specifies the active response script or executable that must run upon a trigger. You don't need to specify the file name extension unless you have multiple scripts sharing the same name. In this case, it is the firewall-drop executable.
   • <timeout_allowed>: Allows a timeout after a period of time. Setting this value to yes reverts the action after a period of time.
2. Now add an <active-response> block within the <ossec_config> tag in the same Wazuh server /var/ossec/etc/ossec.conf file.
   • <command>: Specifies the command to configure. This is the command name defined in the previous step.
   • <location>: Specifies where the command must execute. The options are:
     • local: It runs the script on the monitored endpoint that generated the alert.
     • server: It runs the script on the Wazuh server.
     • defined-agent: It runs the script on a predefined agent. Use the <agent_id> tag to specify the ID of the Wazuh agent that must run the script regardless of where the event occurred. For example:

       <ossec_config>
         <active-response>
           <disabled>no</disabled>
           <command>host-deny</command>
           <location>defined-agent</location>
           <agent_id>001</agent_id>
           <level>10</level>
           <timeout>180</timeout>
         </active-response>
       </ossec_config>
       

     • all: Every Wazuh agent in the environment must run the script. Use this option with caution. Incorrect configuration can cause problems in your environment.
   • <timeout>: Specifies how long the active response action is effective, in seconds.

   Source: Official Wazuh Docs

Wazuh Client Setup

No configuration is required for agent while using out of the box script. The script we are trying to run is located in /var/ossec/active-response/bin by default.

But what did we actually configure?
After the agent sends the log and a rule is triggered in the manager, the manager checks the <active-response> block of the config file. It understands that the agent in which ssh brute force attack has been attempted(Given by rule id 5763) needs to execute the firewall-drop script. Then, after 180 seconds it needs to revert the changes it made after executing the script. The firewall-drop is a script located in the monitored endpoint's /var/ossec/active-response/bin/firewall-drop that blocks a specific IP address. But how does it know which IP address to block? This information should be passed as argument to the script. This is done by the manager. But how?

After a match in the active-response , the manager looks up the corresponding <command> block to identify the exact filename of the remediation script (e.g., firewall-drop or some custom script as well). It then makes a JSON payload which looks like:

{
  "version": 1,
  "origin": {
    "name": "node01",
    "module": "wazuh-analysisd"
  },
  "command": "add",
  "parameters": {
    "extra_args": [],
    "alert": {
      "id": "1719999999.123456",
      "timestamp": "2026-06-22T10:15:30.123+0000",
      "rule": {
        "level": 10,
        "description": "sshd: Multiple authentication failures.",
        "id": "5712",
        "mail": false,
        "groups": ["syslog", "sshd", "authentication_failures"],
        "firedtimes": 8
      },
      "agent": {
        "id": "003",
        "name": "web-server-01",
        "ip": "10.0.0.15"
      },
      "manager": {
        "name": "node01"
      },
      "data": {
        "srcip": "192.168.1.100",
        "srcuser": "admin",
        "dstuser": "root",
        "protocol": "ssh"
      },
      "decoder": {
        "name": "sshd"
      },
      "location": "/var/log/secure"
    }
  }
}

Field-by-field for this case

Field	Description	Example value
version	Payload format version	1
origin.name	Manager/node that sent the command	node01
origin.module	Module that triggered it	wazuh-analysisd
command	add blocks the IP now; delete is sent automatically later to unblock it once the AR timeout expires	add
parameters.extra_args	Extra CLI args from the <arguments> block in ossec.conf, if configured	[]
parameters.alert.rule.id / level	Which rule fired and its severity. This must meet the <rules_id> / <level> filter set in the active-response config	5763 / 10
parameters.alert.data.srcip	This is the key field firewall-drop.sh/.cmd actually reads — it's the IP that gets blocked	192.168.1.100
parameters.alert.agent.id/name/ip	The agent that generated the alert (and where the script runs, unless AR is set to manager-side execution)	003 / web-server-01

How firewall-drop uses it

The script (firewall-drop.sh on Linux, firewall-drop.cmd on Windows) reads stdin, parses this JSON, checks command:

• add → extracts parameters.alert.data.srcip and inserts a DROP rule (iptables/nftables/netsh) for that IP, then logs it to active-responses.log.
• delete → removes that same rule for that IP.

If srcip isn't present in the alert's data object, the active response won't have an IP to block and will typically fail or no-op, this is why firewall-drop is only mapped to rules that reliably populate srcip (e.g., SSH brute force, port scan rules).

So now I will attack my Kali Linux agent using a open source brute force tool called hydra. I am going to perfrom a ssh brute force on my Kali machine which has IP address 192.168.122.76 using my fedora host. Before attacking let me ping my Kali machine from fedora. The ping is successful which means my Fedora host can reach kali. Now I will attack using the command:
sudo hydra -t 4 -l root -P password.txt 192.168.122.76 ssh
Here,

• root->username
• password.txt->File consisting all the passwords to try
• 192.168.122.76->Ip address of the target machine

password.txt is simply a text file created at location from where this command is run:

You need to create this file. I have created a simple file with 10 passwords to try. How hydra does brute force is simple, it connects to ssh at the target IP address using username root and tries all the passwords written in the paswords.txt file.

After hydra complets the attack let's check the wazuh dashboard.

As we can see rule 5763(ssh brute force attack) is triggered and alert is shown in the dashboard. Now the manager checks the <active-response> block of its config file and sees that it needs to run a script named firewall-drop. It then checks the <command> block to see further information(like name of the actual executable and nature; stateless or stateful) about frewall-drop.
Then the Wazuh Manager sends the JSON payload mentioned above to the Wazuh client into the script's standard input. The script then runs using the defined parameters in the payload, blocking the IP address of the attacker. After the attack if I try to ping the Kali machine again withing 180 seconds(this is the timeout we configured), the ping will fail.

This shows that active reponse worked. Which means the script added a DROP rule for my fedora IP to iptables.
Also we can see the iptable for DROP rule using

sudo iptables -L -n | grep DROP

This shows that Kali added drop rules to the Fedora IP. The IP of Fedora for Kali is 192.168.122.1for Kali because Kali is the VM hosted by Fedora so Fedora is the gateway for Kali, this is how VMs use network.
Now after 180 seconds the Wazuh Manager will again send the JSON payload but this time the command field in the JSON payload will be 'delete' instead of add so the script will romove the DROP rule for that IP, effectively reverting the action. Now if I ping again, it will be successful again.

And the DROP rule will be removed.

No output means there is no DROP rule in the iptable.

We can also write custom responses for actions for which Wazuh does not provide out of the box scripts for. We will see how to set this up with an example in the next section; Writing Custom Rules