The Complete Custom Wazuh Rules and Decoders Guide

Out of the box, Wazuh can detect thousands of security events across Windows, Linux, macOS, cloud platforms, network devices, containers, and applications. However, every environment eventually produces logs that Wazuh doesn’t understand natively. Custom applications, proprietary software, internally developed APIs, specialized appliances, and third-party SaaS platforms often generate unique log formats that require custom parsing before they become useful security events. This is where Wazuh rules and decoders become essential.

Decoders tell Wazuh how to read and extract information from raw logs, while rules determine whether those extracted fields represent something worth alerting on.

Together, they form the heart of Wazuh’s detection engine, allowing organizations to build highly customized threat detection logic tailored to their infrastructure.

Whether you’re parsing authentication logs from a custom web application, creating Sysmon detections for advanced Windows attacks, monitoring proprietary APIs, or enriching cloud events with custom metadata, understanding how rules and decoders interact is one of the most valuable Wazuh skills you can develop.

In this guide, you’ll learn:

• How the complete Wazuh event processing pipeline works
• The differences between decoders and rules
• When to create custom decoders versus custom rules
• How Wazuh processes JSON, Syslog, Windows, and custom log formats
• Best practices for building scalable, maintainable detection logic
• Common troubleshooting techniques for decoder and rule issues
• Advanced techniques including dynamic fields, parent-child decoders, and Sysmon event detection

By the end of this guide, you’ll understand not only how to build custom Wazuh rules and decoders, but also how to design a detection pipeline that remains accurate, performant, and easy to maintain as your environment grows.

What Are Wazuh Rules and Decoders?

At a high level, every log entering Wazuh passes through two major processing stages:

1. Decoding
2. Rule evaluation

Although they’re closely related, they solve entirely different problems.

Overview of the Wazuh Event Processing Pipeline

A simplified processing flow looks like this:

Log Source
      │
      ▼
Log Collector
      │
      ▼
Pre-decoding
      │
      ▼
Decoder
      │
Extracted Fields
      │
      ▼
Rule Engine
      │
      ▼
Alert Generated
      │
      ▼
Indexer
      │
      ▼
Dashboard

Every stage builds upon the previous one.

If a decoder fails, the rule engine has little or no structured data to evaluate.

What Decoders Do

A decoder converts unstructured log text into structured fields that Wazuh can understand.

For example, consider the raw authentication log:

User=jdoe IP=192.168.10.25 Status=Failed

A decoder extracts information such as:

• Username
• Source IP
• Authentication result
• Timestamp
• Session ID
• Hostname
• Event category

After decoding, the event becomes structured:

username = jdoe
srcip = 192.168.10.25
status = Failed

Instead of searching raw text repeatedly, Wazuh evaluates structured fields much more efficiently.

Custom decoders become necessary whenever:

• Wazuh doesn’t recognize a log format
• New fields need to be extracted
• Vendor logs contain proprietary structures
• Nested JSON requires custom parsing
• Multiple log formats share common prefixes

Related Guide: Wazuh Decoder Guide

What Rules Do

Rules evaluate decoded events and determine whether they represent normal activity, suspicious behavior, or confirmed security incidents.

A rule can examine:

• Extracted usernames
• Source IP addresses
• Event IDs
• File paths
• Process names
• Registry keys
• Network ports
• Parent processes
• Dynamic fields
• Previous matching events

For example:

IF

status = Failed

AND

username = administrator

THEN

Generate Alert Level 10

Rules can also:

• Correlate multiple events
• Detect brute-force attacks
• Identify privilege escalation
• Detect malware behavior
• Trigger Active Response
• Suppress false positives

Unlike decoders, rules never parse raw logs, they rely entirely on decoded fields.

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

How Decoders and Rules Work Together

Think of decoders and rules as two consecutive stages.

The decoder answers:

“What information exists inside this log?”

The rule answers:

“Does this information indicate something important?”

