Security platforms are only as effective as their ability to understand incoming log data. Organizations collect millions of events every day from operating systems, firewalls, cloud services, applications, and security tools, but these logs arrive in dozens of different formats. Before Wazuh can detect malicious behavior, correlate events, or trigger alerts, it must first interpret the raw log entries. This is where Wazuh decoders become essential.

Decoders transform unstructured log messages into structured fields that the Wazuh rules engine can analyze.

Without accurate decoding, important information such as usernames, IP addresses, event IDs, process names, or file paths may never reach detection rules, resulting in missed alerts or inaccurate threat detection.

Whether you’re integrating a new log source, troubleshooting custom rules, or building your own detection content, understanding how decoders work is one of the most valuable Wazuh skills you can develop.

In this guide, you’ll learn how the Wazuh Decoder engine works, how decoding differs from rule matching, how parent and child decoders process logs, and how to build reliable custom decoders that accurately parse virtually any log format.

Related Guides:

• How to Create Custom Detection Rules in Wazuh (With Examples)
• How to Test Wazuh Rules

What Is a Wazuh Decoder?

A Wazuh decoder is a parsing component that analyzes incoming log messages and extracts meaningful information into structured fields that the Wazuh rules engine can evaluate.

Think of a decoder as a translator.

Applications produce logs in their own unique formats, but Wazuh needs standardized field names before it can determine whether an event represents suspicious or malicious activity.

The decoder performs this translation automatically.

For example, consider the following authentication log:

Jul 18 09:42:11 webserver sshd[1452]: Failed password for invalid user admin from 192.168.1.55 port 52418 ssh2

A decoder may extract fields such as:

• Timestamp
• Hostname
• Program name (sshd)
• Username (admin)
• Source IP (192.168.1.55)
• Source port (52418)
• Authentication status (Failed)

Once these fields exist, Wazuh rules can determine whether this event indicates brute-force activity, credential abuse, or other security threats.

How Decoders Fit into the Wazuh Log Analysis Pipeline

Every event entering Wazuh follows a structured processing pipeline:

1. Log collection
2. Pre-decoding
3. Decoder matching
4. Field extraction
5. Rule evaluation
6. Alert generation

The decoder sits directly between raw log collection and rule evaluation.

Its responsibility is not to decide whether an event is malicious, it simply identifies and organizes the data so the rules engine can make that decision.

Without successful decoding, many detection rules will never execute because the required fields don’t exist.

Decoding vs. Rule Matching

Many beginners confuse decoders with detection rules, but they perform completely different tasks.

For example:

A decoder extracts:

srcip = 10.10.1.25
username = admin
action = failed

A rule then evaluates:

IF action == failed
AND username == admin
THEN generate alert

This separation keeps parsing independent from threat detection, making Wazuh easier to maintain and extend.

Related Guide: How to Create Custom Detection Rules in Wazuh (With Examples)

Why Accurate Decoding Improves Threat Detection

The quality of your threat detection depends heavily on the quality of your decoding.

Poorly designed decoders may:

• Miss important fields
• Capture incorrect values
• Fail when log formats change
• Produce false positives
• Cause false negatives
• Break custom detection rules

Well-designed decoders, on the other hand, provide consistent structured data that enables reliable alerting, correlation, dashboards, compliance reporting, and threat hunting.

The official Wazuh documentation recommends creating custom decoders whenever logs don’t match existing decoder definitions, ensuring that custom applications and proprietary systems can still participate fully in the detection pipeline.

Industry guidance from organizations such as MITRE ATT&CK also emphasizes the importance of collecting normalized security telemetry, since high-quality structured event data directly improves detection engineering and behavioral analytics.

How Wazuh Decoding Works

Every log received by Wazuh passes through several processing stages before an alert is generated.

Understanding this pipeline makes it much easier to troubleshoot parsing issues and build reliable custom decoders.

Log Collection

The process begins when a log reaches the Wazuh Manager.

Logs may originate from:

• Linux systems
• Windows Event Logs
• Firewalls
• IDS/IPS platforms
• Cloud services
• Applications
• Containers
• Network devices
• Syslog servers

Collection modules normalize how logs enter the analysis engine, regardless of their original source.

Related Guide: How to Configure Wazuh as a Centralized Syslog Server

Pre-Decoding Phase

Before custom decoders even begin, Wazuh performs pre-decoding.

This lightweight parser extracts generic information commonly found in syslog-formatted messages, including:

• Timestamp
• Hostname
• Program name
• Process ID

Because these fields are standardized across many Unix-style logs, extracting them first improves efficiency and reduces unnecessary regex processing later.

Decoder Matching

After pre-decoding, Wazuh searches through its decoder library.

Each decoder contains matching conditions such as:

• Program name
• Prematch expressions
• Parent decoder references
• Regular expressions

The engine attempts to identify which decoder best matches the incoming log.

Rather than testing every decoder equally, Wazuh narrows the search using parent relationships and prematch filters, significantly improving performance.

Field Extraction

Once a decoder matches the log, it extracts relevant values into standardized fields.

Common extracted fields include:

• Source IP
• Destination IP
• Username
• Process name
• File path
• Event ID
• Port numbers
• URLs
• Hashes
• Command-line arguments

These become searchable structured attributes used throughout the Wazuh platform.

Rule Evaluation

Only after decoding completes does the Wazuh rules engine begin evaluating detection logic.

Rules reference extracted fields rather than parsing raw text.

For example:

if srcip == 192.168.1.55
and username == admin
and action == failed

Because rules work with structured data, they are simpler, faster, and easier to maintain than attempting to parse raw log text repeatedly.

Related Guide: How to Test Wazuh Rules

Alert Generation

If one or more rules match the decoded event, Wazuh generates an alert.

The alert contains:

• Rule ID
• Severity level
• Description
• MITRE ATT&CK mappings (where applicable)
• Decoded fields
• Original log
• Agent information
• Timestamp

