Creating Custom Detection Rules in Wazuh
Overview
One of the biggest advantages of running your own SIEM is the ability to decide what activity actually matters in your environment. Built-in detection rules provide a strong starting point, but every network is different. A login event that is completely normal for one organization might deserve immediate investigation somewhere else.
Creating custom detection rules in Wazuh allows you to take the events Wazuh is already collecting and turn them into detections that reflect your own systems, users, applications, and security priorities.
I have been using Wazuh as the SIEM for my own security monitoring environment, collecting events from Windows endpoints, servers, network devices, and other systems. As I worked with the platform, custom rules became one of the most useful parts of the project because they allowed me to move beyond simply collecting logs and start detecting activity that was specifically important to my network.
This guide explains how custom Wazuh rules work, how I use them, and why creating your own detections is an important step when building a practical security monitoring environment.
Why Create Custom Wazuh Rules?
Wazuh includes thousands of rules for detecting authentication events, malware activity, system changes, vulnerabilities, suspicious processes, and many other security-related events.
That does not mean every environment should rely exclusively on the default rules.
Your organization might want to detect something very specific, such as repeated account lockouts, interactive logins to a sensitive server, remote desktop activity, changes to an important Windows service, or events generated by a particular application.
Custom rules allow those events to be given additional context.
Instead of asking:
“What alerts does Wazuh generate?”
The better question becomes:
“What activity do I want Wazuh to tell me about?”
That change in thinking is an important part of developing useful SIEM detections.
Understanding Wazuh Rules
Wazuh processes incoming log data through decoders and rules.
A decoder identifies and extracts useful information from a log entry. Once Wazuh understands the event, its rules determine whether that event matches conditions that should generate an alert.
A simplified workflow looks like this:
Endpoint or Device
|
v
Log
|
v
Decoder
|
v
Rule
|
v
Alert
The rule can evaluate information such as event IDs, usernames, source addresses, processes, authentication types, or other fields extracted from the original event.
Custom rules build on this process rather than replacing it.
The Wazuh Local Rules File
Custom rules can be stored in:
/var/ossec/etc/rules/local_rules.xml
This makes local_rules.xml an important file when customizing a Wazuh deployment.
Before making changes to detection rules, it is a good idea to create a backup:
sudo cp /var/ossec/etc/rules/local_rules.xml /var/ossec/etc/rules/local_rules.xml.bak
The original file can then be edited with an editor such as:
sudo nano /var/ossec/etc/rules/local_rules.xml
Important: Rule syntax needs to be correct. A malformed XML configuration can prevent rules from loading correctly. Changes should be tested before being treated as production-ready detections.
Example Structure of a Custom Rule
A basic custom Wazuh rule may resemble the following:
<group name="local,">
<rule id="100001" level="10">
<if_sid>EXISTING_RULE_ID</if_sid>
<description>Custom detection description</description>
</rule>
</group>
This example is intentionally generic because the correct parent rule and matching conditions depend on the event being detected.
The important components are:
| Element | Purpose |
|---|---|
<group> | Organizes related rules |
<rule> | Defines the custom rule |
id | Provides a unique identifier |
level | Determines alert severity |
<if_sid> | Links the rule to another Wazuh rule |
<description> | Describes what was detected |
Additional conditions can be added depending on what information is available in the decoded event.
Detection Begins With the Log
One lesson that becomes obvious when working with custom SIEM rules is that you should not start by writing XML.
Start with the event.
Before creating a detection, determine exactly what Wazuh is receiving. Look at the original event, determine which decoder processed it, identify the rule that currently matches it, and examine the fields available for additional filtering.
The process is closer to:
Generate Event
↓
Find Event in Wazuh
↓
Inspect Decoded Fields
↓
Identify Existing Rule
↓
Determine Detection Logic
↓
Create Custom Rule
↓
Test
↓
Tune
This makes troubleshooting considerably easier than attempting to create a rule based only on what you expect the log to contain.
Testing Rules With wazuh-logtest
Wazuh provides a particularly useful utility for testing detection logic:
sudo /var/ossec/bin/wazuh-logtest
The tool allows you to provide a log entry and see how Wazuh processes it.
This can help identify:
- Which decoder processed the event.
- Which fields were extracted.
- Which rule matched.
- The resulting alert level.
- Whether a new custom rule is being triggered.
This is extremely useful when developing custom rules because a rule that looks correct is not necessarily a rule that will match the actual event.
Testing should always be part of the process.
[Screenshot – Wazuh Logtest Custom Rule]
Choosing an Alert Level
Another important consideration when creating custom detection rules in Wazuh is severity.
Not every interesting event should become a critical alert.
For example, a successful interactive login may be worth recording but might not deserve the same severity as repeated authentication failures followed by a successful remote login.
The goal is not to create as many high-severity alerts as possible.
The goal is to make severity meaningful.
If everything is critical, eventually nothing feels critical.
Real-World Example: Windows Account Lockouts
Windows account lockouts are a good example of why custom detections can be valuable.
Windows Security Event ID:
4740
indicates that a user account was locked out.
That event could be caused by something harmless, such as an old password stored on another device, but it could also be associated with repeated authentication attempts against an account.
In my environment, this is exactly the kind of event I want Wazuh to bring to my attention.
Rather than continuously reviewing Windows Security logs manually, Wazuh can detect the event and elevate it according to the monitoring requirements of the environment.
[Screenshot – Wazuh Windows Account Lockout Alert]
Real-World Example: Monitoring Interactive Logins
Windows authentication events provide another useful opportunity for custom detection.
Event ID:
4624
represents a successful account logon, but the event alone does not tell the entire story.
The Logon Type provides additional context.
For example:
Logon Type 2 = Interactive
Logon Type 10 = RemoteInteractive
A Type 2 login generally represents someone logging onto the system interactively, while Type 10 is commonly associated with Remote Desktop activity.
Depending on the endpoint, those events may deserve very different treatment.
A Remote Desktop login to an administrative server, for example, could be considerably more interesting than a normal workstation login.
This is where custom detection logic becomes valuable: the detection can consider not just whether authentication succeeded, but how it occurred and where it occurred.
Avoiding Alert Fatigue
Creating custom rules is easy.
Creating useful custom rules takes more thought.
It is tempting to alert on every event that looks interesting when first building a SIEM. The result can quickly become hundreds or thousands of alerts that nobody realistically investigates.
A better approach is to ask:
- Is this event actually actionable?
- Would I investigate this if it happened?
- How frequently does it normally occur?
- Does the event require additional context?
- Should it generate an alert or simply remain searchable?
- Is there a known legitimate source that should be excluded?
These questions help turn raw logging into useful security monitoring.
Suppression Rules Matter Too
Custom detection does not always mean creating more alerts.
Sometimes the correct solution is reducing noise.
A known system might continuously generate an event that has already been investigated and determined to be legitimate. If that activity cannot reasonably be eliminated at the source, carefully targeted suppression can prevent it from overwhelming useful detections.
The key word is targeted.
Suppressing an entire event category because one system generates noise could hide legitimate malicious activity elsewhere. Whenever possible, suppression should be based on enough context to identify the known benign condition without eliminating visibility into unrelated events.
Document Every Custom Rule
Custom rules should also be documented.
At minimum, documentation should record:
| Information | Description |
|---|---|
| Rule ID | Unique Wazuh rule identifier |
| Purpose | Why the rule exists |
| Data Source | Windows, Linux, firewall, application, etc. |
| Detection Logic | Conditions that cause the rule to match |
| Severity | Assigned Wazuh alert level |
| Expected Activity | What normal behavior looks like |
| False Positives | Known legitimate triggers |
| Response | What should happen when it fires |
Six months later, a rule named 100047 will mean very little without documentation explaining why it exists.
Good detection engineering includes maintaining the detection just as much as creating it.
Custom Rules Turn Logs Into Security Monitoring
Collecting logs is only the beginning of building a SIEM.
The real value appears when those logs can answer meaningful questions about the environment.
Who logged into this server remotely?
Why did this account become locked?
Why is this endpoint generating repeated authentication failures?
Did this behavior occur anywhere else?
Is this normal for this system?
Creating custom detection rules in Wazuh helps transform a large collection of events into monitoring that reflects the systems you are actually responsible for protecting.
The more familiar you become with your environment, the more useful those rules can become. Instead of relying entirely on generic detections, you begin building security monitoring around what normal looks like on your own network.
That is where a SIEM starts becoming genuinely useful.
Key Takeaways
- Main lesson: Custom Wazuh rules allow detection logic to be tailored to the activity that actually matters in your environment.
- Important command:
sudo /var/ossec/bin/wazuh-logtest - Skills practiced: Log analysis, SIEM administration, Windows event analysis, detection engineering, rule testing, and alert tuning.
- Defensive considerations: Avoid excessive alerting, test rules before deployment, document custom detections, and keep suppression rules narrowly targeted.
- Next step: Build detections around known behavior in your environment and continually tune them as you learn what normal activity looks like.