Without a decoder:

Raw Log

↓

No extracted fields

↓

Rules cannot match correctly

Without rules:

Fields extracted successfully

↓

No alert generated

Only when both components work together can Wazuh transform raw log data into actionable security alerts.

This separation also improves maintainability.

Multiple rules can reuse the same decoder, while a single rule can apply to logs parsed by different decoders, reducing duplication across your ruleset.

Why Custom Rules and Decoders Are Important

The default Wazuh ruleset supports thousands of event types, but no security platform can anticipate every organization’s infrastructure.

Custom rules and decoders allow security teams to monitor:

• Internal applications
• Proprietary software
• Manufacturing systems
• Industrial control systems
• Cloud-native services
• Business-specific workflows
• Custom APIs
• Third-party SaaS platforms

Organizations also use custom rules to:

• Reduce false positives
• Add organization-specific detection logic
• Enforce compliance requirements
• Detect insider threats
• Monitor sensitive assets
• Identify business logic abuse

According to the MITRE ATT&CK framework, effective detection engineering depends on collecting relevant telemetry and creating detection logic tailored to an organization’s environment rather than relying solely on default signatures.

Guidance from NIST Special Publication 800-61 Rev. 2 (Computer Security Incident Handling Guide) also emphasizes the importance of customizing monitoring and detection capabilities to align with organizational risks and incident response processes.

Common Use Cases for Customization

Custom rules and decoders are commonly used for:

• Monitoring custom authentication systems
• Parsing proprietary application logs
• Detecting API abuse
• Identifying suspicious PowerShell activity
• Monitoring Kubernetes workloads
• Creating cloud-specific detections
• Parsing firewall logs unsupported by default decoders
• Monitoring database audit logs
• Building ransomware detections
• Creating compliance-specific alerts
• Monitoring industrial equipment
• Correlating business events with security events

Advanced users also customize Sysmon rules to detect:

• Credential dumping
• Process injection
• DLL sideloading
• Encoded PowerShell
• LOLBins
• Lateral movement

Related Guide: Step-by-Step: Custom Wazuh Sysmon Rules Guide

How Wazuh Processes Logs

Understanding the complete event processing pipeline makes it much easier to troubleshoot why alerts fail, decoders don’t match, or rules never execute.

Every event follows a predictable sequence before appearing in the Wazuh Dashboard.

Log Collection

Everything begins with log collection.

The Wazuh agent (or manager) gathers logs from sources such as:

• Linux system logs
• Windows Event Logs
• Sysmon
• Authentication logs
• Firewalls
• Cloud services
• Containers
• Web servers
• Databases
• APIs
• Syslog devices

Logs are forwarded to the Wazuh manager through encrypted communication channels, where they enter the analysis engine.

Different collection modules normalize timestamps and metadata before the logs continue through the pipeline.

Pre-decoding

Before attempting to decode the log, Wazuh performs a lightweight parsing phase called pre-decoding.

This stage extracts universal metadata such as:

• Timestamp
• Hostname
• Program name
• Syslog priority
• Log source

For Syslog messages, Wazuh separates the Syslog header from the message body.

Example:

Jul 18 09:41:22 server01 sshd[1122]:

Produces:

hostname = server01

program_name = sshd

timestamp = Jul 18 09:41:22

This metadata helps determine which decoder should process the remaining message.

Decoding

Once pre-decoding finishes, Wazuh evaluates available decoders.

Each decoder attempts to match the log using:

• Program name
• Prematch expressions
• Regular expressions
• JSON parsers
• Parent decoders
• Child decoders

If a decoder matches successfully, Wazuh extracts structured fields such as:

• Username
• Source IP
• Destination IP
• Process name
• Command line
• Registry key
• URL
• File path
• Hash
• User agent
• Session ID

The quality of your decoder largely determines how effective downstream rule matching will be.