These alerts can then be viewed in the dashboard, forwarded to external SIEMs, or trigger automated responses.

Related Guide: How to Configure Wazuh Active Response

Wazuh Decoder Architecture

Understanding the internal architecture of Wazuh decoders helps explain why complex log formats can be parsed efficiently without relying on a single massive regular expression.

Pre-decoder

The pre-decoder is the first parser executed after log collection.

Its purpose is to extract common metadata before specialized decoders begin processing.

Typical outputs include:

• Timestamp
• Hostname
• Program name
• Process ID

These values become immediately available to downstream decoders.

Timestamp Extraction

Many log formats begin with a timestamp.

For example:

Jul 18 15:30:42

The pre-decoder isolates this value so later decoder stages don’t need to repeatedly parse date information.

Hostname Detection

The hostname identifies the system that generated the event.

Example:

webserver01

This field enables filtering, reporting, and rule conditions based on the originating machine.

Program Name Identification

For syslog-based events, Wazuh extracts the application responsible for generating the log.

Examples include:

• sshd
• nginx
• sudo
• kernel
• postfix
• apache2

Program names are frequently used as the first filtering step when selecting parent decoders.

Decoder Engine

The decoder engine evaluates decoder definitions stored within the Wazuh ruleset.

Each decoder contains metadata describing:

• Matching conditions
• Parent relationships
• Prematch expressions
• Regular expressions
• Extracted fields

The engine processes these definitions in a structured hierarchy rather than evaluating every decoder independently.

Parent Decoders

Parent decoders provide broad classification.

For example, a parent decoder may identify:

• SSH logs
• Apache logs
• Windows Security events
• Syslog messages

Once the parent matches, Wazuh evaluates only the relevant child decoders instead of the entire decoder library.

This hierarchical approach improves both scalability and processing speed.

Child Decoders

Child decoders specialize in parsing specific event types belonging to a parent decoder.

For example, an SSH parent decoder may contain child decoders for:

• Successful login
• Failed login
• Invalid user
• Public key authentication
• Session opened
• Session closed

Each child extracts fields unique to that event.

Regex Matching

Most Wazuh decoders rely on regular expressions (regex) to capture values from log messages.

A regex can identify:

• IPv4 addresses
• Usernames
• File paths
• Process IDs
• URLs
• Event codes

Efficient regex design is important because every incoming log may be evaluated against multiple decoder patterns.

Overly broad or complex expressions can negatively affect parsing performance, especially in high-volume environments.

Prematch Filtering

A prematch acts as a quick filter before executing the full regular expression.

For example:

prematch: Failed password

Only logs containing that phrase proceed to full regex evaluation.

This significantly reduces CPU usage by avoiding unnecessary regex processing across unrelated log entries.

The Wazuh documentation recommends using prematch conditions whenever possible because they improve decoder efficiency and scalability.

Extracted Fields

Once decoding succeeds, Wazuh stores structured values that can be referenced by rules, dashboards, searches, and integrations.

Common extracted fields include:

Source IP

The originating IP address responsible for the activity.

Example:

srcip = 192.168.1.55

Destination IP

The target system receiving the connection or request.

dstip = 10.0.0.15

Username

The account involved in the event.

user = administrator

Process Name

The executable or service that generated the log.

Examples include:

• sshd
• powershell.exe
• winlogon.exe
• nginx

Event ID

Windows events commonly include an Event ID that identifies the type of activity.

Examples:

• 4624 (Successful Logon)
• 4625 (Failed Logon)
• 4688 (Process Creation)

Custom Fields

Custom decoders are not limited to predefined field names.

Organizations frequently extract additional values such as:

• Session IDs
• Tenant IDs
• API keys (masked where appropriate)
• Device IDs
• Cloud account IDs
• Container names
• Kubernetes namespaces
• Application-specific identifiers

These custom fields allow organizations to build highly tailored detection rules for proprietary applications and unique log formats.

Related Guides:

• How to Create Custom Detection Rules in Wazuh (With Examples)
• Custom Decoder Isn’t Matching: Wazuh Logtest Deep Dive

Types of Wazuh Decoders

Wazuh includes several types of decoders, each designed to solve a different parsing challenge.

Some are built into the default ruleset and cover common operating systems and applications, while others can be customized to support proprietary software, cloud services, or internally developed applications.

Choosing the right decoder type improves maintainability, reduces processing overhead, and makes future troubleshooting much easier.

Built-in Decoders

Built-in decoders are included with every Wazuh installation and support hundreds of common log sources.

Examples include decoders for:

• Linux system logs
• Windows Event Logs
• SSH
• Apache
• Nginx
• Syslog
• Sudo
• MySQL
• Postfix
• OpenSSH
• Docker
• Kubernetes
• Cloud services

These decoders are actively maintained by the Wazuh project and are updated alongside new Wazuh releases.

Rather than creating custom decoders from scratch, it’s always worth checking whether an existing decoder already supports your log format.

Custom Decoders

Custom decoders allow administrators to parse logs that are not supported by the default ruleset.

Common use cases include:

• Proprietary business applications
• Internal APIs
• Custom authentication systems
• Network appliances
• Legacy software
• Third-party SaaS platforms
• Specialized security products

Custom decoders are typically stored in:

/var/ossec/etc/decoders/local_decoder.xml

or as individual XML files inside:

/var/ossec/etc/decoders/

Using separate decoder files for different applications makes upgrades and maintenance much easier than modifying the default ruleset.

Parent and Child Decoders

Large applications often generate many different log formats.

Instead of creating dozens of unrelated decoders, Wazuh allows decoders to be organized into parent-child hierarchies.

A parent decoder performs broad identification.

Example:

<decoder name="apache">
    <program_name>apache2</program_name>
</decoder>

Child decoders then extract fields for specific event types.

<decoder name="apache-access">
    <parent>apache</parent>
    ...
</decoder>

Benefits include:

• Less duplicated configuration
• Faster decoder evaluation
• Easier maintenance
• Better organization
• Improved scalability

