Wazuh uses XML-based detection rules to analyze security events, correlate log data, and generate alerts when suspicious activity is detected. Every rule is assigned a unique numerical identifier, known as a rule ID, which allows the Wazuh manager to distinguish one detection rule from another.
These IDs are much more than simple labels, they are fundamental to how Wazuh processes events, builds rule relationships, and generates accurate alerts.
Rather than creating entirely new rules, many choose to overwrite or replace existing rules so they can change alert levels, suppress noisy detections, add additional conditions, or tailor behavior to their environment. While this is a common and supported practice, it must be done carefully.
Improperly overwriting rule IDs can introduce serious configuration problems.
Duplicate IDs, conflicting rule definitions, and incorrectly copied vendor rules may prevent Wazuh from loading successfully or produce unpredictable detection behavior.
In some cases, rule conflicts can cause startup failures, XML validation errors, or alerts that never trigger because the intended rule has been replaced unintentionally.
Fortunately, avoiding these issues is straightforward once you understand how Wazuh manages rule identifiers internally.
In this guide, you’ll learn how Wazuh assigns and processes rule IDs, why conflicts occur, how to safely overwrite existing rules without breaking your deployment, and the best practices that help ensure your custom rules remain compatible with future upgrades.
Understanding Wazuh Rule IDs
What Are Rule IDs?
A rule ID is a unique integer assigned to every detection rule defined in Wazuh’s XML ruleset.
Whenever Wazuh evaluates incoming events, each matching rule is identified by its rule ID, allowing the manager to determine exactly which detection logic has been triggered.
For example, a rule may detect repeated failed SSH login attempts, while another identifies privilege escalation activity.
Even if two rules inspect similar logs, each one requires its own unique identifier so Wazuh can distinguish them throughout the detection pipeline.
Rule IDs also appear in generated alerts, making them invaluable for:
- Troubleshooting rule behavior
- Searching alerts in the Wazuh Dashboard
- Creating alert suppressions
- Building active response actions
- Referencing parent or child rules
Understanding rule IDs is essential before attempting any customization.
How Wazuh Uses Rule IDs Internally
Internally, Wazuh indexes every loaded rule by its ID during startup.
As XML rule files are parsed, the manager builds an in-memory rule tree that allows it to efficiently evaluate incoming events.
Rule IDs are used throughout several internal processes, including:
- Matching decoded events against detection logic
- Linking child rules to parent rules using
<if_sid> - Building rule inheritance chains
- Managing rule dependencies
- Producing alert metadata
- Triggering Active Response actions
Because of this internal indexing process, Wazuh expects every rule ID to be unique unless a rule is intentionally overridden using supported methods.
The relationship between decoders and rules is also important.
Decoders first normalize raw log data into structured fields. Rules then evaluate those decoded fields and determine whether an alert should be generated.
Related Guide: Custom Decoder Isn’t Matching: Wazuh Logtest Deep Dive
Why Rule IDs Must Be Unique
Unique rule IDs are one of the core requirements of the Wazuh rules engine.
During startup, Wazuh performs several validation stages before the manager begins monitoring logs.
Duplicate rule IDs can interrupt these stages and prevent the ruleset from loading correctly.
Unique IDs are required for several reasons.
Rule Loading Process
When the manager loads XML rule files, every rule is indexed by its ID.
If two unrelated rules define the same identifier, Wazuh cannot reliably determine which definition should be used.
This ambiguity often results in startup errors or rule loading failures.
XML Validation
Before activating the ruleset, Wazuh validates XML syntax and rule consistency.
Duplicate IDs may trigger validation failures or warnings depending on how the rules are defined.
These errors should always be resolved before deploying changes to production.
Related Guide: Troubleshooting wazuh-logtest: Why Alerts Are Missing from JSON Output
Alert Generation
Every alert references the rule that generated it.
If conflicting rule IDs exist, alerts may:
- Reference the wrong rule
- Use unexpected severity levels
- Contain incorrect descriptions
- Trigger unintended Active Responses
This can significantly complicate incident investigations.
Rule Dependency Mapping
Many Wazuh rules depend on other rules using directives such as:
<if_sid><if_group><if_matched_sid><if_matched_group>
These relationships depend entirely on stable rule IDs.
If an ID unexpectedly changes or conflicts with another rule, dependent rules may stop working correctly without producing obvious errors.
For complex custom rulesets, preserving consistent rule IDs is critical.
Default Rule ID Ranges in Wazuh
Wazuh ships with thousands of built-in detection rules covering operating systems, network devices, cloud platforms, applications, compliance frameworks, and threat intelligence integrations.
These rules occupy predefined ID ranges that are maintained by the Wazuh development team.
Following the official rule ID recommendations greatly reduces maintenance effort and minimizes upgrade-related conflicts.
According to the official Wazuh documentation, administrators should keep vendor rules intact whenever possible and place custom rules in appropriate local rule files using recommended custom ID ranges rather than modifying shipped rules directly.
Built-in Rules
Default rules included with Wazuh cover:
- Authentication events
- File Integrity Monitoring (FIM)
- Malware detection
- Vulnerability detection
- Cloud integrations
- Windows Event Logs
- Linux Syslog
- Network IDS integrations
- Compliance monitoring
These rules are updated regularly during Wazuh upgrades.
Reserved Ranges
Some rule ID ranges are reserved for official Wazuh content.
Administrators should avoid creating arbitrary rules within these reserved spaces because future releases may introduce new rules that occupy those IDs, resulting in conflicts after an upgrade.
Recommended Ranges for Custom Rules
The Wazuh documentation recommends storing custom rules inside local_rules.xml or separate custom rule files while assigning IDs from ranges intended for local customization.
Using dedicated custom ID ranges provides several advantages:
- Prevents collisions with vendor rules
- Simplifies troubleshooting
- Makes upgrades safer
- Improves maintainability
- Keeps custom content organized
Why Following the Official Ranges Reduces Upgrade Issues
One of the most common causes of post-upgrade rule failures is modifying vendor-supplied rules directly.
During an upgrade, official rules are replaced with newer versions.
If local modifications exist inside those files, they are often overwritten or become incompatible with updated dependencies.
Using recommended custom rule ranges instead allows administrators to preserve their customizations while benefiting from future ruleset improvements.
For long-term maintenance, overriding behavior through local custom rules is significantly safer than editing the shipped ruleset.
What Causes Rule ID Conflicts?
Rule ID conflicts usually occur when administrators unintentionally define multiple rules with the same identifier or modify the default ruleset in unsupported ways.
Although these problems are easy to create, they can often be avoided by following consistent rule management practices.
Understanding the most common causes helps prevent difficult troubleshooting later.
Duplicate Rule IDs
The simplest cause of a conflict is assigning the same numerical ID to more than one rule.
During startup, Wazuh expects each rule to have a unique identifier unless it is intentionally replacing an existing rule using supported mechanisms.
Duplicate IDs commonly appear after rapid development or when multiple administrators contribute custom rules without coordinating ID assignments.
Defining the Same ID Twice
A frequent mistake is creating a new rule and accidentally reusing an ID that already exists elsewhere.
For example:
- Copying an existing rule as a template
- Forgetting to update the
<rule id="">attribute - Reusing IDs from previous testing
Even if the rule logic is different, duplicate IDs create ambiguity during rule loading.
Multiple Custom Rule Files
Large deployments often separate rules into multiple XML files.
While this improves organization, it also increases the likelihood that different files define the same rule ID.
Examples include:
local_rules.xmlcustom_linux_rules.xmlcustom_windows_rules.xmlthreat_detection.xml
Without centralized ID management, collisions become increasingly common.
Copying Vendor Rules Into Local Rules
Another common source of conflicts occurs when administrators copy an official Wazuh rule into a local rules file without changing how it should be overridden.
Although copying the XML may appear harmless, Wazuh now encounters two definitions for the same rule during startup.
Common Mistake When Customizing Detections
Many administrators copy an existing vendor rule because they only want to:
- Change the alert level
- Modify the description
- Add additional matching conditions
- Ignore specific events
Simply duplicating the rule is not the recommended approach.
Instead, Wazuh provides supported methods for overriding or extending existing rules while maintaining compatibility with future updates.
Upgrade Complications
Editing or duplicating built-in rules can create maintenance problems after upgrades.
As Wazuh introduces new rule logic, your copied version may:
- Miss important improvements
- Reference outdated parent rules
- Produce inconsistent alerts
- Conflict with newly added rule IDs
Using supported customization methods significantly reduces these risks.
Importing Community Rule Sets
Many organizations import publicly available rule packs from GitHub or security communities.
While these can expand detection coverage, they often introduce IDs that overlap with existing custom content.
Careful review is essential before importing third-party rules into production.
Overlapping IDs
Community rule packs are usually developed independently.
Two different repositories may assign identical IDs without any awareness of each other, creating immediate conflicts when both are installed.
Third-Party Integrations
Security products and integrations sometimes include their own Wazuh rule files.
Examples include:
- Endpoint security products
- Network monitoring tools
- Threat intelligence feeds
- Custom application integrations
Administrators should always inspect imported rule IDs before deployment.
Rule Packs from Different Sources
Organizations frequently merge:
- Internal detection rules
- Open-source repositories
- Vendor integrations
- Security team contributions
Without proper governance, duplicate IDs become almost inevitable.
Merging Multiple Repositories
Large enterprises often maintain separate repositories for different teams.
When those repositories are merged into a centralized Wazuh deployment, overlapping IDs may not be discovered until the manager fails to load.
Version control reviews and automated validation help detect these problems early.
Version Mismatches
Running rule packs created for different Wazuh versions can also introduce conflicts.
Older rule collections may reference IDs that newer Wazuh releases already use or reserve, leading to compatibility issues after upgrades.
Manual Editing Errors
Human error remains one of the leading causes of rule ID conflicts.
Even experienced administrators occasionally overlook duplicated IDs while making rapid changes.
Copy-Paste Mistakes
Copying existing rules to accelerate development is common, but forgetting to update the rule ID is equally common.
This simple oversight can prevent the ruleset from loading successfully.
Forgotten IDs
Over time, administrators may forget which IDs have already been assigned, especially in environments with hundreds of custom rules.
Maintaining an internal ID allocation document or using version control reviews helps prevent accidental reuse.
Renaming Files Without Updating Rules
Renaming or reorganizing XML rule files does not automatically eliminate duplicate IDs.
If the original file remains loaded alongside the renamed version, Wazuh may process both files and encounter duplicate rule definitions.
Keeping custom rules organized and periodically auditing loaded rule files helps prevent these subtle configuration mistakes.
Related Guide: How to Test Wazuh Rules
Can You Actually Overwrite a Wazuh Rule?
One of the most common misconceptions among Wazuh administrators is that customizing a built-in rule requires editing the original XML file or redefining the same rule ID.
In reality, Wazuh provides safer mechanisms for extending or changing detection behavior without modifying the default ruleset.
Understanding the difference between overwriting, overriding, and extending rules is essential for building a maintainable deployment that survives future upgrades.
The Difference Between Overwriting and Overriding
Although the terms are often used interchangeably, they describe different approaches.
Overwriting typically means replacing the original rule definition itself, usually by editing the shipped XML rule files or redefining the same rule ID.
Overriding, on the other hand, means creating new rules that change detection behavior without altering the original files. This is the approach recommended by the Wazuh project because it preserves compatibility with future releases.
Whenever possible, administrators should think in terms of extending existing detection logic rather than replacing it completely.
Editing Built-in Rules
One way to overwrite a rule is to edit the XML files located within the default Wazuh ruleset.
While this appears to be the simplest solution, it has several drawbacks:
- Changes are overwritten during upgrades.
- Vendor improvements are lost.
- Troubleshooting becomes significantly harder.
- Configuration drift develops over time.
For these reasons, directly editing built-in rules should generally be avoided.
Creating Replacement Rules
A safer alternative is to create your own custom rule that references the original detection logic.
Instead of replacing the vendor rule, your custom rule can:
- Increase or decrease alert severity
- Add additional matching conditions
- Trigger Active Response
- Generate more specific alerts
- Correlate multiple detections
This approach keeps the original rule intact while allowing you to customize behavior.
Disabling Versus Replacing Behavior
Sometimes administrators simply want to stop a noisy alert rather than replace it entirely.
These are two different objectives:
- Disabling prevents the alert from being generated.
- Replacing changes how the detection behaves.
- Extending builds additional logic on top of an existing rule.
Choosing the correct strategy reduces unnecessary complexity and makes future maintenance much easier.
Why Editing Default Rules Is Discouraged
Although modifying the shipped XML files may seem convenient during initial testing, it almost always creates maintenance problems later.
The official Wazuh documentation recommends keeping vendor rule files unchanged and placing all customizations in local rule files instead.
Updates Overwrite Changes
Every Wazuh upgrade installs updated versions of the official ruleset.
Any manual edits made directly to those files are likely to disappear after the upgrade.
Even if backups exist, administrators must manually compare every modified file against the new release, which becomes increasingly difficult as deployments grow.
Difficult Troubleshooting
Months later, it is often impossible to remember which rules were modified manually.
This creates several problems:
- Unexpected alert behavior
- Difficult root-cause analysis
- Confusion during incident response
- Longer upgrade windows
Keeping customizations isolated makes troubleshooting far more straightforward.
Unsupported Configurations
Vendor support and community troubleshooting generally assume that the official rules remain unchanged.
If core rule files have been heavily modified, reproducing issues becomes much more difficult, and future documentation may no longer match your environment.
Recommended Approach
The safest long-term strategy is to leave the shipped rules untouched while placing all custom logic in separate files.
This keeps your deployment clean, organized, and much easier to upgrade.
Use local_rules.xml
For many environments, local_rules.xml is the simplest location for custom detections.
Keeping locally maintained rules separate from vendor content allows administrators to:
- Preserve changes during upgrades
- Simplify backups
- Quickly locate custom logic
- Reduce configuration conflicts
Create Custom Rule Files
As deployments become larger, many teams organize custom detections into multiple XML files.
Examples include:
linux_rules.xmlwindows_rules.xmlcloud_rules.xmlapplication_rules.xml
Separating rules by technology or business function improves maintainability and makes collaboration easier.
Override Behavior Instead of Modifying Core Files
Rather than redefining existing rule IDs, create new rules that reference or build upon existing detections.
This provides several important advantages:
- Better upgrade compatibility
- Easier troubleshooting
- Cleaner version control
- Reduced risk of rule ID conflicts
- Better collaboration across teams
This approach aligns with Wazuh’s recommended customization model and significantly lowers long-term maintenance costs.
Related Guide: How to Create Custom Detection Rules in Wazuh (With Examples)
Safe Methods for Customizing Existing Rules
Wazuh includes several mechanisms for modifying detection behavior without creating rule ID conflicts.
Instead of replacing vendor rules, administrators can extend, refine, suppress, or correlate existing detections using features built directly into the rules engine.
These methods are safer, easier to maintain, and much more resilient during upgrades.
Using <if_sid> to Extend Existing Rules
One of the most powerful customization techniques is the <if_sid> directive.
Rather than duplicating an existing rule, <if_sid> allows a new rule to execute only after another rule has already matched.
This enables layered detection while keeping the original rule untouched.
Triggering Additional Logic
Child rules created with <if_sid> can perform additional checks before generating alerts.
For example, a child rule might:
- Require a specific username
- Match a particular source IP
- Check a decoded JSON field
- Verify a command-line argument
- Detect repeated activity
This makes detections much more precise while minimizing false positives.
Practical Examples
A common scenario is extending an existing authentication rule.
For example:
- Base rule detects failed SSH authentication.
- Child rule checks whether failures exceed a threshold.
- Another child rule verifies that attempts originated externally.
- A final child rule raises the alert severity.
Instead of rewriting the original detection, each layer builds upon the previous one.
This layered design is easier to understand, maintain, and troubleshoot.
Using Rule Groups
Rule groups provide another effective way to organize custom detections.
Groups allow related rules to be categorized together, simplifying both management and alert filtering.
Organizing Custom Detections
Grouping rules by function improves consistency.
Examples include:
- Authentication
- Malware
- Cloud
- Web applications
- Compliance
- Active Response
- Threat intelligence
Well-organized rule groups make large rulesets much easier to navigate.
Maintaining Readability
As deployments grow to hundreds or even thousands of custom rules, organization becomes increasingly important.
Consistent grouping helps:
- Reduce duplicate logic
- Improve documentation
- Speed troubleshooting
- Simplify onboarding for new administrators
A structured ruleset is considerably easier to maintain over time.
Changing Alert Levels Without Reusing IDs
A common requirement is adjusting the severity of an existing detection.
Many administrators mistakenly reuse the original rule ID when they only want to change the alert level.
This is unnecessary.
Creating Child Rules
Instead of modifying the original rule, create a child rule that references it.
The child rule can assign a different severity while leaving the original detection intact.
Benefits include:
- No duplicate IDs
- Cleaner rule hierarchy
- Easier upgrades
- Better visibility into customized logic
Severity Adjustments
Child rules can increase or decrease alert levels based on additional context.
For example:
- Failed login from an internal host → Lower severity
- Failed login from the Internet → Higher severity
- Administrative account involved → Critical severity
This allows much more intelligent alerting without altering vendor content.
Suppressing Existing Alerts
Not every environment requires every default detection.
Some alerts may generate excessive noise and need to be suppressed under controlled conditions.
Ignore Rules
Instead of deleting or editing vendor rules, create custom ignore rules that prevent unnecessary alerts.
Common use cases include:
- Scheduled maintenance
- Known administrative activity
- Approved automation
- Monitoring systems
- Internal scanners
Properly designed ignore rules reduce alert fatigue while preserving the underlying detection logic.
Conditional Matching
Suppression should always be as specific as possible.
Rather than ignoring every occurrence of an event, administrators should apply conditions such as:
- Source IP
- Hostname
- Username
- Process name
- Time window
- Event type
Granular suppression minimizes the risk of hiding legitimate attacks.
Related Guide: How to Reduce False Positives in Wazuh
Creating New Rules That Reference Existing Ones
The most maintainable customization strategy is often creating entirely new rules that reference existing detections.
Instead of replacing vendor content, new rules simply build upon established logic.
Building Layered Detections
Layered detection improves accuracy by combining multiple indicators.
For example:
- Authentication failure detected.
- Multiple failures occur within a short period.
- Source IP is external.
- User belongs to an administrative group.
- Active Response is triggered.
Each rule performs a single responsibility, making the detection chain easier to maintain and expand.
Maintaining Upgrade Compatibility
Because the original Wazuh rules remain untouched, future upgrades rarely require modifications to your custom logic.
This approach offers several long-term benefits:
- Lower maintenance effort
- Cleaner version control
- Easier troubleshooting
- Improved documentation
- Reduced rule ID conflicts
For most production environments, referencing existing rules rather than replacing them is considered the safest customization strategy.
Choosing Safe Rule ID Ranges
Selecting an organized rule ID strategy is one of the simplest ways to prevent conflicts before they occur.
While Wazuh only requires rule IDs to be unique, a structured numbering scheme makes custom rules easier to maintain, audit, and expand over time.
Organizations that establish rule ID standards early rarely encounter duplicate ID problems as their rulesets grow.
Recommended Custom ID Ranges
Wazuh recommends assigning locally developed rules from ranges intended for custom content rather than using IDs that may conflict with built-in rules.
Keeping all custom rules within a dedicated numbering space offers several advantages:
- Prevents collisions with vendor rules
- Simplifies code reviews
- Makes custom rules immediately recognizable
- Reduces upgrade risks
- Improves documentation
Always consult the current Wazuh documentation before selecting a numbering scheme, as recommended ranges may evolve between releases.
Avoiding Reserved IDs
Official Wazuh releases continue to introduce new rules covering additional operating systems, cloud services, applications, and threat intelligence sources.
Using IDs from reserved or vendor-managed ranges increases the likelihood of future conflicts after upgrades.
To minimize this risk:
- Never assign IDs that already exist in the default ruleset.
- Avoid copying vendor IDs into custom files.
- Verify imported rule packs before deployment.
- Review release notes after upgrading.
A few minutes spent validating IDs can prevent hours of troubleshooting later.
Organizing IDs by Function
As custom rule libraries expand, assigning IDs sequentially often becomes difficult to manage.
Instead, many organizations reserve blocks of IDs for different technologies or use cases.
For example:
| Rule Category | Example ID Range |
|---|---|
| Linux Monitoring | 100000–100999 |
| Windows Events | 101000–101999 |
| Authentication | 102000–102999 |
| Cloud Services | 103000–103999 |
| Threat Intelligence | 104000–104999 |
The exact numbering is less important than maintaining consistency across the environment.
A logical allocation strategy makes it much easier to identify rule ownership and avoid accidental duplication.
Maintaining an Internal Rule ID Inventory
One of the best practices for large Wazuh deployments is maintaining a central inventory of assigned rule IDs.
This can be as simple as a spreadsheet, version-controlled document, or internal wiki containing:
- Rule ID
- Purpose
- Owner
- File location
- Date created
- Related parent rule
- Last modified date
Maintaining an inventory provides several benefits:
- Prevents duplicate assignments
- Simplifies peer reviews
- Accelerates troubleshooting
- Supports compliance documentation
- Makes future expansion much easier
For teams managing hundreds of custom detections, a documented rule ID registry often becomes one of the most valuable maintenance tools available.
Be First to Comment