Related Guide: How to Use Wazuh Dynamic Fields to Extract Custom Log Data

Rule Evaluation

Once fields have been extracted, the rule engine begins evaluating events.

Rules can inspect:

• Static fields
• Dynamic fields
• Previous events
• Time windows
• Frequency thresholds
• Groups
• MITRE mappings
• Compliance tags

Rule conditions may include:

if_sid

if_group

match

regex

field

frequency

timeframe

same_source_ip

same_user

Rules execute in sequence until the highest-priority applicable alert is produced.

Alert Generation

When a rule matches successfully, Wazuh creates an alert containing:

• Rule ID
• Severity level
• Description
• Extracted fields
• MITRE ATT&CK mappings
• Compliance mappings (PCI DSS, HIPAA, GDPR, etc.)
• Agent information
• Original log
• Timestamp

This structured alert is significantly easier to search, correlate, and investigate than the original raw log.

Indexing and Dashboard Visualization

Generated alerts are forwarded to the Wazuh Indexer, where they’re indexed for searching and analytics.

The Wazuh Dashboard enables analysts to:

• Search alerts
• Filter by rule
• Investigate timelines
• Build dashboards
• Create visualizations
• Run threat hunting queries
• Correlate related events

Well-designed decoders also improve searchability because extracted fields become individually searchable rather than remaining embedded in raw log text.

Active Response Integration

After an alert is generated, Wazuh can automatically execute predefined response actions.

Examples include:

• Blocking malicious IP addresses
• Disabling compromised user accounts
• Killing suspicious processes
• Isolating endpoints
• Updating firewall rules
• Executing custom scripts

This automation allows organizations to reduce response times for high-confidence detections.

Related Guide: How to Configure Wazuh Active Response

Understanding Wazuh Decoders

Decoders are the foundation of every custom detection workflow.

If logs aren’t parsed correctly, even perfectly written rules won’t produce accurate alerts.

Understanding how decoders operate helps you build reliable, scalable parsing logic for virtually any log source.

What Is a Decoder?

A decoder is an XML definition that tells Wazuh how to identify a particular log format and extract useful information from it.

Rather than inspecting every possible rule against raw text, Wazuh first converts logs into structured data.

Typical extracted values include:

• Username
• Source IP
• Destination IP
• Process
• Event ID
• File path
• Registry key
• URL
• Hash
• Command line
• Device name
• Session ID

These structured fields become available for rule evaluation, dashboards, searches, and automated responses.

Parent vs Child Decoders

Large log formats often share common prefixes.

Instead of duplicating parsing logic, Wazuh supports hierarchical decoders.

A parent decoder identifies the general log type.

Example:

CustomApp:

Child decoders then parse specific message variations.

For example:

1. Child 1:

Login Success

2. Child 2:

Login Failed

3. Child 3:

Password Changed

Benefits include:

• Less duplicated XML
• Easier maintenance
• Better performance
• More modular parsing logic
• Cleaner rule design

Related Guide: How to Map Complex Log Fields Using Wazuh Parent Child Rules

Static and Dynamic Fields

Wazuh supports two categories of extracted fields.

Static fields are predefined by Wazuh.

Examples include:

• srcip
• dstip
• user
• hostname
• id
• status

These integrate seamlessly with built-in rules.

Dynamic fields allow you to extract virtually any custom value.

Examples:

• customer_id
• tenant_name
• api_endpoint
• device_score
• transaction_id
• application_role
• session_token

Dynamic fields are especially valuable for monitoring proprietary applications and business-specific workflows.

Regex and PCRE2 Support

Most decoders use regular expressions to identify and capture log data.

Wazuh supports traditional POSIX regular expressions as well as PCRE2, enabling advanced pattern matching features such as lookarounds, atomic groups, and more expressive capture logic where appropriate.

PCRE2 can simplify parsing of complex or inconsistent log formats, though overly complex expressions should be used carefully to avoid unnecessary processing overhead.