This hierarchical approach is especially useful when applications generate access logs, error logs, audit logs, and authentication logs with different structures.

Dynamic Field Decoders

Not every log source follows a fixed structure.

Many modern applications produce JSON logs or semi-structured key-value pairs where fields can change between events.

Dynamic field decoders allow Wazuh to extract these values without requiring a separate regex for every possible variation.

Typical examples include:

• Cloud platform logs
• Container logs
• Kubernetes events
• API responses
• Security products exporting JSON

Instead of extracting only predefined fields like srcip or user, dynamic decoding can capture arbitrary key-value pairs that rules reference later.

This flexibility is particularly valuable in cloud-native environments where log schemas evolve frequently.

Plugin Decoders

Plugin decoders extend Wazuh with specialized parsing engines beyond standard regular expressions.

Instead of relying solely on XML-based regex matching, plugin decoders use dedicated parsing logic for complex formats.

Common plugin decoders include support for:

• JSON
• PF (Packet Filter) firewall logs
• Symantec logs
• SonicWall logs
• Other specialized formats

Plugin decoders are generally preferred when log structures are too complex or dynamic for traditional regex-based parsing.

Using plugin decoders also reduces the amount of custom XML that administrators need to maintain.

Decoder XML Structure Explained

Every Wazuh decoder is defined using XML. While decoder files can become complex, most rely on a small set of core elements.

Understanding what each element does makes creating and troubleshooting decoders much easier.

Decoder Name

The name attribute uniquely identifies the decoder.

<decoder name="apache-access">
</decoder>

Purpose

• Identifies the decoder
• Used by child decoders
• Appears in debugging output
• Helps organize decoder libraries

Use descriptive names that clearly identify the application and log type.

Parent

The <parent> element links a decoder to another decoder.

<decoder name="apache-access">
    <parent>apache</parent>
</decoder>

Purpose

• Creates decoder hierarchies
• Reduces duplicate matching logic
• Improves processing performance
• Keeps decoder files organized

Only logs matched by the parent decoder are evaluated against its children.

Prematch

A prematch performs a quick string comparison before executing the full regular expression.

<decoder name="ssh-failed">
    <prematch>Failed password</prematch>
</decoder>

Purpose

• Filters unrelated logs
• Reduces regex execution
• Improves performance
• Simplifies decoder logic

Because string matching is much faster than regex evaluation, prematch expressions are considered a best practice for high-volume environments.

Regex

The <regex> element extracts data from the log.

Example:

<decoder name="ssh-failed">
    <regex>Failed password for (\S+) from (\d+\.\d+\.\d+\.\d+)</regex>
</decoder>

Purpose

• Matches log content
• Captures values
• Identifies event structure

Each pair of parentheses creates a captured value that can later be mapped to a field.

Order

The <order> element assigns captured groups to field names.

<decoder name="ssh-failed">
    <regex>Failed password for (\S+) from (\d+\.\d+\.\d+\.\d+)</regex>
    <order>user,srcip</order>
</decoder>

Captured groups are mapped as follows:

Without an order element, captured values cannot be referenced by detection rules.

Program Name

The <program_name> element limits decoder execution to logs generated by a specific application.

<decoder name="sshd">
    <program_name>sshd</program_name>
</decoder>

Purpose

• Narrows decoder scope
• Improves performance
• Prevents accidental matches
• Reduces false positives

Program name filtering is commonly used in parent decoders.

Offset

The offset attribute tells Wazuh where regex matching should begin.

Example:

<decoder name="apache-access">
    <regex offset="after_prematch">client=(\S+)</regex>
    <order>srcip</order>
</decoder>

Common offsets include:

• after_parent
• after_prematch

Using offsets prevents the regex engine from repeatedly scanning parts of the log that have already been processed.

Plugin Decoder

Plugin decoders invoke specialized parsing engines.

Example:

<decoder name="json-log">
    <plugin_decoder>JSON_Decoder</plugin_decoder>
</decoder>

Instead of parsing with regex, the JSON decoder automatically extracts keys and values from valid JSON documents.

This greatly simplifies decoder configuration for structured log formats.

Options

Some decoders include optional XML elements or attributes that control matching behavior or parsing logic.

Example:

<decoder name="custom-app">
    <prematch>AUTH</prematch>
    <regex>user=(\S+)</regex>
    <order>user</order>
</decoder>

Options vary depending on the decoder type, but they typically improve matching precision, parsing efficiency, or compatibility with specific log formats.

Consult the official decoder XML reference whenever you’re using less common decoder attributes.

How to Create a Custom Wazuh Decoder

When Wazuh encounters a log format that isn’t supported by its built-in decoders, you can create a custom decoder to extract the fields required by your detection rules.

A well-designed decoder should be simple, readable, and resilient to small formatting changes.

Identify the Log Format

Begin by collecting several real log samples.

For example:

AUTH: user=jdoe action=login src=192.168.10.15 status=success

Look for:

• Constant text
• Variable fields
• Delimiters
• Key-value pairs
• Optional fields
• Repeating patterns

Using multiple log samples helps ensure your decoder handles slight variations.

Create a Local Decoder File

Never modify the default decoder files included with Wazuh.

Instead, create a local decoder file:

/var/ossec/etc/decoders/local_decoder.xml

or create an application-specific file such as:

/var/ossec/etc/decoders/custom_app.xml

Keeping custom decoders separate prevents them from being overwritten during upgrades.

Define Prematch Conditions

Identify text that appears in every log.

Example:

<prematch>AUTH:</prematch>

This ensures that only authentication logs are evaluated by the regex engine.

Build the Regular Expression

Create a regex that captures each variable value.

Example:

<regex>user=(\S+) action=(\S+) src=(\S+) status=(\S+)</regex>

The four capture groups represent:

1. Username
2. Action
3. Source IP
4. Status

Map Captured Fields

Assign each captured value to a Wazuh field using the order element.

<order>user,action,srcip,status</order>

