Wazuh customization with custom rules and decoders

The fastest way to decide where a customization belongs is to know which stage of the pipeline owns each job. Decoders and rules both live on the Wazuh server, but they do different work. A decoder reads a raw event and extracts named fields from it, such as a source address, a user name or an action. A rule then tests those fields and decides whether the event matters and how severe it is by assigning an alert level. If a field is missing from the alert, the problem is usually in the decoder. If the field is present but the alert is noisy, missing or mis-levelled, the problem is usually in the rule. Keeping that split in mind prevents engineers from tuning rule levels to hide a parsing failure.

Data moves through four components. Wazuh agents on endpoints collect logs, file activity, inventory and other events and send them to the Wazuh server. The server runs its decoders and rules against each event and produces alerts. Those alerts are stored in the Wazuh indexer, which is a full-text search and analytics engine, and the Wazuh dashboard reads from the indexer to present them. The server is the only stage where your custom decoders and rules take effect, so a change made anywhere else will not alter how events are classified. Before you change anything, confirm with your own test events which stage produces the symptom you are seeing.

Custom decoder and rule files are not edited directly on each server by default. The Wazuh server manages agent configuration remotely, and the same central mechanism is the practical route for delivering shared configuration to agents. Your team should therefore treat custom files as managed artifacts: keep them in version control, deliver them through one controlled path, and validate them before they reach production. Confirm in the Wazuh documentation for your exact 4.14 patch level how the server checks rule and decoder syntax, how it reports errors on restart, and whether a failed file stops the service or is skipped, because that behavior determines how much damage a bad change can do.

A practical check is to replay representative events through a test server before each change. Collect a sample of raw logs from each source you customize, including normal and unusual cases, and record which fields and alert levels they produce today. After a change, compare the new output against that baseline. Differences should be intentional. This also gives you evidence for later upgrades, because the same replay set shows whether a new 4.14 patch changed how your custom rules behave. Plan for this testing from the start, since rules that work on one log format often fail silently when a vendor changes its output.

Tuning in Wazuh should make the alert stream easier to act on without removing the ability to see what matters. The main levers are the rule level (the severity Wazuh assigns when a rule matches), suppression rules that discard known benign events, and grouping that keeps related detections together on the dashboard. Each lever changes what analysts see, so each change needs a stated reason, a narrow scope and a way to be reversed. Start by identifying the handful of rules that produce most of the volume, then decide for each whether the problem is the severity, the trigger conditions or the way the output is presented.

Adjusting a default rule level is usually safer than suppressing the rule. Wazuh ships its rules in its own rule files, and local changes belong in the custom rules location so that they survive package updates. Where a rule is noisy in one environment but meaningful in another, a child rule that inherits from the parent and sets a different level for a specific agent group, host pattern or decoded field is easier to explain than an edit to the parent. Confirm the exact rule ID ranges, override mechanics and file locations for your installed 4.14 release in the official documentation before you build the change, because the precedence between parent and child rules determines which level actually fires.

Suppression is where detections are most often lost. A rule that discards events should match only the exact benign pattern, such as one service account performing one scheduled task from one known host, and should never match on a broad keyword or an entire rule group. Treat every suppression as a claim that a specific event is never worth an analyst's time, and test that claim against a sample of the events it would drop. Grouping related rules works differently: it changes how alerts are labelled and clustered so that a burst of related events reads as one story. Grouping does not remove events, so it is the safer tool when the goal is readability.

Measure every change before and after it goes live. For each rule you touch, record its alert count over a comparable window before the change, the count after it, the number of events suppressed or re-leveled, and a short sample of what was removed. A large drop with a clean sample is evidence that the change worked. A large drop with unexplained content is a warning that the rule is too broad. Keep the measurements alongside the change record. Ask your internal team or any implementation partner to define the observation window and the sampling method in writing before tuning begins, so the results can be compared later.

Keep an approval record for each change. The record should name the rule ID, the original and new level or suppression condition, the business or threat reason, the person who approved it, the date, and the rollback step. Analysts need this to understand why an alert that used to be critical is now informational, and auditors need it to confirm that detection coverage was reviewed rather than quietly reduced. Store the records in the same version control as your custom rule files so that every change is traceable to a commit. Review suppressions on a fixed schedule, because a benign pattern that was valid last year may no longer be benign after an infrastructure change.

The most useful thing you can prepare before customization starts is administrative access to a test Wazuh environment that mirrors production. Custom decoders and rules are written as XML files on the Wazuh server, and they only become useful once they are tested against real agent traffic in the Wazuh dashboard and in the server's log test tool. Without admin access to both the server and the dashboard, every test waits on someone else's queue, and the first rounds of work become guesswork. Confirm that the account can edit the local rule and decoder files, restart the relevant services, and view alerts across the agent groups in scope. Sample logs are the single largest driver of rework. Ask for representative log lines from each source, taken from the same software version and log configuration your production agents send. Each sample should be labeled with what it means: normal activity, a known failure, or a specific attack pattern you want detected. Unlabeled samples force the team to guess field boundaries and severity, and guessed decoders often match the wrong events. Include enough volume to show variation, such as different user names, status codes and message formats, so that a decoder is not written around a single lucky line. You also need a named owner for alert decisions. This person decides which events should raise an alert, at what level, and which noisy patterns should be suppressed or grouped. Without one, rule changes stall while engineers wait for a decision, or they ship with thresholds nobody on your side agreed to. The owner should be reachable during testing and should sign off on the final alert levels before they reach the production dashboard. Next, provide the compliance or internal control list the alerts should map to. This is usually a set of control IDs and titles from frameworks such as PCI DSS, HIPAA or NIST 800-53, or from your own internal control library. Mapping targets determine which rule groups and dashboard views are needed and what evidence each alert must carry. A list supplied at the start prevents a later round of relabeling rules to match an auditor's wording. Finally, agree on change approval rules and a test or staging environment before any production change is made. Confirm who approves a rule change, how emergency fixes are handled, and how the approved change is recorded in your change system. Then confirm that the staging environment receives the same agent groups and configuration pattern as production, so tests reflect real behavior. Clear approval rules and a staging path shorten the schedule because each change is reviewed once, and they reduce rework because tested rules move to production without being reopened.