The Wazuh documentation recommends keeping expressions as specific and efficient as possible to improve decoder performance and reduce false matches.

JSON Decoders

Modern applications increasingly generate structured JSON logs.

Unlike plain-text parsing, JSON decoders access fields directly.

Example:

{
  "username":"alice",
  "action":"login",
  "status":"failed"
}

Fields can be extracted without relying on lengthy regular expressions, making JSON parsing more reliable and easier to maintain as schemas evolve.

Dynamic Field Extraction

Dynamic field extraction allows security teams to retain valuable business context that doesn’t fit Wazuh’s predefined schema.

Common examples include:

• Customer IDs
• Tenant IDs
• Order numbers
• Device fingerprints
• Risk scores
• API versions
• Subscription plans
• Session identifiers

This additional context enables more precise detection logic and richer investigations, especially in multi-tenant or custom application environments.

Related Guide: How to Use Wazuh Dynamic Fields to Extract Custom Log Data

Decoder Matching Order

When processing an event, Wazuh evaluates decoders in a defined order until it finds the appropriate match.

In general, the process follows this pattern:

1. Pre-decoding extracts basic metadata.
2. Candidate decoders are filtered using attributes such as program_name or prematch.
3. Parent decoders identify the overall log family.
4. Child decoders refine parsing for specific message types.
5. Matching regular expressions or JSON extraction rules capture the required fields.

Designing decoders with selective prematch expressions and logical parent-child hierarchies reduces unnecessary evaluations and improves performance in large environments.

Decoder Best Practices

When building custom decoders:

• Keep each decoder focused on a single log format.
• Use parent-child hierarchies to eliminate duplicated parsing logic.
• Prefer JSON parsing over regular expressions when structured logs are available.
• Extract only the fields needed for detection and investigation.
• Use descriptive names for custom dynamic fields.
• Test every decoder with wazuh-logtest before deploying to production.
• Store custom decoders separately from the default ruleset to simplify upgrades.
• Validate changes in a staging environment before rolling them out broadly.

These practices improve long-term maintainability, minimize false matches, and make it easier to extend your detection pipeline as new log sources are introduced.

Related Guide: How to Use Wazuh Logtest

Understanding Wazuh Rules

Rules are the intelligence layer of Wazuh’s detection engine.

After decoders extract structured information from raw logs, rules analyze that data to determine whether an event is informational, suspicious, or malicious.

Every alert displayed in the Wazuh Dashboard is the result of one or more rules successfully matching decoded fields.

Well-designed rules enable security teams to detect attacks, reduce false positives, correlate related events, trigger automated responses, and map detections to industry security frameworks.

Rule IDs

Every Wazuh rule must have a unique numeric rule ID.

For example:

<rule id="100500" level="10">

The rule ID uniquely identifies the detection logic and allows other rules to reference it.

Rule IDs are commonly used with directives such as:

• if_sid
• if_matched_sid
• if_group
• if_matched_group

These references enable rules to build upon previous detections instead of evaluating every event independently.

When creating custom rules, avoid modifying the default Wazuh rules directly.

Instead, assign custom rule IDs within your organization’s designated range and store them in local rule files. This approach simplifies upgrades and prevents your customizations from being overwritten.

Related Guide: How to Safely Overwrite Local Rule IDs Without Wazuh Conflicts

Rule Levels

Every rule contains a level attribute that represents the severity of the generated alert.

Higher levels indicate events that deserve greater attention from security analysts.

A common guideline is:

For example:

• Successful user login → Level 3
• Failed administrator login → Level 7
• Malware detected → Level 12
• Confirmed ransomware behavior → Level 15

Consistent severity assignments help analysts prioritize investigations and reduce alert fatigue.

Rule Conditions

Rules evaluate one or more conditions before generating an alert.

Conditions can inspect:

• Decoded fields
• Static fields
• Dynamic fields
• Event IDs
• Process names
• File paths
• Registry keys
• Command lines
• Source IP addresses
• Usernames
• Previous rule matches

A simplified example:

status = failed

AND

username = administrator

AND

srcip = 192.168.1.25

Only when every required condition is satisfied does the rule trigger.

Rules may also use:

• Exact matches
• Regular expressions
• Wildcards
• Numeric comparisons
• String comparisons
• Field existence checks

Combining multiple conditions generally produces more accurate detections than relying on a single field.

Rule Groups

Rule groups categorize related detections.

Examples include:

• authentication
• ssh
• windows
• sysmon
• malware
• web
• firewall
• cloud
• vulnerability_detection
• compliance

Groups simplify:

• Rule organization
• Dashboard searches
• Alert filtering
• Rule inheritance
• Reporting

For example, every SSH authentication rule can belong to the authentication and ssh groups while still detecting different attack techniques.

Grouping related rules also makes long-term maintenance much easier as custom rulesets grow.

Frequency and Timeframe Correlation

Many attacks consist of repeated events rather than a single suspicious log entry.

Wazuh allows rules to correlate activity over time using frequency and timeframe conditions.

Examples include:

• Five failed logins within two minutes
• Twenty PowerShell executions in one minute
• Multiple privilege escalation attempts
• Repeated malware detections on the same endpoint

Instead of generating five individual alerts, Wazuh can generate one higher-confidence alert indicating a possible attack.

This greatly reduces alert noise while improving detection accuracy.

Common use cases include:

• Brute-force attacks
• Password spraying
• Port scanning
• Web enumeration
• Credential stuffing
• Denial-of-service attacks

Related Guide: Wazuh Brute Force Detection Guide

Rule Chaining

Rule chaining allows multiple rules to build upon each other.

Rather than creating one large, complicated rule, Wazuh encourages smaller rules that reference previous detections.

For example:

Rule 100100

↓

Failed Login

↓

Rule 100200

↓

Five Failed Logins

↓

Rule 100300

↓

Possible SSH Brute Force

↓

Rule 100400

↓

Trigger Active Response

This layered design provides several benefits:

• Easier troubleshooting
• Better rule reuse
• Reduced duplication
• Simpler maintenance
• Improved readability

Rule chaining is commonly implemented using directives such as if_sid and if_matched_sid, allowing higher-level detections to build on simpler foundational rules.

MITRE ATT&CK Mapping

Modern detection engineering extends beyond simply generating alerts.

Analysts also need to understand which attacker techniques those alerts represent.

Wazuh supports mapping rules to the MITRE ATT&CK framework.

For example:

These mappings help:

• Prioritize investigations
• Perform threat hunting
• Measure detection coverage
• Identify gaps in monitoring
• Standardize reporting across security teams

The MITRE ATT&CK framework is widely recognized as the industry standard for documenting adversary tactics, techniques, and procedures (TTPs).

Compliance Mapping (PCI DSS, HIPAA, NIST, GDPR)

In addition to ATT&CK mappings, Wazuh rules can include references to major compliance frameworks.

Common examples include:

• PCI DSS
• HIPAA
• NIST Cybersecurity Framework
• GDPR
• CIS Controls

Compliance mappings help organizations:

• Demonstrate security monitoring
• Produce audit reports
• Track regulatory requirements
• Simplify compliance assessments

For example, authentication monitoring rules may contribute toward PCI DSS requirements for access control and logging, while file integrity monitoring supports multiple compliance standards requiring change detection.

The NIST Cybersecurity Framework (CSF) 2.0 emphasizes continuous security monitoring and event detection as key capabilities for identifying cybersecurity incidents.

Active Response Integration

Rules don’t have to stop at generating alerts.

High-confidence detections can automatically trigger Active Response actions.

Examples include:

• Blocking an IP address
• Disabling a compromised account
• Killing a malicious process
• Isolating a host
• Updating firewall rules
• Running custom response scripts