These fields can now be referenced by detection rules.

Related Guide: How to Create Custom Detection Rules in Wazuh (With Examples)

Save the Decoder

Save the XML file inside the Wazuh decoder directory.

Verify the XML is well-formed before reloading the manager.

Common mistakes include:

• Missing closing tags
• Incorrect nesting
• Invalid regex
• Typographical errors
• Incorrect field ordering

Reload Wazuh Manager

After saving the decoder, reload or restart the Wazuh Manager so it loads the new configuration.

For systems using systemd:

sudo systemctl restart wazuh-manager

In production environments, it’s good practice to validate the decoder in a test environment before restarting a heavily utilized manager.

Validate the Decoder

The easiest way to test a decoder is with wazuh-logtest.

Paste sample logs into the tool and verify:

• The correct decoder matches
• Expected fields are extracted
• Parent decoder selection is correct
• Detection rules trigger successfully

Using realistic log samples during testing reduces the risk of decoding failures after deployment.

Related Guide:

• Custom Decoder Isn’t Matching: Wazuh Logtest Deep Dive
• How to Test Wazuh Rules

Complete Custom Decoder Example

The following decoder parses a simple authentication log and extracts the username, action, source IP, and login status.

<decoder name="custom-auth">
    <prematch>AUTH:</prematch>

    <regex>
        user=(\S+)\s+
        action=(\S+)\s+
        src=(\S+)\s+
        status=(\S+)
    </regex>

    <order>
        user,
        action,
        srcip,
        status
    </order>
</decoder>

Given this log:

AUTH: user=jdoe action=login src=192.168.10.15 status=success

Wazuh extracts:

Once these fields are available, you can build custom rules that detect failed logins, privileged account usage, suspicious source IPs, or other organization-specific security events without parsing the raw log again.

Testing Wazuh Decoders

Testing is one of the most important steps when developing or modifying a Wazuh decoder.

Even a small mistake in a regular expression or field mapping can prevent alerts from firing or cause incorrect data to be extracted.

Rather than deploying a decoder directly into production, you should validate it using wazuh-logtest, which simulates the log analysis pipeline without affecting live event processing.

Testing should verify not only that the decoder matches the log, but also that the expected fields are extracted correctly and that downstream rules behave as intended.

Using wazuh-logtest

The primary tool for testing decoders is wazuh-logtest.

Start the interactive utility:

sudo /var/ossec/bin/wazuh-logtest

You’ll see a prompt similar to:

Starting wazuh-logtest...

Type one log per line.

Paste a sample log:

AUTH: user=jdoe action=login src=192.168.10.15 status=success

The utility processes the event through every stage of the analysis pipeline and displays the results.

Related Guide: Custom Decoder Isn’t Matching: Wazuh Logtest Deep Dive

Verifying Extracted Fields

One of the most important sections of the output is Phase 2, where Wazuh displays the decoder that matched along with the extracted fields.

Example output:

**Phase 2: Completed decoding.

decoder: 'custom-auth'

user: 'jdoe'
action: 'login'
srcip: '192.168.10.15'
status: 'success'

Verify that:

• The expected decoder matched.
• Every required field appears.
• Field values are accurate.
• No unexpected values were captured.
• Data wasn’t truncated.

If a field is missing, review the decoder’s regex and order elements.

Testing Multiple Log Samples

Never validate a decoder using only one example log.

Instead, collect samples representing different scenarios, such as:

• Successful authentication
• Failed authentication
• Invalid usernames
• Missing optional fields
• IPv6 addresses
• Different timestamp formats
• Slight formatting differences between software versions

Example:

AUTH: user=jdoe action=login src=192.168.10.15 status=success

AUTH: user=admin action=login src=203.0.113.25 status=failed

AUTH: user=backup action=logout src=10.0.0.8 status=success

Testing multiple variations helps ensure your decoder remains reliable when real-world log formats evolve.

Debugging Failed Matches

If the decoder fails to match, work through the following checklist:

1. Verify the log reaches the Wazuh Manager.
2. Confirm the correct decoder file is loaded.
3. Check XML syntax.
4. Verify the prematch condition.
5. Test the regex separately.
6. Confirm the parent decoder matches first.
7. Restart or reload the manager after making changes.

Useful commands include:

Check decoder configuration:

sudo /var/ossec/bin/wazuh-logtest

Monitor the manager log while testing:

sudo tail -f /var/ossec/logs/ossec.log

Validate XML formatting:

xmllint --noout /var/ossec/etc/decoders/local_decoder.xml

If the decoder still doesn’t match, simplify the regex and gradually add complexity until the failure point is identified.

Related Guide: How to Fix ossec.conf Syntax Errors in Wazuh Agents

Comparing Decoder Output

When modifying an existing decoder, compare the output before and after your changes.

Ask yourself:

• Did additional fields appear?
• Did any fields disappear?
• Did field names change?
• Did capture groups shift?
• Did parent decoder selection change?
• Are rules still firing correctly?

For example:

Adding useful fields without breaking existing ones helps preserve compatibility with existing rules and dashboards.

After validating the decoder, confirm that the expected detection rules also trigger correctly using wazuh-logtest.

Related Guide: How to Test Wazuh Rules

Common Decoder Attributes

Wazuh decoders are built from a collection of XML elements and attributes that control how logs are matched and parsed.

While the decoder syntax supports many options, a handful of attributes are used in most decoder definitions.

name

The name attribute uniquely identifies a decoder.

Example:

<decoder name="apache-access">

The name should:

• Be unique
• Clearly identify the log source
• Be descriptive enough for troubleshooting
• Be reused by child decoders when appropriate

parent

The <parent> element creates hierarchical decoder relationships.

Example:

<parent>apache</parent>

Benefits include:

• Eliminates duplicated matching logic
• Improves performance
• Organizes related decoders
• Simplifies maintenance

Child decoders are evaluated only after the parent decoder successfully matches.

prematch