For example:

Rule Matches

↓

Alert Generated

↓

Active Response Triggered

↓

Firewall Blocks Source IP

Automating response actions helps reduce attacker dwell time and allows security teams to react to threats within seconds instead of minutes or hours.

When implementing Active Response, it’s important to carefully tune rules and thoroughly test them in a non-production environment to avoid unintended disruptions caused by false positives.

Related Guide: How to Configure Wazuh Active Response

How Rules and Decoders Work Together

Rules and decoders are designed to complement one another.

Decoders transform raw log data into structured fields, while rules evaluate those fields to determine whether an alert should be generated.

Neither component is particularly useful on its own.

A decoder without rules only parses data, while a rule without decoded fields has little meaningful information to evaluate.

Together, they form the complete detection pipeline.

Event Processing Workflow

Every event follows a predictable sequence inside Wazuh.

Raw Log

↓

Log Collection

↓

Pre-decoding

↓

Decoder

↓

Extracted Fields

↓

Rule Evaluation

↓

Alert

↓

Indexer

↓

Dashboard

↓

Active Response (Optional)

Each stage depends on the successful completion of the previous stage.

Decoder Extracts Data

Consider the following raw log:

User=jdoe IP=192.168.1.50 Status=Failed

A decoder extracts structured information such as:

username = jdoe

srcip = 192.168.1.50

status = Failed

Instead of evaluating raw text repeatedly, Wazuh now works with structured fields that can be searched, correlated, and indexed efficiently.

Rule Evaluates Extracted Fields

Once decoding completes, rules inspect the extracted values.

For example:

IF

status = Failed

AND

username = administrator

THEN

Generate Level 10 Alert

Rules may also inspect:

• Previous events
• Time windows
• Frequency thresholds
• Dynamic fields
• Parent rule matches
• Rule groups

This separation keeps the parsing logic independent from the detection logic.

Alert Generation

If all rule conditions are satisfied, Wazuh generates a structured alert.

Typical alert information includes:

• Rule ID
• Severity
• Description
• Timestamp
• Agent
• Original log
• Decoded fields
• MITRE ATT&CK mapping
• Compliance references

The alert is then indexed for searching, visualization, and automated response.

Practical Processing Example

Imagine a custom web application produces the following log:

LOGIN user=alice ip=198.51.100.20 result=failed

Step 1 — Decoder

The decoder extracts:

user = alice

srcip = 198.51.100.20

result = failed

Step 2 — Rule

A custom rule evaluates:

result = failed

The rule generates a level 5 authentication failure alert.

Step 3 — Correlation Rule

A second rule detects:

• Five failed logins
• Same IP address
• Two-minute window

A higher-severity brute-force alert is generated.

Step 4 — Active Response

The firewall automatically blocks the attacking IP address for a predefined period.

This layered workflow illustrates how decoders, rules, correlation logic, and automated responses work together to detect and mitigate threats.

Common Design Patterns

Experienced Wazuh administrators often follow several design patterns when creating custom detection content.

One Decoder, Many Rules

A single decoder extracts reusable fields that multiple rules evaluate.

Example:

Authentication Decoder

↓

Failed Login Rule

↓

Successful Login Rule

↓

Impossible Travel Rule

↓

Privilege Escalation Rule

This avoids duplicating parsing logic.

Parent-Child Decoder Hierarchy

Use parent decoders for shared log prefixes and child decoders for specific event types.

Benefits include:

• Less XML duplication
• Easier maintenance
• Better scalability

Related Guide: How to Map Complex Log Fields Using Wazuh Parent Child Rules

Multi-Stage Detection

Build simple foundational rules before creating advanced correlation rules.

For example:

Rule A

↓

Rule B

↓

Rule C

Each layer increases detection confidence while minimizing false positives.

Dynamic Field Design

Extract business-specific information using dynamic fields rather than forcing custom data into predefined Wazuh fields.

Examples include:

• Customer ID
• API endpoint
• Tenant ID
• Risk score
• Subscription plan

This approach produces more flexible and maintainable detection logic.

Related Guide: How to Use Wazuh Dynamic Fields to Extract Custom Log Data

Creating Your First Custom Decoder

Creating a custom decoder is often the first step toward supporting a new log source in Wazuh.

The process involves identifying the log structure, extracting the fields you need, validating the parser, and deploying it so that rules can evaluate the resulting data.

Identify the Log Format

Before writing any XML, collect several examples of the logs you want to parse.

Look for:

• Fixed prefixes
• Consistent delimiters
• Key-value pairs
• Timestamps
• Usernames
• IP addresses
• Event IDs
• JSON structures
• Optional fields

Comparing multiple samples helps you identify which parts of the log are constant and which parts vary, making it easier to design a reliable decoder.

Create the Decoder XML

Create a new decoder file inside your custom decoder directory (commonly local_decoder.xml or another custom XML file included by Wazuh).

A basic decoder typically defines:

• A unique decoder name
• A prematch expression to identify the log type
• One or more regular expressions or JSON parsing directives
• The order in which captured fields are assigned

Using a prematch filter helps Wazuh skip unrelated logs and improves parsing performance.

Extract Required Fields

Next, determine which values should become searchable fields.

Common fields include:

• Username
• Source IP
• Destination IP
• Hostname
• Event type
• Status
• Process name
• File path
• URL
• Session ID

Avoid extracting every possible value.

Instead, focus on the information required for detection, investigation, reporting, and correlation.

If your application generates business-specific metadata, consider using dynamic fields with descriptive names rather than repurposing built-in fields.

Related Guide: How to Use Wazuh Dynamic Fields to Extract Custom Log Data

Validate with wazuh-logtest

Always validate new decoders before deploying them.

The wazuh-logtest utility shows:

• Which decoder matched
• Extracted fields
• Rule matches
• Generated alerts
• Parsing errors

Testing with multiple log samples, including valid, malformed, and unexpected inputs, helps identify parsing issues early and reduces the risk of missed detections in production.

Related Guides:

• How to Use Wazuh Logtest
•  Troubleshooting wazuh-logtest: Why Alerts Are Missing from JSON Output

Deploy the Decoder

Once validation is complete:

1. Save the decoder XML in your custom decoder directory.
2. Ensure the file is included in the Wazuh configuration.
3. Restart or reload the Wazuh manager so the new decoder is loaded.
4. Confirm there are no syntax errors in the manager logs.

Keeping custom decoders separate from the default ruleset makes future Wazuh upgrades significantly easier because your customizations won’t be overwritten.

Verify Successful Parsing

After deployment, generate test events that match your new log format and verify that:

• The correct decoder is selected.
• All required fields are extracted.
• No parsing warnings or errors appear.
• Expected rules trigger successfully.
• Alerts are visible in the Wazuh Dashboard.
• Extracted fields can be searched and filtered.

Successful parsing confirms that your decoder is ready for production use and provides a solid foundation for building custom detection rules on top of the newly structured data.

<rule id="100500" level="8">

username = administrator

srcip = 198.51.100.10

status = failed

status = failed

AND

username = administrator

{
  "user": "alice",
  "action": "login",
  "status": "failed",
  "srcip": "198.51.100.25"
}

{
  "user": {
    "name": "alice",
    "role": "administrator"
  },
  "network": {
    "srcip": "198.51.100.25"
  }
}

{
  "roles": [
    "admin",
    "developer"
  ]
}

Initial Access

↓

Credential Discovery

↓

Privilege Escalation

↓

Lateral Movement

↓

Data Collection

↓

Exfiltration

Parent Rule

Windows Process Creation

        |

        |

Child Rule 1

PowerShell Execution

        |

Child Rule 2

Encoded PowerShell Command

        |