A prematch performs a fast string comparison before running the regular expression.

Example:

<prematch>Failed password</prematch>

Common uses include:

• Matching application names
• Authentication failures
• Log prefixes
• Keywords
• Event categories

Using prematch expressions reduces unnecessary regex execution and improves overall decoding performance.

regex

The <regex> element defines the regular expression used to capture values.

Example:

<regex>user=(\S+) src=(\S+)</regex>

Each capture group becomes a field listed in the <order> element.

Good regex patterns should:

• Match only the required data.
• Avoid excessive backtracking.
• Be resilient to minor formatting changes.
• Remain readable for future maintenance.

order

The <order> element maps regex capture groups to Wazuh field names.

Example:

<order>user,srcip</order>

Given:

user=jdoe src=192.168.10.15

The decoder extracts:

The order of field names must exactly match the order of the regex capture groups.

program_name

The <program_name> element limits decoder execution to logs generated by a specific application.

Example:

<program_name>sshd</program_name>

Typical program names include:

• sshd
• nginx
• sudo
• apache2
• postfix
• kernel

Using this element prevents unrelated logs from being evaluated by the decoder.

offset

The offset attribute specifies where regex matching should begin.

Example:

<regex offset="after_prematch">

Common values include:

• after_parent
• after_prematch

Offsets improve performance by skipping portions of the log that have already been processed.

plugin_decoder

The <plugin_decoder> element delegates parsing to a specialized decoder plugin.

Example:

<plugin_decoder>JSON_Decoder</plugin_decoder>

Plugin decoders are commonly used for:

• JSON logs
• Firewall logs
• Vendor-specific formats
• Structured application logs

They reduce the need for complex regular expressions while providing reliable parsing for structured data.

use_own_name

The <use_own_name> element instructs a child decoder to use its own name instead of inheriting the parent decoder’s name.

Example:

<use_own_name>true</use_own_name>

This is useful when:

• Multiple child decoders represent distinct event types.
• Debugging decoder matches.
• Reporting requires more granular decoder names.
• Large decoder hierarchies need clearer identification.

type

The <type> element specifies the expected log format.

Example:

<type>syslog</type>

Depending on the decoder, the type may indicate formats such as:

• syslog
• json
• windows
• firewall
• application-specific logs

Using the correct type helps Wazuh apply the appropriate parsing behavior.

Advanced Decoder Techniques

As your Wazuh deployment grows, you’ll encounter increasingly diverse log formats.

Advanced decoder techniques allow you to parse these logs efficiently while keeping your decoder library organized and maintainable.

Multiple Regular Expressions

Some log formats cannot be parsed with a single regular expression.

Instead of creating one extremely complex regex, split the parsing logic into multiple stages using parent and child decoders or multiple decoder definitions.

Benefits include:

• Better readability
• Easier troubleshooting
• Improved maintainability
• Reduced regex complexity

Smaller expressions are also less prone to performance issues caused by excessive backtracking.

Nested Decoders

Nested decoders build on earlier parsing results.

For example:

Parent Decoder
      │
      ▼
Authentication Logs
      │
      ▼
Failed Login Decoder
      │
      ▼
Privileged User Decoder

Each level performs progressively more specific matching, reducing duplicate logic while improving organization.

Reusing Parent Decoders

A single parent decoder can support dozens of specialized child decoders.

Example hierarchy:

apache
 ├── access
 ├── error
 ├── ssl
 ├── proxy
 └── authentication

This approach keeps related parsing logic together and avoids repeatedly matching the same application metadata.

Parsing JSON Logs

Many modern applications produce structured JSON logs rather than plain text.

Instead of creating lengthy regular expressions, use the JSON plugin decoder.

Example log:

{
  "user": "alice",
  "action": "login",
  "srcip": "192.168.10.20",
  "status": "success"
}

Using JSON_Decoder automatically extracts keys and values into structured fields, simplifying decoder maintenance and improving reliability.

This approach is particularly useful for cloud platforms, containerized applications, and REST APIs.

Parsing Syslog Messages

Syslog remains one of the most widely used logging standards.

Typical syslog messages already contain metadata such as:

• Timestamp
• Hostname
• Program name
• Process ID

Because the pre-decoder extracts this information automatically, custom decoders can focus solely on parsing the application-specific portion of the log, resulting in simpler and faster decoder definitions.

Related Guide: How to Configure Wazuh as a Centralized Syslog Server

Handling Multiline Logs

Some applications generate events that span multiple lines, such as:

• Java stack traces
• Python exceptions
• .NET runtime errors
• Application crash reports

Rather than attempting to decode each line individually, configure log collection to combine related lines into a single event before decoding.

This allows the decoder to process the complete context and improves rule accuracy.

Dynamic Field Extraction

Cloud-native applications frequently introduce new fields without changing the overall log structure.

Dynamic field extraction enables Wazuh to capture these evolving key-value pairs without requiring constant decoder updates.

This technique is especially valuable for:

• Kubernetes audit logs
• Cloud provider logs
• Container platforms
• SaaS application logs
• Security telemetry in JSON format

It allows new fields to become available for searches and detection rules with minimal maintenance.

Improving Decoder Efficiency

Decoder performance becomes increasingly important in environments processing thousands of events per second.

To maximize efficiency:

• Use program_name whenever possible.
• Add a prematch before expensive regex operations.
• Prefer parent-child hierarchies over duplicated logic.
• Keep regular expressions as simple as possible.
• Avoid greedy wildcard expressions unless necessary.
• Reuse existing decoders instead of creating redundant ones.
• Test against diverse real-world log samples before deployment.

The Wazuh documentation recommends designing decoders with selective matching and lightweight regular expressions to minimize processing overhead in high-volume deployments.

Decoder Performance Best Practices

As your Wazuh deployment grows, decoder efficiency becomes increasingly important.

A poorly optimized decoder may only add a few milliseconds of processing time per event, but when a manager is processing hundreds of thousands of logs per minute, those delays accumulate into significant CPU usage and increased analysis latency.