Child Rule 3

PowerShell Downloading Remote Payload

10 failed authentication attempts

FROM

same source IP

WITHIN

60 seconds

Failed Login

↓

Successful Login

↓

Same User

↓

Within 5 Minutes

New User Created

↓

User Added to Administrators Group

↓

Privileged Command Executed

↓

Within 10 Minutes

Exclude:

scanner.company.com

backup-service-account

Any PowerShell execution

PowerShell execution

AND

Encoded command detected

AND

Unknown user

3 failed logins

15 failed logins within 5 minutes

Outbound connection to suspicious IP

Unknown process created network connection

User logged in shortly before activity

LOGIN user=john ip=203.0.113.20 result=failed application=customer_portal

username=john

srcip=203.0.113.20

status=failed

application=customer_portal

Failed login

AND

Application = customer_portal

AND

Multiple failures from same IP

Possible customer portal brute-force attack

Event ID 4720

+

New administrator account created

Unauthorized privileged account creation

Multiple failed SSH attempts

+

Successful login

+

Privilege escalation

Potential compromised SSH account

Process:

powershell.exe

AND

Command contains:

-EncodedCommand

AND

Parent process:

winword.exe

Possible malicious document execution

Suricata alert

+

Internal host connection

+

Known malicious IP

Possible malware infection

{
 "eventName":"CreateUser",
 "user":"admin"
}

Unexpected cloud account creation

{
 "verb":"create",
 "resource":"pods",
 "namespace":"production"
}

New workload created in production namespace

wazuh/
│
├── decoders/
│   ├── applications.xml
│   ├── cloud.xml
│   ├── firewall.xml
│   └── custom-auth.xml
│
├── rules/
│   ├── authentication.xml
│   ├── malware.xml
│   ├── cloud.xml
│   └── compliance.xml
│
└── documentation/
    ├── detection-notes.md
    └── changelog.md

rules/
|
├── authentication_rules.xml
├── malware_rules.xml
├── sysmon_rules.xml
├── cloud_rules.xml
└── compliance_rules.xml

custom_cloudtrail_rules.xml

rules2.xml

customer_id

api_risk_score

tenant_name

field1

custom_value

Create Change

↓

Review

↓

Test

↓

Deploy

↓

Monitor

Rule Name:
Suspicious Admin Login

Purpose:
Detect unexpected administrator authentication.

Source:
Custom VPN logs.

False Positives:
Approved maintenance windows.

Response:
Investigate source IP.

LOGIN user=admin ip=192.168.1.10 status=failed

user=(.*) status=(.*)

user=(\S+) ip=(\S+) status=(\S+)

<rule id="100500">

<rule id="100500">

field:

customer_role

equals:

administrator

username

srcip

status

Rule 1:

Any PowerShell execution

Level 10


Rule 2:

Malicious encoded PowerShell

Level 14

General Detection

↓

Specific Detection

↓

High Confidence Alert

<rule id="100500">

<description>
Test Rule
</rule>

<rule id="100500">

<description>
Test Rule
</description>

</rule>

Detect every PowerShell execution

Detect PowerShell execution

AND

Encoded command

AND

External network connection

.*user=.*status=.*.*

user=(\S+)\sstatus=(\S+)

Application Decoder

↓

Authentication Decoder

↓

Authorization Decoder

↓

API Decoder

100 failed logins

within

24 hours

10 failed logins

within

5 minutes

Check application name

↓

Check event type

↓

Run detailed matching

Log Collection

↓

Decoder

↓

Extracted Fields

↓

Rule Matching

↓

Alert

↓

Dashboard

wazuh-logtest

{
"user":{
"name":"alice"
}
}

username

Unknown Log Format

↓

Create Decoder

↓

Extract Fields

↓

Create Rule

↓

Generate Alert

/var/ossec/etc/rules/

/var/ossec/etc/decoders/

wazuh-logtest