Following these best practices helps keep your decoder library scalable, maintainable, and efficient.

Use Prematch Whenever Possible

A prematch performs a lightweight string comparison before the regex engine is invoked.

Instead of evaluating a complex regular expression against every incoming log, Wazuh first checks for a simple keyword or phrase.

For example:

<prematch>Failed password</prematch>

This prevents expensive regex processing for unrelated events.

Benefits include:

• Lower CPU usage
• Faster event processing
• Fewer unnecessary regex evaluations
• Better scalability

Prematch expressions are one of the easiest ways to improve decoder performance.

Keep Regular Expressions Simple

Regular expressions should capture only the information required by downstream rules.

Avoid patterns that rely heavily on:

• Nested quantifiers
• Multiple wildcard expressions
• Excessive alternation (|)
• Greedy matching
• Unnecessary backtracking

For example, this is usually preferable:

user=(\S+)

instead of:

user=(.*)

Simpler expressions are easier to maintain and generally execute much faster.

Avoid Unnecessary Capture Groups

Every capture group creates additional processing overhead.

Bad example:

(user=)(\S+)(\s+)(src=)(\S+)

Better:

user=(\S+)\s+src=(\S+)

Capture only the values that will actually be referenced by Wazuh rules.

Reuse Parent Decoders

Rather than duplicating matching logic across multiple decoders, create a shared parent decoder.

Example hierarchy:

Firewall
 ├── Allowed
 ├── Blocked
 ├── NAT
 ├── VPN
 └── IDS

Benefits include:

• Less duplicated XML
• Faster matching
• Easier maintenance
• Better organization

Test with Production Log Samples

Synthetic logs rarely capture all of the variations found in production environments.

Instead, test decoders against:

• Normal traffic
• Error conditions
• Malformed logs
• Different software versions
• High-volume datasets

Testing with realistic samples reduces the likelihood of decoder failures after deployment.

Related Guide: Custom Decoder Isn’t Matching: Wazuh Logtest Deep Dive

Organize Custom Decoder Files

Avoid placing every custom decoder inside one massive XML file.

Instead, group decoders by application.

Example directory:

/var/ossec/etc/decoders/
    apache.xml
    firewall.xml
    vpn.xml
    custom_app.xml
    cloud.xml

Benefits include:

• Easier troubleshooting
• Cleaner version control
• Simpler upgrades
• Better collaboration

Document Decoder Logic

Every custom decoder should include documentation explaining:

• Supported application
• Expected log format
• Required fields
• Regex assumptions
• Creation date
• Author
• Related detection rules

Future administrators will thank you when troubleshooting or extending your decoder library.

Benchmark Decoder Performance

High-volume environments should periodically benchmark decoder performance.

Useful metrics include:

• Events processed per second
• CPU utilization
• Regex execution time
• Average analysis latency
• Manager throughput

Monitor Wazuh Manager resource usage after introducing new decoders to ensure they do not become processing bottlenecks.

Minimize False Matches

Broad regular expressions can accidentally match unrelated logs.

For example, a decoder matching every log containing:

error

may execute far more frequently than intended.

Instead, combine multiple matching conditions such as:

• program_name
• prematch
• Parent decoder
• Specific regex patterns

This improves accuracy while reducing unnecessary processing.

Common Wazuh Decoder Problems

Even experienced Wazuh administrators occasionally encounter decoder issues.

\Most problems stem from XML configuration errors, overly broad regular expressions, or unexpected changes in log formats.

The following sections cover the most common decoder problems, along with their symptoms, causes, diagnostic steps, resolutions, and prevention strategies.

Decoder Not Matching Logs

Symptoms

• wazuh-logtest reports No decoder matched.
• Rules never execute.
• Expected fields are missing.
• Alerts are not generated.

Cause

• Incorrect prematch.
• Regex mismatch.
• Unexpected log format.
• Wrong program_name.
• Log structure changed after a software update.

Diagnosis

Use wazuh-logtest with multiple real log samples.

sudo /var/ossec/bin/wazuh-logtest

Verify:

• Parent decoder matches.
• Prematch succeeds.
• Regex captures values correctly.

Resolution

• Update the regex.
• Correct the prematch.
• Modify the program name filter.
• Adjust the decoder for the current log format.

Prevention

• Test against multiple production log samples.
• Review decoders after application upgrades.
• Keep regex patterns flexible enough to handle minor formatting variations.

Regex Captures Incorrect Fields

Symptoms

• Username appears as the IP address.
• Event IDs contain incorrect values.
• Detection rules trigger unexpectedly.
• Dashboard fields are inaccurate.

Cause

• Incorrect capture groups.
• Greedy regex patterns.
• Field order mismatch.

Diagnosis

Review Phase 2 output in wazuh-logtest.

Compare:

• Capture groups
• order
• Extracted values

Resolution

Update either:

• The regex.
• The order element.
• Both, if necessary.

Prevention

Keep capture groups simple and ensure the <order> element exactly matches the sequence of captured values.

Decoder Never Executes

Symptoms

• Decoder is ignored.
• Another decoder always matches first.
• Expected decoder name never appears in testing.

Cause

• Incorrect parent decoder.
• Program name mismatch.
• Prematch never succeeds.
• Decoder hierarchy is incorrect.

Diagnosis

Review decoder hierarchy using wazuh-logtest and verify which decoder matched instead.

Resolution

• Fix parent relationships.
• Update program_name.
• Refine the prematch.
• Reorder decoder logic if appropriate.

Prevention

Build decoder hierarchies carefully and validate parent-child relationships whenever new decoders are added.

Parent Decoder Conflicts

Symptoms

• Child decoders fail to execute.
• Incorrect child decoder matches.
• Fields are extracted inconsistently.

Cause

• Multiple parent decoders match the same log.
• Parent regex is overly broad.
• Child decoders inherit from the wrong parent.

Diagnosis

Review the decoder selected during Phase 2 of wazuh-logtest.

Check:

• Parent names
• Prematch conditions
• Program name filters

Resolution

Make parent decoders more specific by adding:

• program_name
• More selective prematch conditions
• Narrower regex patterns

Prevention

Design parent decoders with clear, non-overlapping responsibilities.

XML Syntax Errors

Symptoms

• Manager fails to start.
• Decoder file is ignored.
• XML parsing errors appear in ossec.log.

Cause

• Missing closing tags.
• Invalid nesting.
• Improper quotation marks.
• Malformed XML.

Diagnosis

Validate the XML:

xmllint --noout /var/ossec/etc/decoders/local_decoder.xml

Also inspect:

sudo tail -f /var/ossec/logs/ossec.log

Resolution

Correct XML formatting errors and reload the Wazuh Manager.

Prevention

Validate every decoder file before deploying it to production.

Incorrect Field Ordering

Symptoms

• Fields contain the wrong values.
• Detection rules evaluate incorrect data.
• Searches return misleading results.

Cause

The <order> element does not match the regex capture groups.

Diagnosis

Compare:

<regex>(\S+) (\S+) (\S+)</regex>

against:

<order>user,action,srcip</order>

Verify that each field corresponds to the correct capture group.

Resolution

Update the order element to match the regex exactly.

Prevention

Whenever you modify a regex, review the order element immediately afterward.

Duplicate Decoder Names

Symptoms

• Unexpected decoder behavior.
• Debugging becomes confusing.
• Decoder output references the wrong configuration.

Cause

Multiple decoder definitions share the same name.

Diagnosis

Search your decoder directory for duplicate names.

Example:

grep -R '<decoder name=' /var/ossec/etc/decoders/

Resolution

Rename one of the conflicting decoders and update any child decoder references if required.

Prevention

Use descriptive, application-specific naming conventions, such as apache-access, custom-auth, or vpn-login, to avoid collisions.

JSON Parsing Failures

Symptoms

• JSON fields are missing.
• Nested objects are not extracted.
• Rules cannot reference expected values.

Cause

• Invalid JSON syntax.
• Incorrect plugin decoder.
• Unsupported log format.
• Malformed payloads.

Diagnosis

Validate the raw log with a JSON validator and verify that the appropriate plugin decoder is configured.

Resolution

• Correct malformed JSON at the source if possible.
• Configure the appropriate JSON plugin decoder.
• Test the corrected payload with wazuh-logtest.

Prevention

Standardize application logging to emit valid JSON and periodically validate sample logs after application updates.

Related Guide: How to Parse Flattened Nested Keys and Arrays in Wazuh JSON Logs

Multiline Logs Not Decoding Properly

Symptoms

• Stack traces appear as multiple unrelated events.
• Fields are missing.
• Decoder matches only the first line.

Cause

The log collector forwards each line separately instead of combining them into a single event.

Diagnosis

Inspect the raw events received by the Wazuh Manager to determine whether multiline entries have already been split before decoding.

Resolution

Configure log collection to join multiline events before they reach the decoder, then update the decoder if necessary to parse the combined message.

Prevention

Test multiline log sources such as Java, Python, and .NET applications whenever logging configurations or application versions change.

Performance Degradation

Symptoms

• High Wazuh Manager CPU usage.
• Increased event processing latency.
• Lower events-per-second throughput.
• Delayed alert generation.

Cause

• Inefficient regular expressions.
• Missing prematch filters.
• Excessive capture groups.
• Duplicate decoders.
• Broad matching conditions.

Diagnosis

Review recently added or modified decoders, monitor manager resource utilization, and compare performance before and after decoder changes.

Resolution

• Simplify regex patterns.
• Add prematch conditions.
• Reuse parent decoders.
• Remove unnecessary capture groups.
• Consolidate redundant decoders.

Prevention

Follow decoder performance best practices, validate changes with production log samples, and benchmark decoder performance before rolling new decoders into production.

Real-World Example

Scenario

A large enterprise operates a custom internal authentication platform used by employees to access business applications.

The application generates detailed security events, including login attempts, session creation, privilege changes, and authentication failures.

However, the application uses a proprietary log format that is not supported by the default Wazuh decoder library.

Example application log:

AUTH_EVENT user=jane.smith src=203.0.113.45 result=failed session=8f29ab31 reason=invalid_password

Because the built-in decoders cannot interpret this format, security analysts create a custom decoder hierarchy.

The team designs a parent decoder responsible for identifying authentication events:

<decoder name="custom-authentication">
    <prematch>AUTH_EVENT</prematch>
</decoder>

Child decoders are then created to handle specific authentication scenarios:

custom-authentication
│
├── successful-login
│
├── failed-login
│
├── session-created
│
└── privilege-change

Each child decoder extracts important security fields:

• Username
• Source IP address
• Authentication result
• Session ID
• Failure reason
• Authentication method

For failed login events, the decoder extracts:

user = jane.smith
srcip = 203.0.113.45
result = failed
session = 8f29ab31
reason = invalid_password

These fields allow the Wazuh rules engine to evaluate the event instead of analyzing raw text.

Decoder Validation Process

Before deploying the decoder into production, analysts test it using:

sudo /var/ossec/bin/wazuh-logtest

They submit multiple log samples:

Successful authentication:

AUTH_EVENT user=admin src=10.10.5.20 result=success session=a91bc22

Failed authentication:

AUTH_EVENT user=jane.smith src=203.0.113.45 result=failed session=8f29ab31 reason=invalid_password

The team verifies that:

• The correct decoder matches.
• All expected fields are extracted.
• Child decoders classify events correctly.
• No unrelated logs trigger the decoder.

Connecting Decoders to Detection Rules

After validating the decoder, analysts create custom detection rules based on the extracted fields.

For example:

• Alert when a privileged account fails authentication repeatedly.
• Detect brute-force login attempts from the same source IP.
• Identify successful logins after multiple failed attempts.
• Track suspicious session creation patterns.

Instead of writing rules against raw log messages, rules can now evaluate structured fields.

Example logic:

IF user = administrator
AND result = failed
AND multiple attempts occur
THEN generate high-severity alert

Related Guide: How to Create Custom Detection Rules in Wazuh (With Examples)

Results and Improvements

After implementing the custom decoder architecture, the organization achieves several improvements.

Improved Visibility

Previously, authentication events appeared as unstructured text, making investigation difficult.

After decoding, analysts can search and correlate:

• User activity
• Source locations
• Authentication failures
• Session identifiers
• Attack patterns

The security team gains a complete view of authentication behavior inside the Wazuh Dashboard.

Faster Incident Response

Because events are properly decoded, analysts no longer need to manually inspect raw logs during investigations.

They can immediately identify:

• Which account was targeted.
• Which IP address initiated the attack.
• Whether authentication succeeded.
• Which session was affected.

This reduces investigation time and improves response efficiency.

Reduced False Positives

Before decoding, detection rules relied on broad text matching.

For example:

failed

could match unrelated application errors.

After decoding, rules use precise fields:

result = failed
event_type = authentication

This improves detection accuracy and reduces unnecessary alerts.

Long-Term Maintainability

By using:

• Parent-child decoder structures
• Documented XML files
• Production log testing
• Reusable field mappings

the security team can easily update the decoder when the application introduces new log formats.

This approach ensures the Wazuh deployment continues providing reliable detection as the environment evolves.

Frequently Asked Questions (FAQ)

Question: What is a Wazuh decoder?

A Wazuh decoder is a component that converts raw log messages into structured fields that the Wazuh rules engine can analyze.

Decoders extract information such as:

• Usernames
• IP addresses
• Event IDs
• Processes
• File paths
• Authentication results

This structured data allows Wazuh rules to detect security events accurately.

Question: What is the difference between a decoder and a rule?

A decoder parses log data, while a rule evaluates the decoded information.

The workflow is:

Raw Log
   ↓
Decoder
   ↓
Structured Fields
   ↓
Rule Evaluation
   ↓
Alert

Example:

Decoder extracts:

username = admin
status = failed
srcip = 192.168.1.50

Rule evaluates:

IF username=admin
AND status=failed
THEN generate alert

Question: Where are Wazuh decoders stored?

Default Wazuh decoders are stored inside:

/var/ossec/ruleset/decoders/

Custom decoders should be stored separately, commonly:

/var/ossec/etc/decoders/local_decoder.xml

or:

/var/ossec/etc/decoders/

Keeping custom decoders separate prevents changes from being overwritten during upgrades.

Question: Can I modify built-in decoders?

Technically, built-in decoders can be modified, but it is not recommended.

Changes made inside the default ruleset may be overwritten during Wazuh upgrades.

The recommended approach is:

• Create custom decoder files.
• Extend existing decoders using parent-child relationships.
• Store organization-specific parsing logic separately.

Question: How do I create a custom decoder?

Creating a custom decoder involves:

1. Identify the log format.
2. Collect real log samples.
3. Create a decoder XML file.
4. Define matching conditions.
5. Build regex patterns.
6. Map extracted values using <order>.
7. Restart Wazuh Manager.
8. Test using wazuh-logtest.

Question: How do I test a decoder?

Use the Wazuh testing utility:

sudo /var/ossec/bin/wazuh-logtest

Paste a sample log and verify:

• The correct decoder matches.
• Fields are extracted correctly.
• Rules trigger as expected.

Testing should always include multiple log variations before production deployment.

Question: What is the purpose of a parent decoder?

A parent decoder provides common matching logic that multiple child decoders can reuse.

For example:

apache
 ├── access logs
 ├── error logs
 └── authentication logs

Benefits include:

• Better organization.
• Faster decoder processing.
• Less duplicate configuration.
• Easier maintenance.

Question: Can Wazuh decode JSON logs?

Yes.

Wazuh supports JSON decoding through its JSON decoder plugin.

JSON logs are commonly generated by:

• Cloud platforms
• Containers
• Kubernetes
• Modern applications
• Security tools

Using JSON decoding avoids complex regex patterns and allows Wazuh to extract structured fields automatically.

Question: Why is my decoder not matching logs?

Common causes include:

• Incorrect regex.
• Incorrect prematch condition.
• Wrong program name.
• Parent decoder mismatch.
• XML syntax problems.
• Log format changes.

Troubleshooting steps:

1. Test the log with wazuh-logtest.
2. Verify the decoder file is loaded.
3. Check regex capture groups.
4. Review extracted fields.
5. Inspect Wazuh Manager logs.

Question: How can I improve decoder performance?

Improve decoder performance by:

• Using prematch conditions.
• Keeping regex patterns simple.
• Avoiding unnecessary capture groups.
• Reusing parent decoders.
• Removing duplicate decoders.
• Testing against real production logs.
• Monitoring Wazuh Manager resource usage.

Efficient decoders reduce CPU usage and help maintain fast alert processing in large environments.

Conclusion

Wazuh decoders are a critical part of the Wazuh log analysis pipeline because they transform raw security events into structured data that detection rules can understand.

Before Wazuh can identify suspicious behavior, it must first correctly interpret the incoming logs.

Accurate decoding ensures that important fields such as usernames, IP addresses, event IDs, processes, and authentication results are available for reliable rule evaluation.

When building custom decoders, follow proven practices:

• Use prematch conditions to reduce unnecessary processing.
• Keep regular expressions simple and efficient.
• Use parent-child decoder relationships for reusable logic.
• Avoid unnecessary capture groups.
• Organize custom decoder files clearly.
• Document parsing assumptions and field mappings.
• Validate every decoder with wazuh-logtest.
• Test against real production log samples.

As applications, cloud services, and security tools continue evolving, log formats will continue changing.

Regularly reviewing and refining Wazuh decoders ensures that your detection pipeline remains accurate, efficient, and capable of identifying emerging threats.